GraphQL

2.1.1Unicode/统一码

UnicodeBOM → “字节顺序标记(U+FEFF)”

GraphQL的StringValue（字符串值）和Comment（备注）中可以使用非ASCII的Unicode字符。

BOM，又称字节顺序标记，是一个特殊的Unicode字符，它出现在文件的头部，以便程序用以确认当前文本流是Unicode编码，使用了大端还是小端，该用哪一种Unicode编码来转义。

2.1.2White Space/空白符

空白符 →

• ”水平制表符(U+0009)”
• ”空格(U+0020)”

空白符出现在记号的前后，作为记号分隔使用，用于提升源文本的易读性。GraphQL查询文档的空白符可能出现在String或Comment记号中，但并不会显著影响其语义。

2.1.3Line Terminators/行终止符

行终止符 →

• ”新行 (U+000A)”
• ”回车 (U+000D)”
• ”回车 (U+000D)” “新行 (U+000A)”

跟空白符类似，行终止符也是用于提升源文本的易读性，可出现在记号的前后，对GraphQL查询文档的语义无显著影响。行终止符不应该出现在其他记号之间。

2.1.4Comments/注释

注释 → # 注释字符

注释字符 → 源字符，非行终止符

GraphQL查询文档可以包含以#开头的单行注释。

注释可使用除了LineTerminator（行终止符）以外的任意Unicode字符（码点）。所以可以说，注释包含了以#开头的除行终止符以外的所有字符。

注释与空白符类似，出现在任意记号后面、行终止符前面，对GraphQL查询文档的语义无显著影响。

2.1.5Insignificant Commas/无语义逗号

逗号 → ,

与空白符和行终止符类似，逗号(,)也是提升源文本的易读性、分隔词法记号，对GraphQL查询文档的语法语义上也无显著影响.

无语义逗号保证了无论有误逗号，都不影响文档的解读，在其他语言中这就可能是一个用户错误。为了源代码易读性和可维护性，列表会使用行终止符和末尾逗号作为分隔符，无语义逗号也有这个样式上的用途。

2.1.6Lexical Tokens/词法记号

记号 →

• 标点
• 命名
• 整数值
• 浮点值
• 字符串型值

一个GraphQL文档由多种独立记号组成，本规范中使用源文本Unicode字符模式来定义这些记号。

在后文GraphQL查询文档句法中，记号将作为终结符使用。

2.1.7Ignored Tokens/无语义记号

无语义记号 →

• Unicode字节顺序标记
• 空白符
• 行终止符
• 注释
• 逗号

在词法记号的前后可能会出现不定量的无语义记号，包括WhiteSpace（空白符）和Comment备注。源文档的无语义区域都是无语义影响的，但是无语义字符可能以一种有影响的方式出现在源字符词法记号之间，譬如String（字符串）可能包含空白字符。

在解析给定记号时，所有字符都不能被忽略，譬如FloatValue（浮点值）的字符中不允许出现空白符。 (译者案：本段无力，求大神指点)

2.1.8Punctuators/标点

标点 → ! $ ( ) ... : = @ [ ] { | } 之一

GraphQL文档使用了标点符号以描述结构，GraphQL是一种数据描述语言，而非编程语言，因此GraphQL缺乏用于描述数学表达式的标点符号。

2.1.9Names/命名

命名 → /[_A‐Za‐z][_0‐9A‐Za‐z]/*

GraphQL查询文档全是命名的产物：operations（操作），fields（字段），arguments（参数），directives（指令）， fragments（片段）和variables（变量）。所有命名必须遵循以下格式：

GraphQL的命名是大小写敏感的，也就是说name，Name，和NAME是不同的名字，下划线也具有影响，other_name和othername也是两个不同的名字。

GraphQL的命名限制在上述ASCII子集内，以便支持尽可能多的其他系统。

2.8.1Type Conditions/类型条件

类型条件 → on 具名类型

片段需要指定应用于的目标类型，在上述案例中，friendFields在查询User的上下文中使用。

片段不能应用于任何输入值（标量值，枚举型或者输入型对象）。

片段可应用与对象型，接口和联合。

只有在对象的具体类型和片段的应用目标类型匹配的时候，片段内的选择集合才会返回值。

譬如，下列Facebook数据模型查询：

query FragmentTyping {
  profiles(handles: ["zuck", "cocacola"]) {
    handle
    ...userFragment
    ...pageFragment
  }
}

fragment userFragment on User {
  friends {
    count
  }
}

fragment pageFragment on Page {
  likers {
    count
  }
}

profiles根字段将会返回一个列表，其中的元素可能是Page或者User类型。当profiles内的对象是User类型时，friends会出现，而likers不会。反之当结果内的对象是Page时，likers会出现，friends则不会。

{
  "profiles": [
    {
      "handle": "zuck",
      "friends": { "count" : 1234 }
    },
    {
      "handle": "cocacola",
      "likers": { "count" : 90234512 }
    }
  ]
}

2.8.2Inline Fragments/内联片段

内联/行内片段 → ... 类型条件？ 指令？ 选择集合？

片段可以在选择集合内以内联格式定义，这用于根据运行时类型条件式地引入字段。这个特性的标准片段引入版本在query FragmentTyping中已经演示，我们也可以使用内联片段的方式来实现：

query inlineFragmentTyping {
  profiles(handles: ["zuck", "cocacola"]) {
    handle
    ... on User {
      friends {
        count
      }
    }
    ... on Page {
      likers {
        count
      }
    }
  }
}

内联片段也用于将指令应用于一群字段的场景。如果省略了类型条件，片段则被视为等同于封装所在的上下文。

query inlineFragmentNoType($expandedInfo: Boolean) {
  user(handle: "zuck") {
    id
    name
    ... @include(if: $expandedInfo) {
      firstName
      lastName
      birthday
    }
  }
}

2.9.1Int Value/整数值

指定整数不应该使用小数点或指数符号。(譬如：1)

2.9.2Float Value/浮点值

指定浮点数需要包含小数点(例如：1.0)或者指数符号(例如：1e50)或者两者(例如：6.0221413e23)。

2.9.3Boolean Value/布尔值

true和false两个关键字表示布尔型的两个值。

2.9.4String Value/字符串值

字符串是一系列由双引号(")包起来的字符，譬如"Hello World"。字符串内的空白符和其他无语义字符都对字符串有影响。

Semantics/语义

2.9.5Null Value/空值

null代表空值。

GraphQL在语义上有两种方式来表示一个缺值：

• 显式，使用字面量值：null。
• 隐式，不使用任何值。

例如：下列两个相似的字段查询并不是一样的：

{
  field(arg: null)
  field
}

前者显式使用了null给arg参数，后者隐式，没有给arg参数以值。两个形式会被不同解读，譬如一个mutation操作中，会表示成删除一个字段或者不改变一个字段。两者都不能用于非空输入类型参数。

2.9.6Enum Value/枚举值

枚举值表现为没有引号包裹的名称，规范建议使用全大写字母表示枚举值，枚举值仅用于准确枚举类型可用的上下文中，因此枚举类型命名上不必使用字面量。

2.9.7List Value/列表值

列表是包在方括号[ ]中的有序值序列，列表值可以是任意字面量值或者变量，譬如[1, 2, 3]。

因为GraphQL中逗号是可选的，因此末尾逗号和重复逗号都是允许的，而不会代表空缺值。

Semantics/语义

2.9.8Input Object Values/输入型对象值

输入型对象是无需键值列表，使用花括号{ }包起来。对象的值可以是输入字面量值或者变量值(例如：{ name: "Hello world", score: 1.0 })。我们将输入型对象的字面量表示法称作“对象字面量”。

Input object fields are unordered/输入型对象的字段是无序的

输入型字段能以各种句法顺位排列，而表示相同的语义。

下面两个查询在语义上是一样的：

{
  nearestThing(location: { lon: 12.43, lat: -53.211 })
}

{
  nearestThing(location: { lat: -53.211, lon: 12.43 })
}

Semantics/语义

3.1.1Scalars/标量

如名字所示，GraphQL中一个标量代表这一个原始值，GraphQL的响应采用的是树形层级结构，其叶子节点即是标量。

所有GraphQL标量都能以字符串形式表示，虽然取决于所用的返回格式，可能有准确的原始类型来表示指定标量，服务器在适当的时候也应采取这种类型。

GraphQL提供了一些内建标量，类型系统也允许根据语义添加其他标量。假设GraphQL中要定义一个标量Time/时间，可将字符串转换成ISO‐8601的格式，当查询一个Time字段时，客户端可以使用ISO‐8601解析器，将这个字段类型转换成客户端特有的原始类型。另一个有潜在用途的标量是Url，通常会序列化成字符串，但是会由服务器保证是有效的URL。

服务器可能会在schema中省略内建标量，譬如，服务器并未使用浮点数，那么它可能并不会包含Float类型。 但是一旦schema包含了本规范所述的类型，那么一定会遵守本规范描述的对应行为，譬如，服务器一定不会使用名为Int的类型去表示128‐bit的数字，或者国际化信息。

Result Coercion/结果类型转换

当GraphQL服务器准备一个标量字段的时候，必须遵守此标量的描述协议，或者强制转换原始值，或者抛出错误。

例如：当服务器在准备一个Int型标量时，收到的是一个浮点数，如果服务器直接输出这个值，那势必会打破协定，所以服务器可以剔除小数部分，只保留整数部分，然后返回整数值，如果服务器收到的是布尔型值true，那么就可以返回1，如果服务器收到的是字符串型，那么就尝试以10为底，解析字符串为整数，如果服务器没法将某些值转换成Int，那么就只能抛出错误。

因为这个转换行为对于客户端是不可见的，所以准确的转换规则全由实现指定，规范对其的唯一要求就是输出值需遵守标量协议。

Input Coercion/输入类型转换

如果GraphQL的某个参数要求标量作为输入，其类型转换显而易见地必须良好定义。如果输入值无法满足转换规则，则必须抛出错误、

GraphQL对于整数和浮点数输入值有不同的字面量表示方式，其类型转换也对应输入类型做转换。GraphQL可以使用变量作为参数，这些变量的值像是在HTTP的传输中通常会被序列化，由于有些序列化方法并不区分整数和浮点数（譬如JSON），可能因为一个数没有有效小数值而被当作整数而不是浮点数。

下列所有类型中，除了Non‐Null之外，如果显式提供了null，那么其输入结果就会被转换成null。

Built‐in Scalars/内建标量

GraphQL提供一套基本的定义良好的标量类型，每个GraphQL服务器都应该支持这些类型，并且使用这些名字的类型必须遵守下文描述的行为、

3.1.2Objects/对象

GraphQL查询是层级式的可组装的，以树的形式描述了信息。其中标量类型描述了层级查询中叶子节点的值，对象则描述了中间层。

GraphQL对象表示一个具名字段列表，每个字段会产出一个特定类型的值。对象的值应该向有序映射集（ordered maps），其中查询字段名（或者别名）作为键，字段的结果作为值，以出现在查询中的顺序来排序。

对象中的所有字段都不应以"__"（双下划线）起头命名，因为这GraphQL内省系统专用的命名方式。

例如，Person类型可以如下描述：

type Person {
  name: String
  age: Int
  picture: Url
}

其中name产生一个String值，age产生一个Int值，picture产生一个Url值。

对一个对象的查询必须至少指定一个字段，字段的选择集会产生一个有序映射集，其中包含被查询对象准确的子集，这个子集将以查询的顺序排序。只有在对象中声明过的字段才能被有效查询。

譬如，查询Person的所有字段：

{
  name
  age
  picture
}

会产生如下对象：

{
  "name": "Mark Zuckerberg",
  "age": 30,
  "picture": "http://some.cdn/picture.jpg"
}

当选择字段的子集：

{
  age
  name
}

一定会产生准确的子集：

{
  "age": 30,
  "name": "Mark Zuckerberg"
}

对象的字段可能是标量、枚举型、其他对象类型、接口、或者联合。也可能是其它封装类型，其内部类型是这五个之一。

例如：Person类型可能包含relationship：

type Person {
  name: String
  age: Int
  picture: Url
  relationship: Person
}

对于字段对象的查询必须嵌套其字段集合，譬如下列查询就不是有效的：

{
  name
  relationship
}

然而，这个案例是有效的：

{
  name
  relationship {
    name
  }
}

并会产生被查询的每个对象的子集：

{
  "name": "Mark Zuckerberg",
  "relationship": {
    "name": "Priscilla Chan"
  }
}

Field Ordering/字段排序

当查询一个对象时，字段的结果映射在概念上的排序顺序应该是跟查询执行期间字段被执行的顺序一致，除了片段上并不适用于当前字段的类型和被@skip或@include指令跳过的字段。这个排序由CollectFields()算法正确完成。

表示有序映射集的响应序列化格式也应该采用同样的排序。只能表示无序映射集的序列化格式（譬如JSON）应该保证这个语法上的顺序。

响应中字段排序和请求中一致的表示方式，提升了调试过程中对人而言的可读性，也保证了响应属性顺序相关的解析效率。

如果一个片段在其他字段之前展开，那么片段的字段的顺位则在片段后续字段之前。

{
  foo
  ...Frag
  qux
}

fragment Frag on Query {
  bar
  baz
}

产生下面排序结果：

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

如果一个字段在一个选择集中被多次查询，则以第一次被执行的顺序排序，片段中不适用的字段不会影响排序。

{
  foo
  ...Ignored
  ...Matching
  bar
}

fragment Ignored on UnknownType {
  qux
  baz
}

fragment Matching on Query {
  bar
  qux
  foo
}

产生下面排序结果：

{
  "foo": 1,
  "bar": 2,
  "qux": 3
}

如果一个字段被指令排除，那它也不会被纳入字段排序的考量之中。

{
  foo @skip(if: true)
  bar
  foo
}

产生下面排序结果：

{
  "bar": 1,
  "foo": 2
}

Result Coercion/结果类型转换

对象类型的结果类型转换判定机制是GraphQL执行器的核心，因此将在本规范的执行器那一章节覆盖这个内容。

Input Coercion/输入类型转换

对象类型不可作为有效输入类型。

type Person {
  name: String
  picture(size: Int): Url
}

{
  name
  picture(size: 600)
}

{
  "name": "Mark Zuckerberg",
  "picture": "http://some.cdn/picture_600.jpg"
}

3.1.3Interfaces/接口

GraphQL接口表示一个具名字段列表以及其参数，GraphQL对象可以实现接口，并保证包含接口中的字段。

GraphQL接口上的字段拥有和GraphQL对象上相同的规则；字段类型可以是标量、对象、枚举型、接口或者联合，或者这五个类型作为基本类型的封装类型。

例如，一个接口可以描述某个必要字段的类型，譬如Person或者Business，随后实现这个接口。

interface NamedEntity {
  name: String
}

type Person implements NamedEntity {
  name: String
  age: Int
}

type Business implements NamedEntity {
  name: String
  employeeCount: Int
}

产生接口额字段使用的场景为需要从多个对象找返回一个的情况，其中需要保证一定会有部分字段。

继续上述案例，Contact可能指代NamedEntity。

type Contact {
  entity: NamedEntity
  phoneNumber: String
  address: String
}

这将使我们能够编写查询Contact中通用字段的语句。

{
  entity {
    name
  }
  phoneNumber
}

当查询一个接口类型上的字段时，只有在接口上声明的字段可是被查询。上述案例中，entity返回NamedEntity，其中NamedEntity中定义了name，所以这个查询是有效的。所以，下面这个查询是无效的：

{
  entity {
    name
    age
  }
  phoneNumber
}

因为entity指代NamedEntity，这个接口中并没有定义age，所以只有在entity的结果为Person，查询age才有效。查询语句可以通过片段或者内联片段来表述这种情况：

{
  entity {
    name
    ... on Person {
      age
    }
  },
  phoneNumber
}

Result Coercion/结果类型转换

接口类型应该能够判定给定结果对应哪一个对象类型，一旦确定，接口的结果类型转换和对象的接口转换采用一样的方法。

Input Coercion/输入类型转换

接口类型不可作为有效输入类型。

3.1.4Unions/联合

GraphQL联合表示一个对象的类型是对象类型列表中之一，但不保证这些类型之间的字段。另一个区别于接口的方面是，对象会声明其实现的接口，而不知道它被包含的联合。

对于接口和对象，只可以直接查询在其中被定义的字段，如果要查询接口的其他字段，必须使用类型片段。对于联合也是一样，但是联合不定义任何字段，所以联合上不允许查询任何字段，除非使用类型片段。

例如，我们有以下类型系统：

union SearchResult = Photo | Person

type Person {
  name: String
  age: Int
}

type Photo {
  height: Int
  width: Int
}

type SearchQuery {
  firstSearchResult: SearchResult
}

当查询SearchQuery类型的firstSearchResult字段时，查询可能需要片段的所有字段来判断类型。如果结果是Person，那请求其name，如果是photo，那请求height。下列案例是错的，因为联合上不定义任何字段：

{
  firstSearchResult {
    name
    height
  }
}

而正确的查询应该是：

{
  firstSearchResult {
    ... on Person {
      name
    }
    ... on Photo {
      height
    }
  }
}

Result Coercion/结果类型转换

联合类型应该能够判定给定结果对应哪一个对象类型，一旦确定，联合的结果类型转换和对象的接口转换采用一样的方法。

Input Coercion/输入类型转换

联合类型不可作为有效输入类型。

3.1.5Enums/枚举型

GraphQL枚举型是基于标量类型的变体，其表示可能值的一个有限集。

GraphQL枚举型并不指代数值，而是正确的唯一值。他们序列化成字符串，字符串中用名来表示值。

Result Coercion/结果类型转换

GraphQL服务器必须返回定义中可能结果集的一个值。如果无法达成合理的类型转换，则抛出字段错误。

Input Coercion/输入类型转换

GraphQL用常量字面量表示枚举型输入值，GraphQL字符串型字面量不可作为枚举型输入值，否则将抛出查询错误。

查询变量的序列化传输方式中，如果对于非字符串符号值有区别于字符串的表示方法（譬如EDN），那么就应该采用那种方法。否则就像没有这个能力的大多数序列化传输方法一样，字符串型将被转义成同名的枚举型值。

3.1.6Input Objects/输入对象

字段上可能会定义参数，客户端将参数合在查询中传输，从而改变字段的行为。这些输入可能是字符串型或者枚举型，但是有时候需要比这个更复杂的类型结构。

上文中定义的Object并不适合在这儿重用，因为Object可能包含循环引用或者指代了接口类型或联合类型，这俩都不适合作为输入参数。因此，输入对象才成为了这个系统中单独的类型。

Input Object定义了输入字段的一个集合，输入字段并不是标量、枚举型或者其他输入对象，这使参数可以接受任意的复杂结构。

Result Coercion/结果类型转换

输入对象类型不可作为有效结果类型。

Input Coercion/输入类型转换

输入对象类型的值应该是输入对象的字面量或者无序映射集，否则将抛出错误。这个无序映射集不应该包含这个输入对象类型中未定义的字段，否则将抛出错误。

如果输入对象上定一个非空字段没有从原始值收到对应条目（譬如变量未赋值，或者赋予了null（空）值），则抛出错误。

类型转换的结果是环境特定的无序映射集，其定义了由输入对象类型和原始值构成的字段。

对于输入对象类型中的字段，如果原始值中有条目拥有相同的名字，条目的值是一个字面量或者变量（运行时值），这个条目就被添加到结果中同名的字段上。

结果中条目的值是原始值类型转换之后的结果，类型转换的规则由输入字段的类型决定。

下列是输入对象类型转换的案例：

input ExampleInputObject {
  a: String
  b: Int!
}

3.1.7Lists/列表型

GraphQL列表市一个特殊的集合类型，它声明了列表中元素的类型（下文指代为元素类型）。列表值的序列化结果是一个有序列表，列表中的元素根据元素类型序列化。一个字段使用了一个列表类型，其中封装了元素类型，其标注形式为：pets: [Pet]。

Result Coercion/结果类型转换

GraphQL服务器必须返回有序列表作为一个列表类型的结果，列表中的每一个元素都是其元素类型的结果类型转换的结果，如果无法达成合理的类型转换，则抛出字段错误。其中，如果返回的是非列表类型，类型转换也会失败，这是要抛出一个类型系统和实现不匹配的异常。

Input Coercion/输入类型转换

当作为输入类型的时候，要求所有列表值都符合列表元素类型。

如果作为输入类型传递给列表类型的值，既不是列表型也不是null空值，那么它将作为列表中的唯一元素作类型转换，这使输入能够在即便声明为“var args”类型参数数组，但只有一个参数被传入（常见场景），客户端可以直接传递值而不用封装成列表。

3.1.8Non-Null/非空型

默认情况下，GraphQL的所有类型都是可空的；null可作为上述所有类型的有效响应。如果要声明一个值不可为空，可以使用GraphQL的非空类型。这个类型封装一个内部类型，并表现为和被封装类型一样的行为，除了null不可作为其有效响应。非空类型使用一个感叹号跟着封装类型的方式来标注：name: String!。

Nullable vs. Optional/可空 vs 可选

查询上下文中的字段总是可选的，某个字段可以被省略而查询依然有效。然后，非空类型的字段绝不能对查询返回null。

输入（譬如字段参数）默认情况下总是可选的，然而如果一个参数是非空输入类型，那么它将不接受null也不能被省略。为了简明,(nullable)可空类型总是(optional)可选的，(non‐null)非空类型总是(required)必须的。

Result Coercion/结果类型转换

上述所有结果类型转换中，null都被视为有效值，如果转换一个非空类型，那么会使用被封装类型的转换规则。如果非空类型的转换结果不为null空，那么就取这个结果。否则如果结果为null空，那么则抛出字段错误。

Input Coercion/输入类型转换

如果未提供非空类型的输入对象字段或者参数，则被认为是提供了字面量null，或者认为是提供了一个未赋值或者为null空值的运行时变量，然后抛出查询错误。

如果给非空类型提供的值是字面量而非null，或者一个非空变量值，则其会按照被封装类型的输入类型转换规则来转换。

案例：非空参数不可省略。

{
  fieldWithNonNullArg
}

案例：null空值不可作为非空参数的值。

{
  fieldWithNonNullArg(nonNullArg: null)
}

案例：一个可空的变量不能作为非空参数的值。

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

Non‐Null type validation/非空类型验证

1. 一个非空类型不可封装另一个非空类型。

3.2.1@skip

@skip指令可用于字段、片段展开以及内联片段，从而能够在执行期间通过if参数完成条件性排除。

下列案例中，experimentalField只有在$someTest为false的时候才会被查询。

query myQuery($someTest: Boolean) {
  experimentalField @skip(if: $someTest)
}

3.2.2@include

@include指令可用于字段、片段展开以及内联片段，从而能够在执行期间通过if参数完成条件性包含。

下列案例中，experimentalField只有在$someTest为true的时候才会被查询。

query myQuery($someTest: Boolean) {
  experimentalField @include(if: $someTest)
}

4.1.1Naming conventions/命名约定

GraphQL内省系统要求的类型和字段与用户定义的类型和系统共享相同的上下文，其字段名以"__"双下划线开头，以避免和用户定义的GraphQL类型命名冲突。相反地，GraphQL类型系统作者不能定义任何以双下划线开头的类型、字段、参数和其他类型系统工件。artifact的翻译不确定

4.1.2Documentation/文档

所有内省系统中的类型必须提供String类型的description字段，以便类型设计者发布文档以增强能力。GraphQL服务可以返回使用Markdown语法（CommonMark中指定）的description字段。因此建议所有展示description字段的工具使用CommonMark兼容的Markdown渲染器。

4.1.3Deprecation/弃用

为了支持向后兼容管理，GraphQL字段和枚举值可以指出其是否弃用(isDeprecated: Boolean)和一个为何弃用的描述(deprecationReason: String)。

基于GraphQL内省系统建造的工具应该通过隐含信息或者面向开发者的警告信息来减少弃用字段的使用。

4.1.4Type Name Introspection/类型命名内省

GraphQL支持类型命名自行，查询任意对象/接口/联合时可以在一个查询语句的任意位置通过元字段__typename: String!，得到当前查询的对象类型。

这在查询接口或者联合类型的真实类型的时候用得最为频繁。

这是个隐式字段，并不会出现在定义的类型的字段列表中。

4.2.1The __Type Type/__Type类型

__Type是这个类型内省系统的核心，它代表了这个系统中的标量、接口、对象类型、联合、枚举型。

__Type也表示类型修改器，其通常用于表示修改一个类型(ofType: __Type)，这正是我们如何表示列表类型和非空类型，以及他们的组合类型。

4.2.2Type Kinds/类型种类

类型系统中存在多个种类的类型，每种类型都有不同的有效字段，这些类型都被列举在__TypeKind枚举值中。

input Point {
  x: Int
  y: Int
}

4.2.3The __Field Type/__Field类型

__Field类型表示对象或者接口类型的每一个字段。

字段

• name必须返回字符串。
• description必须返回字符串或者null空值。
• args返回__InputValue的列表，表示这个字段接受的参数。
• type必须返回__Type，表示这个字段值的类型。
• isDeprecated返回true如果这个字段不应再被使用，否则false。
• deprecationReason可选，提供字段被弃用的原因。

4.2.4The __InputValue Type/__InputValue类型

__InputValue类型表示字段和指令的参数，如同输入对象的inputFields字段。

字段

• name必须返回字符串。
• description必须返回字符串或者null空值。
• type必须返回表示这个输入值期待的类型的__Type。
• defaultValue返回一个（使用GraphQL语言）字符串，表示这个输入值在运行时未提供值的情况下的默认值，如果这个输入值没有默认值，返回null空值。

4.2.5The __EnumValue Type/__EnumValue类型

__EnumValue表示枚举型的可能值之一。

字段

• name必须返回字符串。
• description必须返回字符串或者null空值。
• isDeprecated返回true如果这个字段不应再被使用，否则false。
• deprecationReason可选，提供字段被弃用的原因。

4.2.6The __Directive Type/__Directive类型

__Directive类型表示服务器支持的一个指令。

字段

• name必须返回字符串。
• description必须返回字符串或者null空值。
• locations返回__DirectiveLocation列表，表示指令可以放置的有效位置。
• args返回__InputValue的列表，表示这个字段接受的参数。

5.1.1Named Operation Definitions/具名操作定义

query getDogName {
  dog {
    name
  }
}

query getOwnerName {
  dog {
    owner {
      name
    }
  }
}

query getName {
  dog {
    name
  }
}

query getName {
  dog {
    owner {
      name
    }
  }
}

query dogOperation {
  dog {
    name
  }
}

mutation dogOperation {
  mutateDog {
    id
  }
}

5.1.2Anonymous Operation Definitions/匿名操作定义

{
  dog {
    name
  }
}

{
  dog {
    name
  }
}

query getName {
  dog {
    owner {
      name
    }
  }
}

5.1.3Subscription Operation Definitions/订阅操作定义

subscription sub {
  newMessage {
    body
    sender
  }
}

fragment newMessageFields on Message {
  body
  sender
}

subscription sub {
  newMessage {
    ... newMessageFields  
  }
}

subscription sub {
  newMessage {
    body
    sender
  }
  disallowedSecondRootField
}

subscription sub {
  newMessage {
    body
    sender
  }
  __typename
}

5.2.1Field Selections on Objects, Interfaces, and Unions Types/对象、接口和联合上的字段选择

Formal Specification/形式规范

• 对于文档中的每一个selection。
• 使fieldName为selection的目标字段。
• fieldName必须定义在范围内的类型上。

Explanatory Text/解释文本

字段选择的目标字段必须定义在选择集的范围类型上。对别名没有限制。

譬如下列片段无法通过验证：

fragment fieldNotDefined on Dog {
  meowVolume
}

fragment aliasedLyingFieldTargetNotDefined on Dog {
  barkVolume: kawVolume
}

对于接口，直接的字段选择只能在字段上操作，（接口）具体实现（对象）的字段与给定接口类型选择集的有效性没有相关性。

例如，以下是有效的：

fragment interfaceFieldSelection on Pet {
  name
}

而以下是无效的：

fragment definedOnImplementorsButNotInterface on Pet {
  nickname
}

因为联合上并没有定义字段，字段没法直接从联合类型选择集上选出，除了元字段__typename这个特例。联合类型选择集上的字段必须仅通过片段查询。

例如，以下是有效的：

fragment inDirectFieldSelectionOnUnion on CatOrDog {
  __typename
  ... on Pet {
    name
  }
  ... on Dog {
    barkVolume
  }
}

但是以下是无效的：

fragment directFieldSelectionOnUnion on CatOrDog {
  name
  barkVolume
}

5.2.2Field Selection Merging/字段选择合并

Formal Specification/形式规范

• 使set为GraphQL文档上定义的任意选择集。
• FieldsInSetCanMerge(set)必然为true。

FieldsInSetCanMerge(set)：

• 使fieldsForName为包含访问片段和内联片段的set中给定响应名的选择集。
• 假设fieldsForName有一对成员fieldA和fieldB：
  • SameResponseShape(fieldA, fieldB)必须为true。
  • 如果fieldA和fieldB的父类型一样或者都不为对象类型：
    • fieldA和fieldB必然有相同的字段名。
    • fieldA和fieldB必然有相同的参数集。
    • 使mergedSet为选择集fieldA和fieldB相加的结果。
    • FieldsInSetCanMerge(mergedSet)必然为true。

SameResponseShape(fieldA, fieldB)：

• 使typeA为fieldA的返回类型。
• 使typeB为fieldB的返回类型。
• 如果typeA或者typeB是Non‐Null非空类型。
  • typeA和typeB必然两个都是Non‐Null类型。
  • 使typeA为typeA的可空类型
  • 使typeB为typeB的可空类型
• 如果typeA或者typeB是List列表类型。
  • typeA和typeB必然两个都是List类型
  • 使typeA为typeA的元素类型
  • 使typeB为typeB的元素类型
  • 从第3步重复。
• 如果typeA或者typeB是Scalar标量或者Enum枚举型。
  • typeA和typeB必然是相同类型。
• 断言：typeA和typeB都是组合类型。
• 使mergedSet为选择集fieldA和fieldB相加的结果。
• 使fieldsForName为包含访问片段和内联片段的set中给定响应名的选择集。
• 假设fieldsForName有一对成员subfieldA和subfieldB：
  • SameResponseShape(subfieldA, subfieldB)必然为true。

Explanatory Text/解释文本

如果执行期间遇到了相同响应名的多个字段选择，执行的字段和参数以及结果值都应该避免歧义。然而，任意两个字段选择能在同一个对象里面遇到还是有效的，那只能是它们等价的情况。

对于简单的手写GraphQL，这个规则明显是一个开发者错误，然而对于嵌套片段，就很难手动检查到这个问题。

以下选择正确地合并：

fragment mergeIdenticalFields on Dog {
  name
  name
}

fragment mergeIdenticalAliasesAndFields on Dog {
  otherName: name
  otherName: name
}

以下则无法合并：

fragment conflictingBecauseAlias on Dog {
  name: nickname
  name
}

如果它们有相同的参数，那么这个相同的参数也会被合并。值和参数都能正确地合并。

例如以下正确地合并：

fragment mergeIdenticalFieldsWithIdenticalArgs on Dog {
  doesKnowCommand(dogCommand: SIT)
  doesKnowCommand(dogCommand: SIT)
}

fragment mergeIdenticalFieldsWithIdenticalValues on Dog {
  doesKnowCommand(dogCommand: $dogCommand)
  doesKnowCommand(dogCommand: $dogCommand)
}

以下并不正确得合并：

fragment conflictingArgsOnValues on Dog {
  doesKnowCommand(dogCommand: SIT)
  doesKnowCommand(dogCommand: HEEL)
}

fragment conflictingArgsValueAndVar on Dog {
  doesKnowCommand(dogCommand: SIT)
  doesKnowCommand(dogCommand: $dogCommand)
}

fragment conflictingArgsWithVars on Dog {
  doesKnowCommand(dogCommand: $varOne)
  doesKnowCommand(dogCommand: $varTwo)
}

fragment differingArgs on Dog {
  doesKnowCommand(dogCommand: SIT)
  doesKnowCommand
}

下面的字段不会合并在一起，然而它们也不会在同一个对象上相遇，所以它们是安全的：

fragment safeDifferingFields on Pet {
  ... on Dog {
    volume: barkVolume
  }
  ... on Cat {
    volume: meowVolume
  }
}

fragment safeDifferingArgs on Pet {
  ... on Dog {
    doesKnowCommand(dogCommand: SIT)
  }
  ... on Cat {
    doesKnowCommand(catCommand: JUMP)
  }
}

然而，字段响应必须形状上能合并，譬如，标量不可变。下列例子中，someValue可能是String或者Int：

fragment conflictingDifferingResponses on Pet {
  ... on Dog {
    someValue: nickname
  }
  ... on Cat {
    someValue: meowVolume
  }
}

5.2.3Leaf Field Selections/叶子节点选择

Formal Specification/形式规范

• 对于文档中的每一个selection
• 使selectionType为selection的结果类型
• 如果selectionType是一个标量：
  • 这个选择的下级选择必须为空
• 如果selectionType是一个接口、联合或者对象
  • 这个选择的下级选择必不为空

Explanatory Text/解释文本

标量上的字段选择是不允许的，标量在任何GraphQL查询的都只是叶子节点。

下列是有效的。

fragment scalarSelection on Dog {
  barkVolume
}

下列是无效的。

fragment scalarSelectionsNotAllowedOnBoolean on Dog {
  barkVolume {
    sinceWhen
  }
}

相反的，GraphQL查询的叶子字段选择必须为标量。在接口、联合或者对象上的选择也不允许没有下级选择。

假设schema有下列查询根类型的补充内容：

extend type QueryRoot {
  human: Human
  pet: Pet
  catOrDog: CatOrDog
}

以下案例是无效的

query directQueryOnObjectWithoutSubFields {
  human
}

query directQueryOnInterfaceWithoutSubFields {
  pet
}

query directQueryOnUnionWithoutSubFields {
  catOrDog
}

5.3.1Argument Names/参数名

Formal Specification/形式规范

• 对于文档中的每一个argument。
• 使argumentName为argument的名字。
• 使argumentDefinition为父字段提供的参数定义或者名为argumentName的的定义。
• argumentDefinition必然存在。

Explanatory Text/解释文本

提供给字段或者指令的每一个参数，必须在字段或者指令的可能参数集合中定义。

譬如下列是有效的：

fragment argOnRequiredArg on Dog {
  doesKnowCommand(dogCommand: SIT)
}

fragment argOnOptional on Dog {
  isHousetrained(atOtherHomes: true) @include(if: true)
}

下列是无效，因为command并没有定义在DogCommand上。

fragment invalidArgName on Dog {
  doesKnowCommand(command: CLEAN_UP_HOUSE)
}

而这个也是无效，因为unless并没有定义在@include上。

fragment invalidArgName on Dog {
  isHousetrained(atOtherHomes: true) @include(unless: false)
}

为了展示更复杂的参数案例，我们添加下列（补充内容）到我们的类型系统：

type Arguments {
  multipleReqs(x: Int!, y: Int!): Int!
  booleanArgField(booleanArg: Boolean): Boolean
  floatArgField(floatArg: Float): Float
  intArgField(intArg: Int): Int
  nonNullBooleanArgField(nonNullBooleanArg: Boolean!): Boolean!
  booleanListArgField(booleanListArg: [Boolean]!): [Boolean]
}

extend type QueryRoot {
  arguments: Arguments
}

参数的顺序并不重要，因此下列两个案例对有效的：

fragment multipleArgs on Arguments {
  multipleReqs(x: 1, y: 2)
}

fragment multipleArgsReverseOrder on Arguments {
  multipleReqs(y: 1, x: 2)
}

5.3.2Argument Uniqueness/参数唯一性

字段和指令将参数视作参数名到从参数值的映射，一个参数集合内有多于一个参数拥有一个样的参数名时将会产生歧义，也是无效的。

Formal Specification/形式规范

• 对于文档中的每一个argument。
• 使argumentName为argument的名字。
• 使arguments为参数集合中所有具有argumentName的名字且包含argument的所有参数。
• arguments必然是只包含argument的集合。

5.3.3Argument Values Type Correctness/参数值类型正确性

fragment goodBooleanArg on Arguments {
  booleanArgField(booleanArg: true)
}

fragment coercedIntIntoFloatArg on Arguments {
  floatArgField(floatArg: 1)
}

fragment stringIntoInt on Arguments {
  intArgField(intArg: "3")
}

fragment goodBooleanArg on Arguments {
  booleanArgField(booleanArg: true)
}

fragment goodNonNullArg on Arguments {
  nonNullBooleanArgField(nonNullBooleanArg: true)
}

fragment goodBooleanArgDefault on Arguments {
  booleanArgField
}

fragment missingRequiredArg on Arguments {
  nonNullBooleanArgField
}

fragment missingRequiredArg on Arguments {
  notNullBooleanArgField(nonNullBooleanArg: null)
}

5.4.1Fragment Declarations/片段声明

{
  dog {
    ...fragmentOne
    ...fragmentTwo
  }
}

fragment fragmentOne on Dog {
  name
}

fragment fragmentTwo on Dog {
  owner {
    name
  }
}

{
  dog {
    ...fragmentOne
  }
}

fragment fragmentOne on Dog {
  name
}

fragment fragmentOne on Dog {
  owner {
    name
  }
}

fragment correctType on Dog {
  name
}

fragment inlineFragment on Dog {
  ... on Dog {
    name
  }
}

fragment inlineFragment2 on Dog {
  ... @include(if: true) {
    name
  }
}

fragment notOnExistingType on NotInSchema {
  name
}

fragment inlineNotExistingType on Dog {
  ... on NotInSchema {
    name
  }
}

fragment fragOnObject on Dog {
  name
}

fragment fragOnInterface on Pet {
  name
}

fragment fragOnUnion on CatOrDog {
  ... on Dog {
    name
  }
}

fragment fragOnScalar on Int {
  something
}

fragment inlineFragOnScalar on Dog {
  ... on Boolean {
    somethingElse
  }
}

fragment nameFragment on Dog { # unused
  name
}

{
  dog {
    name
  }
}

5.4.2Fragment Spreads/片段解构

字段选择也被片段解构之间的互相调用决定。譬如目标片段的选择集和同级的引用目标片段相联合。

{
  dog {
    ...undefinedFragment
  }
}

{
  dog {
    ...nameFragment
  }
}

fragment nameFragment on Dog {
  name
  ...barkVolumeFragment
}

fragment barkVolumeFragment on Dog {
  barkVolume
  ...nameFragment
}

{
  dog {
    name
    barkVolume
    name
    barkVolume
    name
    barkVolume
    name
    # forever...
  }
}

{
  dog {
    ...dogFragment
  }
}

fragment dogFragment on Dog {
  name
  owner {
    ...ownerFragment
  }
}

fragment ownerFragment on Dog {
  name
  pets {
    ...dogFragment
  }
}

fragment dogFragment on Dog {
  ... on Dog {
    barkVolume
  }
}

fragment catInDogFragmentInvalid on Dog {
  ... on Cat {
    meowVolume
  }
}

fragment petNameFragment on Pet {
  name
}

fragment interfaceWithinObjectFragment on Dog {
  ...petNameFragment
}

fragment catOrDogNameFragment on CatOrDog {
  ... on Cat {
    meowVolume
  }
}

fragment unionWithObjectFragment on Dog {
  ...catOrDogNameFragment
}

fragment petFragment on Pet {
  name
  ... on Dog {
    barkVolume
  }
}

fragment catOrDogFragment on CatOrDog {
  ... on Cat {
    meowVolume
  }
}

fragment sentientFragment on Sentient {
  ... on Dog {
    barkVolume
  }
}

fragment humanOrAlienFragment on HumanOrAlien {
  ... on Cat {
    meowVolume
  }
}

fragment unionWithInterface on Pet {
  ...dogOrHumanFragment
}

fragment dogOrHumanFragment on DogOrHuman {
  ... on Dog {
    barkVolume
  }
}

fragment nonIntersectingInterfaces on Pet {
  ...sentientFragment
}

fragment sentientFragment on Sentient {
  name
}

5.5.1Input Object Field Uniqueness/输入对象字段唯一性

Formal Specification/形式规范

• 对于文档中的每一个输入对象值inputObject。
• 对于inputObject中的每一个inputField
  • 使name为inputField的名字
  • 使fields be all Input Object Fields named name in inputObject.
  • fields必然是仅包含inputField的集合。

Explanatory Text/解释文本

输入对象不能包含多余一个同名的字段，否则存在让部分句法被忽略的歧义。

例如，下列查询并不会通过验证。

{
  field(arg: { field: true, field: false })
}

5.6.1Directives Are Defined/指令必须预先定义

Formal Specification/形式规范

• 对于文档中的每一个directive。
• 使directiveName为directive的名字。
• 使directiveDefinition为名为directiveName的指令。
• directiveDefinition必然存在。

Explanatory Text/解释文本

GraphQL服务器定义他们支持的指令，对于每个指令的使用，必须要指令在服务器上可用。

5.6.2Directives Are In Valid Locations/指令必须在有效位置

Formal Specification/形式规范

• 对于文档中的每一个directive。
• 使directiveName为directive的名字。
• 使directiveDefinition为名为directiveName的指令。
• 使locations为directiveDefinition的有效位置。
• 使adjacent为收到指令影响的AST（抽象语法树）节点。
• adjacent必须以locations内的元素来表示。

Explanatory Text/解释文本

GraphQL定义了他们支持的指令，在何处支持。每一指令的使用，都必须在服务器声明支持使用的地方。

譬如，下列查询无法通过验证，因为@skip在QUERY上，并不是有效位置。

query @skip(if: $foo) {
  field
}

5.6.3Directives Are Unique Per Location/每个位置的指令都必须唯一

Formal Specification/形式规范

• 对于文档中指令可是应用的location：
  • 使directives为应用于location的指令集合。
  • 对于directives中的每一个directive：
    • 使directiveName为directive的名字。
    • 使namedDirectives为directives中名为directiveName的指令集合。
    • namedDirectives必然是只有一个值的集合。

Explanatory Text/解释文本

指令用于描述其应用的定义的元数据或者表现的改变。当同名的指令多次使用时，期望的源数据或者表现就会变得有歧义，因此一个位置上只允许使用一个指令。

譬如，下列查询不会通过验证，因为@skip在同一个字段上用了两次：

query ($foo: Boolean = true, $bar: Boolean = false) {
  field @skip(if: $foo) @skip(if: $bar)
}

但是下面案例是有效的，因为@skip在每个位置只用了一次，即便在查询中同名的字段上用了两次：

query ($foo: Boolean = true, $bar: Boolean = false) {
  field @skip(if: $foo) {
    subfieldA
  }
  field @skip(if: $bar) {
    subfieldB
  }
}

5.7.1Variable Uniqueness/变量唯一性

Formal Specification/形式规范

• 对于文档中的每一个operation
  • 对于operation中定义的每一个variable
    • 使variableName为variable的名字
    • 使variables为operation上名为variableName的变量集合
    • variables必然是只有一个值的集合。

Explanatory Text/解释文本

任意操作定了多于一个同名变量，将会变得有歧义，并是无效的。即便重复变量的值是一样的，他也是无效的。

query houseTrainedQuery($atOtherHomes: Boolean, $atOtherHomes: Boolean) {
  dog {
    isHousetrained(atOtherHomes: $atOtherHomes)
  }
}

多个操作可以具有相同的变量名，特别是两个操作引用了同一个片段，这时候同名变量就是必要的了：

query A($atOtherHomes: Boolean) {
  ...HouseTrainedFragment
}

query B($atOtherHomes: Boolean) {
  ...HouseTrainedFragment
}

fragment HouseTrainedFragment {
  dog {
    isHousetrained(atOtherHomes: $atOtherHomes)
  }
}

5.7.2Variable Default Values Are Correctly Typed/变量默认值必须是正确的类型

Formal Specification/形式规范

• 对于文档中的每一个operation
• 对于每一个operation上的每一个variable
  • 使variableType为variable的类型
  • 如果variableType是non‐null非空，则不能有默认值。
  • 如果variable有默认值，则其必须是同样的类型或者能转换到variableType

Explanatory Text/解释文本

操作中定一个变量都是可以定义默认值的，如果对应类型不是non‐null。

例如，下列查询能通过验证。

query houseTrainedQuery($atOtherHomes: Boolean = true) {
  dog {
    isHousetrained(atOtherHomes: $atOtherHomes)
  }
}

但是如果变量被定义为非空类型，那么默认值是不可达的，因此下列如同这样的查询就不会通过验证

query houseTrainedQuery($atOtherHomes: Boolean! = true) {
  dog {
    isHousetrained(atOtherHomes: $atOtherHomes)
  }
}

默认值必须和变量类型兼容，必须是匹配或者能转换到这种类型。

不匹配的类型会失败，如下例：

query houseTrainedQuery($atOtherHomes: Boolean = "true") {
  dog {
    isHousetrained(atOtherHomes: $atOtherHomes)
  }
}

然而如果类型是可转换的，查询就能通过。

例如：

query intToFloatQuery($floatVar: Float = 1) {
  arguments {
    floatArgField(floatArg: $floatVar)
  }
}

5.7.3Variables Are Input Types/变量必须是输入类型

Formal Specification/形式规范

• 对document中的每一个operation
• 对每一个operation上的每一个variable
  • 使variableType为variable的类型
  • 当variableType是LIST或者NON_NULL
    • 使variableType为variableType引用的类型
  • variableType必然是SCALAR、ENUM或者INPUT_OBJECT类型

Explanatory Text/解释文本

变量只能是标量、枚举型和输入对象，或者这些类型的列表和非空封装变体，这些是输入类型。而对象、联合、接口不能作为输入。

对于这些的案例，假设有如下类型系统补充内容：

input ComplexInput { name: String, owner: String }

extend type QueryRoot {
  findDog(complex: ComplexInput): Dog
  booleanList(booleanListArg: [Boolean!]): Boolean
}

下列查询是有效的：

query takesBoolean($atOtherHomes: Boolean) {
  dog {
    isHousetrained(atOtherHomes: $atOtherHomes)
  }
}

query takesComplexInput($complexInput: ComplexInput) {
  findDog(complex: $complexInput) {
    name
  }
}

query TakesListOfBooleanBang($booleans: [Boolean!]) {
  booleanList(booleanListArg: $booleans)
}

下列查询是无效的：

query takesCat($cat: Cat) {
  # ...
}

query takesDogBang($dog: Dog!) {
  # ...
}

query takesListOfPet($pets: [Pet]) {
  # ...
}

query takesCatOrDog($catOrDog: CatOrDog) {
  # ...
}

5.7.4All Variable Uses Defined/所有变量的使用必须预先定义

Formal Specification/形式规范

• 对于文档中的每一个operation
  • 对于范围内的每一个variableUsage，变量必须在operation的变量列表中。
  • 使fragments为operation传递引用的每一个片段
  • 对于fragments中的每一个fragment
    • 对于fragment范围内的每一个variableUsage，变量必须在operation的变量列表中。

Explanatory Text/解释文本

变量的有效范围是在每一个操作内的，也就是说任何在操作上下文中要使用的变量，必须在那个操作的顶部预先定义。

例如：

query variableIsDefined($atOtherHomes: Boolean) {
  dog {
    isHousetrained(atOtherHomes: $atOtherHomes)
  }
}

是有效的，$atOtherHomes由这个操作定义。

相反，下面这个操作是无效的：

query variableIsNotDefined {
  dog {
    isHousetrained(atOtherHomes: $atOtherHomes)
  }
}

$atOtherHomes并没有被操作定义。

片段使这个规则复杂，被操作引入的任何片段都能接入那个操作定义的变量。片段可以出现在多个操作内，因此变量的使用必须和所有操作上的变量定义对应。

譬如，下列是有效的：

query variableIsDefinedUsedInSingleFragment($atOtherHomes: Boolean) {
  dog {
    ...isHousetrainedFragment
  }
}

fragment isHousetrainedFragment on Dog {
  isHousetrained(atOtherHomes: $atOtherHomes)
}

因为isHousetrainedFragment在variableIsDefinedUsedInSingleFragment操作的上下文中使用，其参数也被也在这个操作上定义。

另一面，如果操作内引入的片段所使用的参数并没有在操作上定义，那么这个查询是无效的。

query variableIsNotDefinedUsedInSingleFragment {
  dog {
    ...isHousetrainedFragment
  }
}

fragment isHousetrainedFragment on Dog {
  isHousetrained(atOtherHomes: $atOtherHomes)
}

这也是传递应用的，所以下列会失败：

query variableIsNotDefinedUsedInNestedFragment {
  dog {
    ...outerHousetrainedFragment
  }
}

fragment outerHousetrainedFragment on Dog {
  ...isHousetrainedFragment
}

fragment isHousetrainedFragment on Dog {
  isHousetrained(atOtherHomes: $atOtherHomes)
}

片段使用的变量必须在所有的操作上定义。

query housetrainedQueryOne($atOtherHomes: Boolean) {
  dog {
    ...isHousetrainedFragment
  }
}

query housetrainedQueryTwo($atOtherHomes: Boolean) {
  dog {
    ...isHousetrainedFragment
  }
}

fragment isHousetrainedFragment on Dog {
  isHousetrained(atOtherHomes: $atOtherHomes)
}

然而下面这个并不通过验证：

query housetrainedQueryOne($atOtherHomes: Boolean) {
  dog {
    ...isHousetrainedFragment
  }
}

query housetrainedQueryTwoNotDefined {
  dog {
    ...isHousetrainedFragment
  }
}

fragment isHousetrainedFragment on Dog {
  isHousetrained(atOtherHomes: $atOtherHomes)
}

这是因为housetrainedQueryTwoNotDefined并没有定变量$atOtherHomes，但是这个变量被isHousetrainedFragment操作引入使用。

5.7.5All Variables Used/所有变量都必须被使用

Formal Specification/形式规范

• 对于文档中的每一个operation。
• 使variables为operation上定义的变量。
• variables中的每一个variable必须至少被使用一次，无论是操作本身使用，还是操作引入的片段通过传递引用使用。

Explanatory Text/解释文本

操作上定义的所有变量必须至少被使用一次，无论是操作本身使用，还是操作引入的片段通过传递引用使用。未使用的变量会导致验证错误。

例如，下列是无效的：

query variableUnused($atOtherHomes: Boolean) {
  dog {
    isHousetrained
  }
}

因为$atOtherHomes没有被引用过。

这个规则也适用于片段解构的传递引用：

query variableUsedInFragment($atOtherHomes: Boolean) {
  dog {
    ...isHousetrainedFragment
  }
}

fragment isHousetrainedFragment on Dog {
  isHousetrained(atOtherHomes: $atOtherHomes)
}

上面是有效的，因为$atOtherHomes在isHousetrainedFragment中被使用过了，其由variableUsedInFragment引入。

如果那个片段没有引用$atOtherHomes，则是无效的：

query variableNotUsedWithinFragment($atOtherHomes: Boolean) {
  ...isHousetrainedWithoutVariableFragment
}

fragment isHousetrainedWithoutVariableFragment on Dog {
  isHousetrained
}

一个文档中的所有操作都必须使用他们所有的变量。

从而，下列文档是无效的：

query queryWithUsedVar($atOtherHomes: Boolean) {
  dog {
    ...isHousetrainedFragment
  }
}

query queryWithExtraVar($atOtherHomes: Boolean, $extra: Int) {
  dog {
    ...isHousetrainedFragment
  }
}

fragment isHousetrainedFragment on Dog {
  isHousetrained(atOtherHomes: $atOtherHomes)
}

这个文档是无效的，因为queryWithExtraVar定义了额外的一个变量。

5.7.6All Variable Usages are Allowed/所有变量都允许使用

Formal Specification/形式规范

• document中的每一个operation
• 使variableUsages为operation引入的所有传递使用。
• 对于variableUsages中的每一个variableUsage
  • 使variableType为operation上的变量定义的的类型。
  • 使argumentType为传递进去的参数的类型。
  • 使hasDefault为true，如果参数定义有默认值。
  • AreTypesCompatible(argumentType, variableType, hasDefault)必然为true
• AreTypesCompatible(argumentType,variableType, hasDefault)：
  • 如果hasDefault为true，把variableType当作non‐null非空。
  • 如果argumentType和variableType的内部类型不相同，返回falae
  • 如果argumentType和variableType的列表纬度不相同，返回falae
  • 如果variableType的任意列表层级不是non‐null，而argument对应的是non‐null，则类型不兼容。

Explanatory Text/解释文本

变量使用必须和它们传递进去的参数兼容。

验证失败会发生在变量在类型上下文完全不匹配和传递可空类型参数给非空类型变量的时候。

类型必须匹配：

query intCannotGoIntoBoolean($intArg: Int) {
  arguments {
    booleanArgField(booleanArg: $intArg)
  }
}

$intArg是Int类型，不能作为参数传递给Boolean类型的booleanArg。

列表基数也必须一样。例如，列表不能传递给单数值。

query booleanListCannotGoIntoBoolean($booleanListArg: [Boolean]) {
  arguments {
    booleanArgField(booleanArg: $booleanListArg)
  }
}

可空性也同样重要。通常，空值变量不可传递给非空变量。

query booleanArgQuery($booleanArg: Boolean) {
  arguments {
    nonNullBooleanArgField(nonNullBooleanArg: $booleanArg)
  }
}

主要注意的例外是有默认参数的情况，这个参数会被视作非空。

query booleanArgQueryWithDefault($booleanArg: Boolean = true) {
  arguments {
    nonNullBooleanArgField(nonNullBooleanArg: $booleanArg)
  }
}

对于列表类型，跟可空性类似的规则同时应用与外部和内部类型，一个可空列表不能传入一个非空列表，一个可空值的列表不能传递给一个非空值的列表。 下列是有效的：

query nonNullListToList($nonNullBooleanList: [Boolean]!) {
  arguments {
    booleanListArgField(booleanListArg: $nonNullBooleanList)
  }
}

然而，一个可空列表不能传入一个非空列表：

query listToNonNullList($booleanList: [Boolean]) {
  arguments {
    nonNullBooleanListField(nonNullBooleanListArg: $booleanList)
  }
}

这个的验证会失败，因为[T]不能传递给[T]!。

类似的，[T]也不能传递给[T!]。

6.1.1Validating Requests/验证请求

如同验证章节中解释的一样，只有通过了所有验证的请求才应该被执行。如果得到了验证错误，它们将被添加到响应中的“errors”列表中，而这个请求也就不执行直接失败。

典型的情况下，验证将在请求执行之前的上下文内瞬间完成，但是在一个相同请求之前已经验证过的情况下，GraphQL服务可能直接执行而不验证。GraphQL服务只应该执行那些某个时间点上没有验证错误也没更改过的请求。

例如：一个请求在开发期已经通过验证，并假设他后面不会改变，或者服务器层验证了一个请求，记住了它的验证结果以避免后续再次验证同样的请求。

6.1.2Coercing Variable Values/转换变量值

如果操作定义了任何变量，然后这些变量的值需要根据变量声明的类型的输入转换规则而转换。如果变量值的输入转换中发生了查询错误，操作会不执行直接失败。

CoerceVariableValues(schema, operation, variableValues)：

• 使coercedValues为一个空的无序Map/映射集。
• 使variableDefinitions为operation定义的变量。
• 对于variableDefinitions中的每一个variableDefinition：
  • 使variableName为variableDefinition的名字。
  • 使variableType为variableDefinition的期望类型。
  • 使defaultValue为variableDefinition的默认值。
  • 使value为variableValues中给名为variableName的变量提供的值。
  • 如果value并不存在(variableValues中并未提供)：
    • 如果defaultValue存在(包括null)：
      • 给coercedValues添加一个名为variableName值为defaultValue的条目。
    • 或者如果variableType是一个Non‐Nullable/非空类型，抛出一个查询错误。
    • 否则，继续处理下一个变量定义。
  • 或者, 如果value无法根据variableType的输入转换规则转换，抛出一个查询错误。
  • 使coercedValue为根据variableType的输入转换规则转换的结果。
  • 给coercedValues添加一个名为variableName值为coercedValue的条目。
• 返回coercedValues。

6.2.1Query/查询

如果操作是一个查询，那操作的结果就是用查询根级对象类型执行查询的顶层选择集的结果。

执行一个查询的时候可以提供一个初始值。

ExecuteQuery(query, schema, variableValues, initialValue)：

• 使queryType为schema中的根级查询类型。
• 断言：queryType是一个对象类型。
• 使selectionSet为query中的顶层选择集。
• 使data为正常执行ExecuteSelectionSet(selectionSet, queryType, initialValue, variableValues)的结果(允许并行)。
• 使errors为执行选择集期间产生的任何字段错误。
• 返回一个包含data和errors的无序映射集。

6.2.2Mutation/更改

如果操作是一个更改，那操作的结果就是用更改根级对象类型执行更改的顶层选择集的结果。这个选择集应该依次执行。

更改的顶层字段被期望用于在下层数据系统上执行副作用操作。依次执行这些更改，以保证副作用操作期间没有竞态条件。

ExecuteMutation(mutation, schema, variableValues, initialValue)：

• 使mutationType为schema的根级更改类型。
• 断言：mutationType是一个对象类型。
• 使selectionSet为mutation中的顶层选择集。
• 使data为依次执行ExecuteSelectionSet(selectionSet, mutationType, initialValue, variableValues)的结果
• 使errors为执行选择集期间产生的任何字段错误。
• 返回一个包含data和errors的无序映射集。

6.2.3Subscription/订阅

如果操作是一个订阅，那结果是一个事件流，称作“Response Stream”响应流，事件流中的每一个事件即是针对下层“Source Stream”源流上的新事件执行操作的结果。

执行订阅会在服务端创建一个永久的函数，用于将下层源流映射成返回的响应流。

Subscribe(subscription, schema, variableValues, initialValue)：

• 使sourceStream为CreateSourceEventStream(subscription, schema, variableValues, initialValue)执行的结果。
• 使responseStream为MapSourceToResponseEvent(sourceStream, subscription, schema, variableValues)执行的结果。
• 返回responseStream。

考虑一个聊天应用案例。客户端发送一个如下请求来订阅投递到聊天室的新消息：

subscription NewMessages {
  newMessage(roomId: 123) {
    sender
    text
  }
}

当客户端订阅后，任何时候有ID为“123”的新消息投递到聊天室后，对于“sender”和“text”的选择将会被执行然后发布到客户端。例如：

{
  "data": {
    "newMessage": {
      "sender": "Hagrid",
      "text": "You're a wizard!"
    }
  }
}

”新消息投递到聊天室”可以使用了“Pub‐Sub”发布订阅系统，其中聊天室ID是“topic”，并且每一个“publish”都包含了“sender”发送者和“text”文本。

Event Streams

事件流表示一序列可观测的离散事件。例如，一个“Pub‐Sub”系统当“subscribing to a topic”订阅了一个话题可能产生一个事件流，每一次“publish”发布到话题都会在事件流上产生一个事件。事件流可能产生一序列无尽的事件，也可能在任何时候终止。响应中的事件流可能因为发生错误而终止，也可能仅仅因为没有后续事件发生。观察者可以在任何时候取消订阅而停止观察事件流，这之后就不会从事件流中收到后续事件了。

Supporting Subscriptions at Scale/支持大规模订阅

支持订阅对GraphQL服务器而言是一个显著的变化。查询和更改操作是无状态的，可以通过克隆GraphQL服务器实例而扩展规模。订阅却相反，它是有状态的，要求在这个订阅的生命周期内维持文档、变量和其他上下文。

考虑下你服务中某个机器宕机状态丢失的时候，你的系统的行为。使用分离的专用服务器来处理订阅状态和客户端连接将能提升系统的持久性和可用性。

6.3.1Normal and Serial Execution/正常序列执行

正常情况下，不论分组字段集合中的条目顺序为何，执行器都能执行（通常是并行执行）。因为除了顶层更改必然有副作用且具有幂等性，字段解析的执行顺序必然不会影响其结果，因此服务器能够以他认为优化的方式自由地执行字段条目。

例如，有下正常执行的分组字段：

{
  birthday {
    month
  }
  address {
    street
  }
}

一个有效的GraphQL执行器可以以任何他选择的顺序来解析这四个字段（然而，birthday必然在month之前，同理address在street之前）。

当执行更改时，最顶层的选择集会依序执行。

当依序执行一个分组字段集的时候，执行器必须以每个条目出现在分组字段集中的顺序来决定在结果映射集对应的条目，使得分组映射集中每一个条目完成之后才继续下一个条目。

例如，有以依序执行的选择集：

{
  changeBirthday(birthday: $newBirthday) {
    month
  }
  changeAddress(address: $newAddress) {
    street
  }
}

执行器必须依序执行：

• 执行changeBirthday的ExecuteField()，其中CompleteValue()期间，会正常执行{ month }次级选择集。
• 执行changeAddress的ExecuteField()，其中CompleteValue()期间，会正常执行{ street }次级选择集。

举一个说明性的例子，假设我们有一个mutation字段changeTheNumber，其返回包含一个theNumber字段的对象。如果我们依序执行下列选择集：

{
  first: changeTheNumber(newNumber: 1) {
    theNumber
  }
  second: changeTheNumber(newNumber: 3) {
    theNumber
  }
  third: changeTheNumber(newNumber: 2) {
    theNumber
  }
}

执行器会如下依序执行：

• 解析changeTheNumber(newNumber: 1)字段
• 正常执行first次级选择集{ theNumber }
• 解析changeTheNumber(newNumber: 3)字段
• 正常执行second次级选择集{ theNumber }
• 解析changeTheNumber(newNumber: 2)字段
• 正常执行third次级选择集{ theNumber }

正确的执行器，对于上述选择集必然会生成如下结果：

{
  "first": {
    "theNumber": 1
  },
  "second": {
    "theNumber": 3
  },
  "third": {
    "theNumber": 2
  }
}

6.3.2Field Collection/字段集合

执行之前，通过调用CollectFields()，选择集会被转换成分组字段集。分组字段集中的每一个条目都是共享同一个响应键的列表。这保证了同一个响应键（别名或者字段名）内所有的字段，包含通过片段引入的，都能同时执行。

如果，手机如下选择集的字段会收集到两个a字段的实体和一个b字段的实体：

{
  a {
    subfield1
  }
  ...ExampleFragment
}

fragment ExampleFragment on Query {
  a {
    subfield2
  }
  b
}

CollectFields()生成的字段分组的深度优先搜索通过执行来保持，保证字段在执行后响应中以稳定可预测的顺序出现。

CollectFields(objectType, selectionSet, variableValues, visitedFragments)：

• 如果未提供visitedFragments，将其初始化为空集。
• 初始化groupedFields为列表的空的有序集。
• 对于selectionSet中的每一个selection：
  • 如果selection提供了@skip指令，使skipDirective为此指令。
    • 如果skipDirective的if参数是true或者是variableValues中的一个为true的变量，则继续selectionSet中的下一个selection。
  • 如果selection提供了@include指令，使includeDirective为此指令。
    • 如果includeDirective参数不是true或者不是variableValues中的一个为true的变量，则继续selectionSet中的下一个selection。
  • 如果selection是一个Field：
    • 使responseKey为selection中的响应键。
    • 使groupForResponseKey为groupedFields中的一个responseKey列表；如果不存在这么一个列表，则创建一个空列表。
    • 附加selection到groupForResponseKey上。
  • 如果selection是一个FragmentSpread：
    • 使fragmentSpreadName为selection的名字。
    • 如果fragmentSpreadName在visitedFragments中，则继续selectionSet中的下一个selection。
    • 添加fragmentSpreadName到visitedFragments上。
    • 使fragment为当前文档中名为fragmentSpreadName的片段。
    • 如果不存在那样的fragment，则继续selectionSet中的下一个selection。
    • 使fragmentType为fragment上的类型条件。
    • 如果DoesFragmentTypeApply(objectType, fragmentType)为false，则继续selectionSet中的下一个selection。
    • 使fragmentSelectionSet为fragment的顶层选择集。
    • 使fragmentGroupedFieldSet为调用CollectFields(objectType, fragmentSelectionSet, visitedFragments)的结果。
    • 对于fragmentGroupedFieldSet中的每一个fragmentGroup：
      • 使responseKey为fragmentGroup中所有字段共享的响应键。
      • 使groupForResponseKey为groupedFields中的responseKey列表；如果不存在这么一个列表，则创建一个空列表。
      • 附加fragmentGroup中所有的元素到groupForResponseKey上。
  • 如果selection是一个InlineFragment：
    • 使fragmentType为selection上的类型条件。
    • 如果fragmentType不为null且DoesFragmentTypeApply(objectType, fragmentType)是false，则继续selectionSet中的下一个selection。
    • 使fragmentSelectionSet为selection的顶层选择集。
    • 使fragmentGroupedFieldSet为调用CollectFields(objectType, fragmentSelectionSet, variableValues, visitedFragments)的结果。
    • 对于fragmentGroupedFieldSet中的每一个fragmentGroup：
      • 使responseKey为为fragmentGroup中所有字段共享的响应键
      • 使groupForResponseKey为groupedFields中的responseKey列表；如果不存在这么一个列表，则创建一个空列表。
        • 附加fragmentGroup中所有的元素到groupForResponseKey上。
• 返回groupedFields。

DoesFragmentTypeApply(objectType, fragmentType)：

• 如果fragmentType是一个对象类型：
  • 如果objectType和fragmentType是同类型，返回true，否则返回false。
• 如果fragmentType是一个接口类型：
  • 如果objectType是fragmentType的一个实现，返回true，否则返回false。
• 如果fragmentType是一个联合：
  • 如果objectType是fragmentType的一个可能类型，返回true，否则返回false。

6.4.1Coercing Field Arguments/转换字段参数

字段可能包含下层运行时产生正确结果的参数，这些参数定义在类型系统中的字段上，都有一个特定的输入类型：Scalars标量、Enum庙举行、Input Object输入对象，或者这三个的List列表和Non‐Null非空封装。

对于查询中每个参数的位置，可能是一个字面量值，也可能是运行时提供的变量。

CoerceArgumentValues(objectType, field, variableValues)：

• 使coercedValues为空的无序映射集。
• 使argumentValues为field提供的参数值。
• 使fieldName为field的名字。
• 使argumentDefinitions为objectType上字段名fieldName定义的参数。
• 对于argumentDefinitions中的每一个argumentDefinition：
  • 使argumentName为argumentDefinition的名字。
  • 使argumentType为argumentDefinition的期待类型。
  • 使defaultValue为argumentDefinition的默认值。
  • 使value为argumentValues中针对argumentName提供的值。
  • 如果value是一个变量：
    • 使variableName为value变量的名字。
    • 使variableValue为variableValues中针对variableName提供的值。
    • 如果variableValue存在(包含null)：
      • 添加名为argName值为variableValue的条目到coercedValues。
    • 否则，如果defaultValue存在(包含null)：
      • 添加名为argName值为defaultValue的条目到coercedValues。
    • 否则，如果argumentType是一个Non‐Nullable非空类型，抛出字段错误。
    • 否则，继续下一个参数定义。
  • 否则，如果value不存在(argumentValues中未提供)：
    • 如果defaultValue存在(包含null)：
      • 添加名为argName值为defaultValue的条目到coercedValues。
    • 否则，如果argumentType是一个Non‐Nullable非空类型，抛出字段错误。
    • 否则，继续下一个参数定义。
  • 否则, 如果value不能根据argType的输入转换规则转换，抛出字段错误。
  • 使coercedValue为根据argType的输入转换规则转换value的结果。
  • 添加名为argName值为variableValue的条目到coercedValues。
• 返回coercedValues。

6.4.2Value Resolution/值解析

虽然几乎所有的GraphQL执行都能通用化描述，但最终内部系统暴露给GraphQL接口的时候必须提供值。这通过ResolveFieldValue暴露，其生成真实值的类型上给定字段的值，

在案例中，这个可能接收objectType/对象类型Person，其field/字段为"soulMate"，这个objectValue/类型值表示John Lennon。它可能被期待得到值表示Yoko Ono。

ResolveFieldValue(objectType, objectValue, fieldName, argumentValues)：

• 使resolver为objectType提供的内部函数，用以决定名为fieldName的字段的解析值。
• 返回使用objectValue和argumentValues调用resolver的结果。

6.4.3Value Completion/值完成

在解析一个字段的值后，再确认其符合期望返回类型即完成。如果返回值是另一个对象类型，然后字段执行将继续递归。

CompleteValue(fieldType, fields, result, variableValues)：

• 如果fieldType是一个Non‐Null非空类型：
  • 使innerType为fieldType的内部类型。
  • 使completedResult为调用CompleteValue(innerType, fields, result, variableValues)的结果。
  • 如果completedResult是null，抛出一个字段错误。
  • 返回completedResult。
• 如果result是null (或者另一种类似于的null内部值，譬如undefined或NaN), 返回null。
• 如果fieldType是一个List列表类型：
  • 如果result并不是一个值的集合，抛出一个字段错误。
  • 使innerType为fieldType的内部类型。
  • 返回一个列表，其中每个列表元素都是调用CompleteValue(innerType, fields, resultItem, variableValues)的结果，其中resultItem为result中的每个元素。。
• 如果fieldType是Scalar标量或者Enum枚举类型：
  • 返回“转换”result的结果，保证其为fieldType的合法值，否则为null。
• 如果fieldType是Object对象，Interface接口，或者Union类型：
  • 如果fieldType是一个Object对象类型。
    • 使objectType为fieldType。
  • Otherwise 如果fieldType是一个Interface接口，或者Union类型。
    • 使objectType为ResolveAbstractType(fieldType, result)。
  • 使subSelectionSet为调用MergeSelectionSets(fields)的结果。
  • 返回ExecuteSelectionSet(subSelectionSet, objectType, result, variableValues)正常求值的结果(允许并行)。

Resolving Abstract Types/解析抽象类型

当完成一个具有抽象返回类型的字段时，譬如Interface接口或者Union联合返回类型，首先，抽象类型必须接地到一个相关的对象类型上去，这个由内部系统决定哪一个是合适的。

ResolveAbstractType(abstractType, objectValue)：

• 返回调用系统提供的内部方法的结果，此方法用于决定给定值objectValue的abstractType的对象类型。

Merging Selection Sets/合并选择集

当多余一个同名字段并行执行后，他们的选择集在完成这个值的时候被合并，以继续次级选择集的执行。

案例查询中，描述了带次级选择集的同名的并行字段。

{
  me {
    firstName
  }
  me {
    lastName
  }
}

当解析了 me的值后，选择集将合并，所以firstName和lastName可以被解析到一个值上。

MergeSelectionSets(fields)：

• 使selectionSet为一个空列表。
• 对于 fields中的每一个field：
  • 使fieldSelectionSet为field的选择集。
  • 如果fieldSelectionSet是null或者empty，继续下一个字段。
  • 将fieldSelectionSet中所有的选择集添加到selectionSet。
• 返回selectionSet。

6.4.4Errors and Non-Nullability/错误与非空

当解析一个字段时抛出了错误，它应该被当作这个字段返回了null，且错误必须添加到响应的"errors"列表中。

如果一个字段解析的结果就是null（不论是字段的解析函数返回了null还是发生了错误），且那个字段是Non-Null，那么抛出一个字段错误。这个错误必须添加到响应的"errors"列表中。

如果字段因为错误而返回了null，这个错误也被添加到了响应的"errors"列表中，这个"errors"列表后续就不应被影响，即是，错误列表中一个字段上只允许添加一个错误。

因为Non-Null类型不能为null，字段错误将会冒泡到父级字段并被父级字段处理。如果父级字段可能为null，那么它就解析为null，否则如果父级字段也是Non-Null类型，那么这个字段错误将会继续冒泡到上一级父级字段。

如果从请求的根到错误的源的所有字段都返回Non-Null条目，那么响应中的"data"条目应该为null。

7.1.1JSON Serialization/JSON序列化

虽然如上所述，GraphQL并不要求一种特定的序列化格式，但是还是比较偏好于JSON。为了风格统一和易于标注，本规范中响应的案例都以JSOn的格式表示，特别需要注意的是，我们的JSON案例中，原始类型都以一下JSON概念来表示：

Object Property Ordering/对象属性排序

JSON被描述为无序键值对集合，而键值对在表示上确实有序的方式。换言之，即便JSON字符串{ "name": "Mark", "age": 30 }和{ "age": 30, "name": "Mark" }编码了相同的值，但是他们却有不同的属性表示顺序。

选择集的求值结果是有序的，这个顺序来源于请求，并由查询执行器定义，因此JSON序列化可以保持这个顺序，并以这个顺序写入到对象属性中。

譬如，如果查询是{ name, age }，则GraphQL服务器响应的JSON会是{ "name": "Mark", "age": 30 }而不是{ "age": 30, "name": "Mark" }。

7.2.1Data/数据

响应中的data条目是请求的操作执行的结果。如果操作是query/查询，输出则是schema查询的根级类型对象，如果操作是mutation/更改，输出则是schema更改的根级类型对象。

如果在执行前遇到错误，结果中将不应有data条目。

如果在执行中遇到错误，并导致不能返回有效响应，则data条目应该为null。

7.2.2Errors/错误

响应中的errors是一个非空错误列表，每个错误是一个映射集。

如果在执行请求的操作中未遇到错误，结果中将不应有errors条目。

如果响应结果中没有data条目，则响应中的errors条目不可为空，其必须包含至少一条错误，这个错误应指出为什么没有数据返回。

如果响应中包含data条目（包含值为null的情况），那么响应中的errors条目可以包含执行期间的任何错误。如果执行期发生了错误，那这个错误就应该被包含。

Error result format/错误结果格式

每个错误都必须包含键为message的条目，其包含了针对开发这错误描述，以便修正错误。

如果一个错误能和请求的GraphQL文档特定点所匹配，它应该包含键为locations的条目，其内容为一个定位列表，每个定位都是键为line和column的映射集，两者都是从1开始的正数，用以描述相关的语法元素的起始位置。

如果一个错误能和GraphQL结果中的特定字段关联，它必须包含键为path的条目，其描述了响应中哪一个字段面临了错误。这能让客户端鉴别一个null是正常逻辑还是运行时错误。

这个字段应该是一个路径段的列表，从响应根级开始直到关联的字段结束。用于表示字段的路径段应该是字符串类型，而表示列表索引的路径段则应该是从0开始的整数。如果错误发生在别名字段，那对应的路径应该使用别名，因为其表示的是响应中的路径而非查询中的。

例如，如果下列查询中，获取一个朋友的名字失败了：

{
  hero(episode: $episode) {
    name
    heroFriends: friends {
      id
      name
    }
  }
}

响应会像这样：

{
  "errors": [
    {
      "message": "Name for character with ID 1002 could not be fetched.",
      "locations": [ { "line": 6, "column": 7 } ],
      "path": [ "hero", "heroFriends", 1, "name" ]
    }
  ],
  "data": {
    "hero": {
      "name": "R2-D2",
      "heroFriends": [
        {
          "id": "1000",
          "name": "Luke Skywalker"
        },
        {
          "id": "1002",
          "name": null
        },
        {
          "id": "1003",
          "name": "Leia Organa"
        }
      ]
    }
  }
}

如果发生错误的字段声明为Non-Null非空，则null错误会冒泡到下一个可空字段，这种情况下，path也应该包含到发生错误的字段的完整路径，即便这个字段未出现在响应中。

譬如，如果上述的name字段在schema中声明为Non-Null非空，那么查询结果可能不同，但是错误还是一样。

{
  "errors": [
    {
      "message": "Name for character with ID 1002 could not be fetched.",
      "locations": [ { "line": 6, "column": 7 } ],
      "path": [ "hero", "heroFriends", 1, "name" ]
    }
  ],
  "data": {
    "hero": {
      "name": "R2-D2",
      "heroFriends": [
        {
          "id": "1000",
          "name": "Luke Skywalker"
        },
        null,
        {
          "id": "1003",
          "name": "Leia Organa"
        }
      ]
    }
  }
}

GraphQL服务器可以给error提供附加的条目，以用来展示更为用的或者机器可读的错误，当然，今后本规范也可能为error引入附加条目。