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[]	The models to compose into the target, each emitted as a GraphQL interface.

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;

@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[]	The operations, or interfaces of operations, to add to the target as fields.

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	Options for the schema, such as its name.

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;