Directives

For more information: GraphQL specification

GraphQLDirective allows you to provide more information about different elements of your schema and queries.

The default skip, include, deprecated and specifiedBy directives are provided. Fields in the different type system definition classes allow you to include the deprecated reason for fields or enum values, and a url of the specification for scalar types. This information will be printed when using the printSchema utility, can be retrieved in Dart through GraphQL extension for modifying the behavior of request execution or, if introspection is enabled, will be exposed by the GraphQL server.

The skip and include directives are supported during document execution following the spec. Right now, custom directives on execution can be obtained by using the parsed DocumentNode from package:gql, in the future better support could be implemented.

Provide custom directives supported by your server through the GraphQLSchema.directives field.

You can retrieve custom directives values in your GraphQL Schema definition when using the buildSchema utility, which will parse all directives and leave them accessible through the astNode Dart fields in the different GraphQL elements. Setting custom directives values through the GraphQL Schema Dart classes is a work in progress. Right now, you can add DirectiveNodes to the element's attachments if you want to print it with printSchema, however the API will probably change. See https://github.com/graphql/graphql-js/issues/1343

KeyDirective

Specifies that a given Object can be identified by the fields passed as argument to the directive

It is repeatable, there can be multiple keys per Object.

The following example shows an Object that can be identified by two keys, the "id" field and the combination "type" and "nested.value" fields.

type Model @key(fields: "id") @key(fields: "type nested { value } ") {
  id: String!
  type: String!
  nested {
    value: int!
  }
}

ValidaDirective

Using package:valida, the valida directive represents the validation configuration. At the moment the ValidaField annotation over arguments and input fields is used to populated the valida directive. For example, the following annotated GraphQLInput that verifies that all lengths inside the strs field have at least 1 byte length:

@Valida()
@GraphQLInput()
class ValidaArgModel {
  @ValidaList(each: ValidaString(minLength: 1))
  final List<String> strs;
  final ValidaArgModel? inner;

  ValidaArgModel({
    required this.strs,
    this.inner,
  });

  Map<String, Object?> toJson() {
    return {
      'strs': strs,
      'inner': inner?.toJson(),
    };
  }

  factory ValidaArgModel.fromJson(Map<String, Object?> map) {
    return ValidaArgModel(
      strs: List<String>.from(map['strs']! as List),
      inner: map['inner'] != null
          ? ValidaArgModel.fromJson((map['inner']! as Map).cast())
          : null,
    );
  }
}

Will generate the following GraphQL definition with valida directive.

input ValidaArgModel {
  strs: [String!]! @valida(jsonSpec: """
{"variantType":"list","each":{"variantType":"string","minLength":1}}
""")
  inner: ValidaArgModel
}

In this case the JSON '{"variantType":"list","each":{"variantType":"string","minLength":1}}' is the result of executing the annotation's (ValidaList(each: ValidaString(minLength: 1))) toJson method.