クエリ短縮形

ドキュメントに操作が1つだけ含まれ、その操作が変数を定義せずディレクティブも適用されていないクエリである場合、その操作は query キーワードと操作名を省略する短縮形で表現できます。

例えば、次の無名クエリ操作はクエリ短縮形で書かれています。

Example № 5{
  field
}

クエリ短縮形には説明（Descriptions）は許されません。

引数は順不同

引数は任意の構文順で与えても、意味的には同じです。

次の二つの操作は意味的に同一です:

Example № 11{
  picture(width: 200, height: 100)
}

Example № 12{
  picture(height: 100, width: 200)
}

フラグメント内での変数の使用

変数はフラグメント内で使用できます。変数は特定の操作に対してグローバルスコープを持つため、フラグメント内で使用される変数は、そのフラグメントを（推移的に）利用するトップレベルの操作で宣言されていなければなりません。もしフラグメント内で参照される変数が、その変数を定義していない操作により含まれている場合、その操作は無効です（参照: All Variable Uses Defined）。

意味論

ディレクティブの順序は重要

ディレクティブは特定の構文上の順序で提供でき、その順序が意味を持つ場合があります。

例えば、次の二つの型定義は異なる意味を持つかもしれません：

Example № 33type Person
  @addExternalFields(source: "profiles")
  @excludeField(name: "photo") {
  name: String
}

Example № 34type Person
  @excludeField(name: "photo")
  @addExternalFields(source: "profiles") {
  name: String
}

Parsing a Schema Coordinate

SchemaCoordinate は独立した文法であり独自の字句トークン集合を持つ自己完結型の文法です。それは Document に含まれるものではありません。SchemaCoordinate のソーステキストは SourceCharacter の列でなければなりません。

他の GraphQL ドキュメントと異なり、SchemaCoordinate は文字列中に Whitespace やその他の Ignored 文法を含んではなりません。これにより、各スキーマ座標は単一で曖昧さのない字句表現を持つことが保証されます。

Resolving a Schema Coordinate

ある schema element を参照するためには、schema coordinate を GraphQL の schema の文脈で解釈する必要があります。

もし該当する schema element が見つからない場合、resolve 関数は値を返しません（エラーは発生しません）。しかし、schema 内で schema coordinate の非葉ノードが見つからない場合はエラーが発生します。

Examples

上の表は、以下のスキーマに基づいて各種の schema coordinate の例を示しています。

type Query {
  searchBusiness(criteria: SearchCriteria!): [Business]
}

input SearchCriteria {
  name: String
  filter: SearchFilter
}

enum SearchFilter {
  OPEN_NOW
  DELIVERS_TAKEOUT
  VEGETARIAN_MENU
}

type Business {
  id: ID
  name: String
  email: String @private(scope: "loggedIn")
}

directive @private(scope: String!) on FIELD_DEFINITION

Built-in Scalars

GraphQL は明確に定義された基本的なスカラー型の集合を規定しています: Int、Float、String、Boolean、および ID です。GraphQL フレームワークはこれらすべてをサポートすべきであり、同名の型を提供するサービスは本書で記述される振る舞いに従わなければなりません。たとえば、サービスが Int という型を定義して 64 ビット数値や国際化情報など別の目的に用いることは許されません。

__Schema のイントロスペクション型から型の集合を返す際、参照されている組み込みスカラーはすべて含める必要があります。スキーマ内で組み込みスカラー型がどこにも参照されていない場合（その型を持つフィールド、引数、入力フィールドがない場合）は、含めてはなりません。

型システム定義言語で GraphQL スキーマを表現する場合、簡潔さのためにすべての組み込みスカラーは省略されるべきです。

Custom Scalars

GraphQL サービスは組み込みスカラーに加えてカスタムスカラー型を使用できます。たとえば、サービスが UUID というスカラーを定義し、それが文字列としてシリアライズされるが RFC 4122 に準拠するようにすることが考えられます。UUID 型のフィールドをクエリする場合、結果を RFC 4122 準拠のパーサで解析できることを期待できます。別の有用なカスタムスカラー例として URL があり、文字列としてシリアライズされるがサービスが有効な URL であることを保証するものです。

カスタムスカラーを定義する際、GraphQL サービスは @specifiedBy ディレクティブやイントロスペクションフィールド specifiedByURL を通じて scalar specification URL を提供するべきです。この URL はそのスカラーのデータ形式、シリアライズ、強制変換ルールに関する人間可読の仕様へリンクしていなければなりません。

たとえば、UUID スカラーを提供するサービスは RFC 4122 へのリンク、あるいはその RFC の合理的部分集合を定義する独自の文書をリンクすることができます。もし scalar specification URL が存在するなら、それを認識するシステムやツールはその記載ルールに従うべきです。

Example № 43scalar UUID @specifiedBy(url: "https://tools.ietf.org/html/rfc4122")
scalar URL @specifiedBy(url: "https://tools.ietf.org/html/rfc3986")
scalar DateTime
  @specifiedBy(url: "https://scalars.graphql.org/andimarek/date-time")

カスタムの scalar specification URL は単一で安定した形式を示すべきで、曖昧さを避けなければなりません。リンク先の仕様が流動的な場合は、変化し得るリソースではなく固定されたバージョンへリンクするべきです。

カスタムの scalar specification URL は定義後に変更すべきではありません。変更するとツールチェインを混乱させたり、リンク先仕様の内容に破壊的変更をもたらす可能性があります。

組み込みスカラー型は本書で規定されているため、scalar specification URL を提供してはなりません。

Result Coercion and Serialization

GraphQL サービスは、あるスカラー型のフィールドを準備する際に、そのスカラー型が示す契約を守らなければなりません。値を強制変換するか、値が強制変換できない、または変換によってデータ損失が生じる可能性がある場合は execution error を発生させるべきです。

GraphQL サービスは内部表現の異なる型を期待される戻り型へ合理的に強制変換する選択をすることがあります。たとえば Int 型のフィールドを返す際に boolean の true を 1 に変換したり、文字列 "123" を 10 進の 123 に解析することがあります。しかし、情報を失うような変換が合理的に行えない場合は execution error を発生させる必要があります。

この強制変換の振る舞いはクライアントからは観測できないため、正確なルールは実装に委ねられます。唯一の要件は、サービスが期待されるスカラー型に適合する値を返さなければならないという点です。

GraphQL のスカラーは使用されるシリアライズ形式に従ってシリアライズされます。各スカラー型に対して最も適切なシリアライズ原始型がある場合があり、サービスは適宜その原始型を生成すべきです。

スカラーのシリアライズに関する詳しい情報は Serialization Format を参照してください。

Input Coercion

もし GraphQL サービスが引数の入力としてスカラー型を期待する場合、強制変換は可観測でありその規則は明確に定義されていなければなりません。入力値が強制変換ルールに一致しない場合は、実行が始まる前に検証されるため request error を発生させなければなりません。

GraphQL には整数および浮動小数点の入力値を表す異なる定数リテラルがあり、どの種類の入力値が与えられるかによって強制変換ルールは異なる扱いをする可能性があります。GraphQL はしばしば変数によりパラメータ化され、その値は HTTP のようなトランスポートでシリアライズされて送信されることがあります。一般的なシリアライズ（例: JSON）は整数と浮動小数点を区別しないため、分数部が空であれば整数入力値（例: 1.0 が整数として解釈される）として扱い、そうでなければ浮動小数点入力値として扱います。

以下のすべての型について、Non-Null を除き、明示的な値 null が与えられた場合は入力強制変換の結果は null になります。

フィールドの順序

オブジェクトをクエリする際、結果として得られるフィールドのマッピングは、実行中に出現した順序と概念的に一致します。ただし、型が適用されないフラグメントや @skip や @include ディレクティブでスキップされたフィールドやフラグメントは除外されます。この順序は CollectFields() アルゴリズムを使うことで正しく生成されます。

順序付きマップを表現できるレスポンスのシリアライズ形式は、この順序を維持するべきです。順序付きマップを表現できない形式（例えば JSON）の場合でも、テキスト的にこの順序を保つべきです。つまり、もし二つのフィールド {foo, bar} がその順でクエリされたなら、生成される JSON シリアライズは同じ順序で {"foo": "...", "bar": "..."} を含むべきです。

リクエスト内で現れる順序と同じ順でフィールドを表現することは、デバッグ時の可読性を高め、プロパティの順序を予測できればレスポンスの効率的な解析を可能にします。

フラグメントが他のフィールドより先にスプレッドされている場合、そのフラグメントが指定するフィールドは後続のフィールドより前にレスポンス内に現れます。

Example № 53{
  foo
  ...Frag
  qux
}

fragment Frag on Query {
  bar
  baz
}

は順序付きの結果を生成します：

Example № 54{
  "foo": 1,
  "bar": 2,
  "baz": 3,
  "qux": 4
}

もし同じフィールドが選択内で複数回クエリされた場合、その順序は最初に出現した時点によって決まります。ただし、型が適用されないフラグメントは順序に影響を与えません。

Example № 55{
  foo
  ...Ignored
  ...Matching
  bar
}

fragment Ignored on UnknownType {
  qux
  baz
}

fragment Matching on Query {
  bar
  qux
  foo
}

は次の順序付き結果を生成します：

Example № 56{
  "foo": 1,
  "bar": 2,
  "qux": 3
}

また、ディレクティブによってフィールドが除外される場合、それらはフィールドの順序に考慮されません。

Example № 57{
  foo @skip(if: true)
  bar
  foo
}

は次の順序付き結果を生成します：

Example № 58{
  "bar": 1,
  "foo": 2
}

結果の強制変換

オブジェクトを強制変換した結果を決定することは GraphQL 実行機の中心的処理です。詳しくは Value Completion を参照してください。

入力の強制変換

オブジェクトは入力としては決して有効ではありません。

型の検証

オブジェクト型は不適切に定義されると無効になり得ます。以下のルールは、GraphQL スキーマ内のすべてのオブジェクト型が従うべきものです。

1. オブジェクト型は 1 つ以上のフィールドを定義していなければなりません。
2. オブジェクト型の各フィールドについて:
   1. そのフィールドは当該オブジェクト型内で一意の名前を持っていなければなりません。同じ名前のフィールドが二つ存在してはなりません。
   2. そのフィールドの名前は "__"（アンダースコア二つ）で始まってはなりません。
   3. そのフィールドは、IsOutputType(fieldType) が true を返す型を返さなければなりません。
   4. そのフィールドの各引数について:
      1. 引数名は "__"（アンダースコア二つ）で始まってはなりません。
      2. 引数名はそのフィールド内で一意でなければなりません。同じ名前の引数が二つあってはなりません。
      3. 引数は、IsInputType(argumentType) が true を返す型を受け入れなければなりません。
      4. もし引数の型が Non-Null でありデフォルト値が定義されていない場合:
         1. @deprecated ディレクティブはこの引数に適用してはなりません。
      5. もし引数にデフォルト値がある場合、そのデフォルト値は当該 argumentType に対する強制変換ルールと互換でなければなりません。
3. オブジェクト型は、1 つ以上の一意なインターフェースを実装すると宣言してよい。
4. オブジェクト型は、実装すると宣言したすべてのインターフェースのスーパーセットでなければなりません:
   1. このオブジェクト型を objectType とします。
   2. 宣言された各インターフェース interfaceType について、IsValidImplementation(objectType, interfaceType) は true でなければなりません。

インターフェースがインターフェースを実装する場合

あるインターフェースが別のインターフェースを実装するよう定義する場合、実装するインターフェースは実装される側のインターフェースで指定されている各フィールドを定義しなければなりません。例えば、インターフェース Resource が Node を実装するには id フィールドを定義する必要があります：

Example № 70interface Node {
  id: ID!
}

interface Resource implements Node {
  id: ID!
  url: String
}

遷移的に実装されるインターフェース（実装対象のインターフェースがさらに実装しているインターフェース）も、実装する型またはインターフェース上できちんと定義されていなければなりません。例えば Image は Resource を実装する際に Node も同時に実装していなければなりません。

Example № 71interface Node {
  id: ID!
}

interface Resource implements Node {
  id: ID!
  url: String
}

interface Image implements Resource & Node {
  id: ID!
  url: String
  thumbnail: String
}

インターフェース定義は循環参照を含んではならず、自身を実装してはなりません。次の例は不正です。なぜなら Node と Named が互いに、また自分自身を実装しているからです：

Counter Example № 72interface Node implements Named & Node {
  id: ID!
  name: String
}

interface Named implements Node & Named {
  id: ID!
  name: String
}

結果の強制変換

インターフェース型は、与えられた結果がどのオブジェクトに対応するかを判定する手段を持つべきです。それが判明したら、インターフェースの結果強制変換はそのオブジェクトの結果強制変換と同じになります。

入力の強制変換

インターフェースは入力としては決して有効ではありません。

型の検証

インターフェース型は不適切に定義されると無効になる可能性があります。

1. インターフェース型は 1 個以上のフィールドを定義していなければなりません。
2. インターフェース型の各フィールドについて:
   1. そのフィールドは当該インターフェース型内で一意の名前を持っていなければなりません。同じ名前のフィールドが二つ存在してはなりません。
   2. そのフィールドの名前は "__"（アンダースコア二つ）で始まってはなりません。
   3. そのフィールドは IsOutputType(fieldType) が true を返す型を返さなければなりません。
   4. そのフィールドの各引数について:
      1. 引数名は "__"（アンダースコア二つ）で始まってはなりません。
      2. 引数名はそのフィールド内で一意でなければなりません。同じ名前の引数が二つあってはなりません。
      3. 引数は IsInputType(argumentType) が true を返す型を受け入れなければなりません。
3. インターフェース型は一意な一つ以上のインターフェースを実装すると宣言できるが、自己実装はできません。
4. インターフェース型は、実装するすべてのインターフェースのスーパーセットでなければなりません:
   1. このインターフェース型を implementingType とします。
   2. 宣言された各インターフェース implementedType について、IsValidImplementation(implementingType, implementedType) は true でなければなりません。

結果の強制変換

ユニオン型は、与えられた結果がどのオブジェクトに対応するかを判定する手段を持つべきです。それが判明したら、ユニオンの結果強制変換はそのオブジェクトの結果強制変換と同じになります。

入力の強制変換

ユニオンは入力としては決して有効ではありません。

型の検証

ユニオン型は不適切に定義されると無効になる可能性があります。

1. ユニオン型は 1 つ以上の一意なメンバー型を含めなければなりません。
2. ユニオンのメンバー型はすべてオブジェクトの基底型でなければなりません。スカラー、インターフェース、ユニオン型はユニオンのメンバーになってはなりません。同様に、ラップ型もユニオンのメンバーになってはなりません。

結果の強制変換

GraphQL サービスは定義された可能な値のうちのいずれかを返さなければなりません。合理的な強制変換ができない場合は execution error を発生させる必要があります。

入力の強制変換

GraphQL には列挙入力値を表す定数リテラルがあります。GraphQL の文字列リテラルは列挙の入力として受け入れてはならず、その場合は request error を発生させるべきです。

EDN のように非文字列の象徴的値を別表現とする変数輸送シリアライゼーション（例えば EDN）では、そのような値のみを列挙入力値として許可すべきです。その他の多くのトランスポートシリアライゼーションでは文字列が列挙入力値と解釈され得るため、文字列は同名の列挙入力値として扱われることがあります。

型の検証

列挙型は不適切に定義されると無効になる可能性があります。

1. 列挙型は 1 つ以上の一意な列挙値を定義していなければなりません。

循環参照

入力オブジェクトは他の入力オブジェクトをフィールド型として参照することが許容されます。循環参照は入力オブジェクトが直接的に、あるいは参照を経由して自身を参照する場合に発生します。

循環参照は一般に許容されますが、Non-Null の単数フィールドが途切れなく連鎖する形で定義されてはなりません。そのような入力オブジェクトは合法的な値を提供する方法がないため無効です。

次の循環参照する入力型の例は有効です。フィールド self を省略できるか、値が null になり得るためです。

Example № 81input Example {
  self: Example
  value: String
}

次の例も有効です。self フィールドが空の List になり得るためです。

Example № 82input Example {
  self: [Example!]!
  value: String
}

次の循環参照する入力型の例は無効です。フィールド self に有限な値を提供できないからです。

Counter Example № 83input Example {
  value: String
  self: Example!
}

次の例も無効です。First.second と Second.first を介した非 null の単数の循環参照が存在するためです。

Counter Example № 84input First {
  second: Second!
  value: String
}

input Second {
  first: First!
  value: String
}

結果の強制変換

入力オブジェクトは結果として有効ではありません。Input Object 型は Object や Interface のフィールドの戻り型にはなり得ません。

入力の強制変換

入力オブジェクトの値は入力オブジェクトリテラルか、変数によって渡された順不同マップであるべきです。そうでない場合は request error が発生しなければなりません。いずれの場合でも、入力オブジェクトリテラルや順不同マップはこの入力オブジェクト型で定義されていない名前のエントリを含んではならず、含んでいる場合はリクエストエラーが発生しなければなりません。

強制変換の結果は、入力オブジェクト型で定義され、かつ値が存在する各フィールドに対するエントリを持つ順不同マップです。結果のマップは以下のルールで構築されます：

• 定義された入力オブジェクトフィールドに対して値が提供されず、そのフィールド定義がデフォルト値を提供している場合は、当該フィールド型の強制変換ルールに従ってデフォルト値を強制変換した結果を使用するべきです。デフォルト値が提供されておらず、入力オブジェクトフィールドの型が non-null の場合はエラーを発生させるべきです。その他の場合、フィールドが必須でなければ、強制変換された順不同マップにエントリは追加されません。
• もし入力オブジェクトフィールドに対して明示的に値 null が提供され、そのフィールドの型が non-null でない場合、強制変換された順不同マップのエントリには null が与えられます。つまり、明示的に null を提供するのと、値を提供しないのとでは意味が異なります。
• もし入力オブジェクトフィールドにリテラル値が提供された場合、そのフィールド型の入力強制変換ルールに従ってその値を強制変換した結果が強制変換された順不同マップのエントリとして与えられます。
• もし入力オブジェクトフィールドに変数が提供された場合は、その変数の実行時値を使用しなければなりません。実行時値が null でありフィールド型が non-null の場合は execution error が発生しなければなりません。実行時値が提供されていない場合は、変数定義のデフォルト値を使用します。変数定義がデフォルト値を提供していない場合は、入力オブジェクトフィールド定義のデフォルト値を使用します。

以下は、String 型フィールド a と 必須の Int! 型フィールド b を持つ入力オブジェクト型に対する入力強制変換の例です：

Example № 85input ExampleInputObject {
  a: String
  b: Int!
}

型の検証

1. Input Object 型は 1 個以上の入力フィールドを定義していなければなりません。
2. Input Object 型の各入力フィールドについて:
   1. 入力フィールドはその Input Object 型内で一意の名前を持っていなければなりません。同じ名前の入力フィールドが二つ存在してはなりません。
   2. 入力フィールドの名前は "__"（アンダースコア二つ）で始まってはなりません。
   3. 入力フィールドは、IsInputType(inputFieldType) が true を返す型を受け入れなければなりません。
   4. もし入力フィールドの型が Non-Null でありデフォルト値が定義されていない場合:
      1. @deprecated ディレクティブはこの入力フィールドに適用してはなりません。
   5. もし Input Object が OneOf Input Object である場合は:
      1. 入力フィールドの型は nullable でなければなりません。
      2. 入力フィールドはデフォルト値を持ってはなりません。
3. もし Input Object が直接または参照を通して自身を参照する場合、参照の連鎖に含まれるフィールドの少なくとも一つは nullable か List 型でなければなりません。
4. InputObjectDefaultValueHasCycle(inputObject) は false でなければなりません。

結果の強制変換

GraphQL サービスはリスト型の結果として順序付きリストを返さなければなりません。リスト内の各項目は項目型に対する結果強制変換の結果でなければなりません。合理的な強制変換ができない場合は 実行エラー を発生させる必要があります。特に、非リストが返された場合は型システムと実装の期待が一致していないことを示すため強制変換は失敗すべきです。

リストの項目型が nullable の場合、個々の項目の準備または強制変換中に発生したエラーは、その位置の値を null にし、レスポンスに 実行エラー を追加する結果になります。リストの項目型が non-null の場合、個々の項目で発生した実行エラーはリスト全体に対する実行エラーとなる必要があります。

入力の強制変換

入力として期待される場合、リスト値はリストの項目型が受け入れ可能な各項目を持つ場合にのみ受け入れられます。

もしリスト型への入力として渡された値がリストではなく、かつ nullではない場合、入力強制変換の結果は要素数 1 のリストとなり、単一の項目値は提供された値に対してリストの項目型の入力強制変換を行った結果になります（ネストしたリストに対しては再帰的に適用され得ます）。

これにより、可変長引数（しばしば "var args" と呼ばれる）を受け取る入力はリスト型として宣言しつつ、単一値の場合はクライアントがリストを構築せず直接その値を渡せるようになります。

以下は様々なリスト型と値に対する入力強制変換の例です：

Nullable と Optional

フィールドは 常に 選択集合（selection set）の文脈内ではオプションです。フィールドは省略可能であり、選択集合が空にならない限りその選択集合は有効です。ただし、Non-Null 型を返すフィールドはクエリ時に null を返すことはありません。

入力（フィールド引数など）はデフォルトで常にオプションです。しかし Non-Null の入力型は必須です。Non-Null は null を受け入れないだけでなく、省略も受け入れません。簡略化のため、nullable 型は常にオプション、non-null 型は常に必須と見なされます。

結果の強制変換

上記の結果強制変換では null は有効な値として扱われていました。Non-Null 型の結果を強制変換するには、ラップされた型の強制変換を行います。その結果が null でなければ、その値が Non-Null 型の強制変換結果となります。もしその結果が null であれば、実行エラー を発生させなければなりません。

入力の強制変換

もし Non-Null 型の引数または入力オブジェクトフィールドに対して値が提供されていない、文字どおりの値として null が提供された、もしくは実行時に値が提供されていない変数が提供された、あるいは実行時に null が与えられた場合は、リクエストエラー を発生させなければなりません。

もし Non-Null 型に提供された値が null以外のリテラル値、もしくは Non-Null な変数値である場合は、ラップされた型に対する入力強制変換を用いてそれを強制変換します。

非 null の引数は省略できません：

Counter Example № 87{
  fieldWithNonNullArg
}

非 null の引数に null を提供することはできません：

Counter Example № 88{
  fieldWithNonNullArg(nonNullArg: null)
}

nullable 型の変数を非 null の引数に渡すことはできません：

Example № 89query withNullableVariable($var: String) {
  fieldWithNonNullArg(nonNullArg: $var)
}

型の検証

1. Non-Null 型は別の Non-Null 型をラップしてはなりません。

組み込みディレクティブ

組み込みディレクティブ はこの仕様内で定義されたディレクティブを指します。

GraphQL 実装は @skip と @include のディレクティブを提供するべきです。

型システム定義言語をサポートする GraphQL 実装は、スキーマ内の非推奨部分を表すために @deprecated ディレクティブを提供する必要があります。

カスタムスカラー定義を表す場合、型システム定義言語をサポートする実装は @specifiedBy を提供するべきです。

OneOf 入力オブジェクトを表す場合、型システム定義言語をサポートする実装は @oneOf を提供するべきです。

型システム定義言語で GraphQL スキーマを表現する際、簡潔さのために任意の 組み込みディレクティブ を省略できます。

GraphQL サービスをイントロスペクトする際、提供されているすべてのディレクティブ（組み込みディレクティブを含む）は返されるディレクティブ集合に含まれていなければなりません。

カスタムディレクティブ

GraphQL サービスやクライアントツールは、この文書で定義されたもの以外の任意の カスタムディレクティブ を提供できます。ディレクティブは GraphQL をカスタムまたは実験的な振る舞いで拡張する推奨手段です。

ディレクティブは宣言された適用箇所でのみ使用されるべきです。以下の例ではフィールドに注釈を付けるためのディレクティブが定義されています：

Example № 90directive @example on FIELD

fragment SomeFragment on SomeType {
  field @example
}

ディレクティブの適用場所は、長い一覧を表現する際の書式補助として先頭に省略可能な | を含めて定義できます：

Example № 91directive @example on
  | FIELD
  | FRAGMENT_SPREAD
  | INLINE_FRAGMENT

ディレクティブは型システム定義言語の注釈としても使用でき、スキーマやクライアント生成コードのための追加メタデータを提供するのに役立ちます。

以下の例では、@example がフィールド定義と引数定義を注釈しています：

Example № 92directive @example on FIELD_DEFINITION | ARGUMENT_DEFINITION

type SomeType {
  field(arg: Int @example): String @example
}

ディレクティブは repeatable キーワードを含めて繰り返し可能として定義できます。繰り返し可能なディレクティブは、同一箇所で異なる引数とともに同じディレクティブを複数回使いたい場合に有用です：

Example № 93directive @delegateField(name: String!) repeatable on OBJECT | INTERFACE

type Book @delegateField(name: "pageCount") @delegateField(name: "author") {
  id: ID!
}

extend type Book @delegateField(name: "index")

ディレクティブを定義する際、そのディレクティブが直接的または間接的に自身を参照してはなりません：

Counter Example № 94directive @invalidExample(arg: String @invalidExample) on ARGUMENT_DEFINITION

型の検証

1. ディレクティブ定義は少なくとも一つの DirectiveLocation を含めなければなりません。
2. ディレクティブ定義は自身を直接参照するディレクティブの使用を含んではなりません。
3. ディレクティブ定義は、ある型やディレクティブが転移的にこのディレクティブへの参照を含むことで間接的に自身を参照するような使用を含んではなりません。
4. ディレクティブ名は "__"（アンダースコア二つ）で始まってはなりません。
5. ディレクティブの各引数について:
   1. 引数名は "__" で始まってはなりません。
   2. 引数名はそのディレクティブ内で一意でなければなりません。
   3. 引数は IsInputType(argumentType) が true を返す型を受け入れなければなりません。

ファーストクラスのドキュメント

イントロスペクションシステム内のすべての型は description フィールド（型: String）を提供し、型設計者が機能に加えてドキュメントを公開できるようにします。GraphQL サービスは description フィールドに Markdown（CommonMark に準拠）を返すことができます。したがって description を表示するツールは CommonMark 準拠の Markdown レンダラを使用することが推奨されます。

非推奨

後方互換性の管理を支援するために、GraphQL のフィールド、引数、入力フィールド、および列挙値は isDeprecated: Boolean! によって非推奨であるかどうかを示し、なぜ非推奨であるかを説明するために deprecationReason: String を提供できます。

イントロスペクションを用いて構築されたツールは、非推奨の使用を情報の隠蔽や開発者向けの警告を通じて抑止するよう配慮すべきです。

安定した順序

すべてのデータコレクションの観測可能な順序は、スキーマの可読性と安定性を向上させるために保持されるべきです。TypeSystemDocument からスキーマが生成される場合、イントロスペクションはオブジェクトフィールド、入力オブジェクトフィールド、引数、列挙値、ディレクティブ、ユニオンのメンバー型、および実装しているインターフェースといった各要素リストについてソース中の同じ順序で項目を返すべきです。

スキーマイントロスペクションスキーマ

スキーマイントロスペクションシステム自体が GraphQL スキーマとして表現されています。以下はイントロスペクションを提供するための型システム定義の全集合であり、それらは後続の節で完全に定義されています。

type __Schema {
  description: String
  types: [__Type!]!
  queryType: __Type!
  mutationType: __Type
  subscriptionType: __Type
  directives: [__Directive!]!
}

type __Type {
  kind: __TypeKind!
  name: String
  description: String
  # may be non-null for custom SCALAR, otherwise null.
  specifiedByURL: String
  # must be non-null for OBJECT and INTERFACE, otherwise null.
  fields(includeDeprecated: Boolean! = false): [__Field!]
  # must be non-null for OBJECT and INTERFACE, otherwise null.
  interfaces: [__Type!]
  # must be non-null for INTERFACE and UNION, otherwise null.
  possibleTypes: [__Type!]
  # must be non-null for ENUM, otherwise null.
  enumValues(includeDeprecated: Boolean! = false): [__EnumValue!]
  # must be non-null for INPUT_OBJECT, otherwise null.
  inputFields(includeDeprecated: Boolean! = false): [__InputValue!]
  # must be non-null for NON_NULL and LIST, otherwise null.
  ofType: __Type
  # must be non-null for INPUT_OBJECT, otherwise null.
  isOneOf: Boolean
}

enum __TypeKind {
  SCALAR
  OBJECT
  INTERFACE
  UNION
  ENUM
  INPUT_OBJECT
  LIST
  NON_NULL
}

type __Field {
  name: String!
  description: String
  args(includeDeprecated: Boolean! = false): [__InputValue!]!
  type: __Type!
  isDeprecated: Boolean!
  deprecationReason: String
}

type __InputValue {
  name: String!
  description: String
  type: __Type!
  defaultValue: String
  isDeprecated: Boolean!
  deprecationReason: String
}

type __EnumValue {
  name: String!
  description: String
  isDeprecated: Boolean!
  deprecationReason: String
}

type __Directive {
  name: String!
  description: String
  isRepeatable: Boolean!
  locations: [__DirectiveLocation!]!
  args(includeDeprecated: Boolean! = false): [__InputValue!]!
}

enum __DirectiveLocation {
  QUERY
  MUTATION
  SUBSCRIPTION
  FIELD
  FRAGMENT_DEFINITION
  FRAGMENT_SPREAD
  INLINE_FRAGMENT
  VARIABLE_DEFINITION
  SCHEMA
  SCALAR
  OBJECT
  FIELD_DEFINITION
  ARGUMENT_DEFINITION
  INTERFACE
  UNION
  ENUM
  ENUM_VALUE
  INPUT_OBJECT
  INPUT_FIELD_DEFINITION
}