Decorators

TypeSpec.GraphQL

@compose

Specify the GraphQL interfaces that should be implemented by a model. The interfaces must be decorated with the @graphqlInterface decorator, and all of the interfaces’ properties must be present and compatible.

@TypeSpec.GraphQL.compose(...interfaces: Model[])

Target

Model

Parameters

Name	Type	Description
interfaces	Model[]

Examples

@graphqlInterface(#{ interfaceOnly: true })
model Node {
  id: string;
}

@compose(Node)
model User {
  ...Node;
  name: string;
}

@graphqlInterface

Mark this model as a GraphQL Interface. Interfaces can be implemented by other models using the @compose decorator.

@TypeSpec.GraphQL.graphqlInterface(options?: valueof { interfaceOnly: boolean })

Target

Model

Parameters

Name	Type	Description
options	valueof {...}	.interfaceOnly When true, the model will only be emitted as an interface (no “Interface” suffix is added to the name). Use this for abstract interfaces that will never be used directly as output/input types (e.g., Node, Connection). Defaults to false.

Examples

@graphqlInterface(#{ interfaceOnly: true })
model Node {
  id: string;
}

@compose(Node)
model User {
  ...Node;
  name: string;
}
// Emits: interface Node { id: String! }
//        type User implements Node { id: String!; name: String! }

@mutation

Specify the GraphQL Operation kind for the target operation to be MUTATION.

@TypeSpec.GraphQL.mutation

Target

Operation

Parameters

None

Examples

@mutation op createUser(name: string): User;

@nullable

Mark a field, operation, or type as nullable in the emitted GraphQL schema.

Applied automatically by the mutation engine when it strips | null from union types. The decorator’s presence on the type’s decorators array is the signal — the implementation is a no-op.

@TypeSpec.GraphQL.nullable

Target

ModelProperty | Operation | Union | Model

Parameters

None

@nullableElements

Mark a field or operation as having nullable array elements in the emitted GraphQL schema.

Applied automatically by the mutation engine when it detects Array<T | null> patterns. Causes the emitter to emit [T] instead of [T!].

@TypeSpec.GraphQL.nullableElements

Target

ModelProperty | Operation

Parameters

None

@oneOf

Mark a model as a @oneOf input object in the emitted GraphQL schema.

This decorator is applied automatically by the mutation engine when it converts a union type in input context to a synthetic input object (since GraphQL unions are output-only). The emitter uses this to emit the @oneOf directive.

@TypeSpec.GraphQL.oneOf

Target

Model

Parameters

None

@operationFields

Assign one or more operations or interfaces to act as fields with arguments on a model. The operations become fields on the GraphQL type with their parameters as arguments.

@TypeSpec.GraphQL.operationFields(...operations: Operation | Interface[])

Target

Model

Parameters

Name	Type	Description
operations	Operation | Interface[]

Examples

op followers(query: string): Person[];

@operationFields(followers)
model Person {
  name: string;
}
// Emits: type Person { name: String!; followers(query: String!): [Person!]! }

@query

Specify the GraphQL Operation kind for the target operation to be QUERY.

@TypeSpec.GraphQL.query

Target

Operation

Parameters

None

Examples

@query op getUser(id: string): User;

@schema

Mark this namespace as describing a GraphQL schema and configure schema properties. All types and operations within the namespace will be emitted to a single GraphQL schema file.

@TypeSpec.GraphQL.schema(options?: valueof TypeSpec.GraphQL.Schema.SchemaOptions)

Target

Namespace

Parameters

Name	Type	Description
options	valueof SchemaOptions

Examples

@schema(#{ name: "MyAPI" })
namespace MyAPI {
  model User {
    id: string;
    name: string;
  }
  @query op getUser(id: string): User;
}
// Emits: MyAPI.graphql

@specifiedBy

Provide a specification URL for a custom GraphQL scalar type. This maps to the @specifiedBy directive in the emitted GraphQL schema.

@TypeSpec.GraphQL.specifiedBy(url: valueof url)

Target

Scalar

Parameters

Name	Type	Description
url	valueof url	URL to the scalar type specification

Examples

@specifiedBy("https://scalars.graphql.org/andimarek/date-time")
scalar DateTime extends utcDateTime;

@subscription

Specify the GraphQL Operation kind for the target operation to be SUBSCRIPTION.

@TypeSpec.GraphQL.subscription

Target

Operation

Parameters

None

Examples

@subscription op onUserCreated(): User;