From 9d1c3de863a99fa684d632b9a63d806b84c459ca Mon Sep 17 00:00:00 2001
From: Martin Bonnin <martin@mbonnin.net>
Date: Sat, 5 Aug 2023 15:13:34 +0200
Subject: [PATCH 01/11] Add Appendix C - all built-in definitions

---
 spec/Appendix C -- Built-in Definitions.md | 360 +++++++++++++++++++++
 spec/GraphQL.md                            |   2 +
 spec/Section 3 -- Type System.md           |  11 +-
 spec/Section 4 -- Introspection.md         | 101 +-----
 4 files changed, 370 insertions(+), 104 deletions(-)
 create mode 100644 spec/Appendix C -- Built-in Definitions.md

diff --git a/spec/Appendix C -- Built-in Definitions.md b/spec/Appendix C -- Built-in Definitions.md
new file mode 100644
index 000000000..b50f6630e
--- /dev/null
+++ b/spec/Appendix C -- Built-in Definitions.md	
@@ -0,0 +1,360 @@
+# C. Appendix: Built-in Definitions
+
+## Scalars
+
+```graphql
+"""
+The `Int` scalar type represents non-fractional signed whole numeric values. Int can represent values between
+-(2^31) and 2^31 - 1.
+"""
+scalar Int
+
+"""
+The `Float` scalar type represents signed double-precision fractional values as specified by
+[IEEE 754](http://en.wikipedia.org/wiki/IEEE_floating_point).
+"""
+scalar Float
+
+"""
+The `String` scalar type represents textual data, represented as UTF-8 character sequences. The String type is
+most often used by GraphQL to represent free-form human-readable text.
+"""
+scalar String
+
+"""
+The `Boolean` scalar type represents `true` or `false`.
+"""
+scalar Boolean
+
+"""
+The `ID` scalar type represents a unique identifier, often used to refetch an object or as key for a cache.
+The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When
+expected as an input type, any string (such as `"4"`) or integer (such as `4`) input value will be accepted as
+an ID.
+"""
+scalar ID
+```
+
+## Directives
+
+```graphql
+"""
+Directs the executor to include this field or fragment only when the `if` argument is true
+"""
+directive @include(
+  """
+  Included when true.
+  """
+  if: Boolean!
+) on FIELD | FRAGMENT_SPREAD | INLINE_FRAGMENT
+
+"""
+Directs the executor to skip this field or fragment when the `if` argument is true.
+"""
+directive @skip(
+  """
+  Skipped when true.
+  """
+  if: Boolean!
+) on FIELD | FRAGMENT_SPREAD | INLINE_FRAGMENT
+
+"""
+Marks the field, argument, input field or enum value as deprecated
+"""
+directive @deprecated(
+  """
+  The reason for the deprecation
+  """
+  reason: String = "No longer supported"
+) on FIELD_DEFINITION | ARGUMENT_DEFINITION | ENUM_VALUE | INPUT_FIELD_DEFINITION
+
+"""
+Exposes a URL that specifies the behaviour of this scalar.
+"""
+directive @specifiedBy(
+  """
+  The URL that specifies the behaviour of this scalar.
+  """
+  url: String!
+) on SCALAR
+```
+
+## Introspection types
+
+```graphql
+"""
+A GraphQL Schema defines the capabilities of a GraphQL server. It exposes all available types and directives
+on the server, as well as the entry points for query, mutation, and subscription operations.
+"""
+type __Schema {
+  description: String
+
+  """
+  A list of all types supported by this server.
+  """
+  types: [__Type!]!
+
+  """
+  The type that query operations will be rooted at.
+  """
+  queryType: __Type!
+
+  """
+  If this server supports mutation, the type that mutation operations will be rooted at.
+  """
+  mutationType: __Type
+
+  """
+  If this server support subscription, the type that subscription operations will be rooted at.
+  """
+  subscriptionType: __Type
+
+  """
+  A list of all directives supported by this server.
+  """
+  directives: [__Directive!]!
+}
+
+"""
+The fundamental unit of any GraphQL Schema is the type. There are many kinds of types in GraphQL as
+represented by the `__TypeKind` enum.
+
+Depending on the kind of a type, certain fields describe information about that type.
+"""
+type __Type {
+  kind: __TypeKind!
+  name: String
+  description: 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
+  """
+  may be non-null for custom SCALAR, otherwise null.
+  """
+  specifiedByURL: String
+}
+
+"""
+An enum describing what kind of type a given `__Type` is.
+"""
+enum __TypeKind {
+  """
+  Indicates this type is a scalar.
+  """
+  SCALAR
+
+  """
+  Indicates this type is an object. `fields` and `interfaces` are valid fields.
+  """
+  OBJECT
+
+  """
+  Indicates this type is an interface. `fields`, `interfaces`, and `possibleTypes` are valid fields.
+  """
+  INTERFACE
+
+  """
+  Indicates this type is a union. `possibleTypes` is a valid field.
+  """
+  UNION
+
+  """
+  Indicates this type is an enum. `enumValues` is a valid field.
+  """
+  ENUM
+
+  """
+  Indicates this type is an input object. `inputFields` is a valid field.
+  """
+  INPUT_OBJECT
+
+  """
+  Indicates this type is a list. `ofType` is a valid field.
+  """
+  LIST
+
+  """
+  Indicates this type is a non-null. `ofType` is a valid field.
+  """
+  NON_NULL
+}
+
+"""
+Object and Interface types are described by a list of Fields, each of which has a name, potentially a list of
+arguments, and a return type.
+"""
+type __Field {
+  name: String!
+  description: String
+  args(includeDeprecated: Boolean = false): [__InputValue!]!
+  type: __Type!
+  isDeprecated: Boolean!
+  deprecationReason: String
+}
+
+"""
+Arguments provided to Fields or Directives and the input fields of an InputObject are represented as Input
+Values which describe their type and optionally a default value.
+"""
+type __InputValue {
+  name: String!
+  description: String
+  type: __Type!
+
+  """
+  A GraphQL-formatted string representing the default value for this input value.
+  """
+  defaultValue: String
+  isDeprecated: Boolean!
+  deprecationReason: String
+}
+
+"""
+One possible value for a given Enum. Enum values are unique values, not a placeholder for a string or numeric
+value. However an Enum value is returned in a JSON response as a string.
+"""
+type __EnumValue {
+  name: String!
+  description: String
+  isDeprecated: Boolean!
+  deprecationReason: String
+}
+
+"""
+A Directive provides a way to describe alternate runtime execution and type validation behavior in a GraphQL
+document.
+
+In some cases, you need to provide options to alter GraphQL's execution behavior in ways field arguments will
+not suffice, such as conditionally including or skipping a field. Directives provide this by describing
+additional information to the executor.
+"""
+type __Directive {
+  name: String!
+  description: String
+  isRepeatable: Boolean!
+  locations: [__DirectiveLocation!]!
+  args(includeDeprecated: Boolean = false): [__InputValue!]!
+}
+
+"""
+A Directive can be adjacent to many parts of the GraphQL language, a __DirectiveLocation describes one such
+possible adjacencies.
+"""
+enum __DirectiveLocation {
+  """
+  Location adjacent to a query operation.
+  """
+  QUERY
+
+  """
+  Location adjacent to a mutation operation.
+  """
+  MUTATION
+
+  """
+  Location adjacent to a subscription operation.
+  """
+  SUBSCRIPTION
+
+  """
+  Location adjacent to a field.
+  """
+  FIELD
+
+  """
+  Location adjacent to a fragment definition.
+  """
+  FRAGMENT_DEFINITION
+
+  """
+  Location adjacent to a fragment spread.
+  """
+  FRAGMENT_SPREAD
+
+  """
+  Location adjacent to an inline fragment.
+  """
+  INLINE_FRAGMENT
+
+  """
+  Location adjacent to a variable definition.
+  """
+  VARIABLE_DEFINITION
+
+  """
+  Location adjacent to a schema definition.
+  """
+  SCHEMA
+
+  """
+  Location adjacent to a scalar definition.
+  """
+  SCALAR
+
+  """
+  Location adjacent to an object type definition.
+  """
+  OBJECT
+
+  """
+  Location adjacent to a field definition.
+  """
+  FIELD_DEFINITION
+
+  """
+  Location adjacent to an argument definition.
+  """
+  ARGUMENT_DEFINITION
+
+  """
+  Location adjacent to an interface definition.
+  """
+  INTERFACE
+
+  """
+  Location adjacent to a union definition.
+  """
+  UNION
+
+  """
+  Location adjacent to an enum definition.
+  """
+  ENUM
+
+  """
+  Location adjacent to an enum value definition.
+  """
+  ENUM_VALUE
+
+  """
+  Location adjacent to an input object type definition.
+  """
+  INPUT_OBJECT
+
+  """
+  Location adjacent to an input object field definition.
+  """
+  INPUT_FIELD_DEFINITION
+}
+```
diff --git a/spec/GraphQL.md b/spec/GraphQL.md
index fad6bcdbe..362227aec 100644
--- a/spec/GraphQL.md
+++ b/spec/GraphQL.md
@@ -139,3 +139,5 @@ Note: This is an example of a non-normative note.
 # [Appendix: Notation Conventions](Appendix%20A%20--%20Notation%20Conventions.md)
 
 # [Appendix: Grammar Summary](Appendix%20B%20--%20Grammar%20Summary.md)
+
+# [Appendix: Builtin Definitions](Appendix%20C%20--%20Built-in%20Definitions.md)
diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md
index d32b08566..29b76d3b3 100644
--- a/spec/Section 3 -- Type System.md	
+++ b/spec/Section 3 -- Type System.md	
@@ -388,9 +388,9 @@ Scalar types represent primitive leaf values in a GraphQL type system. GraphQL
 responses take the form of a hierarchical tree; the leaves of this tree are
 typically GraphQL Scalar types (but may also be Enum types or {null} values).
 
-GraphQL provides a number of built-in scalars which are fully defined in the
-sections below, however type systems may also add additional custom scalars to
-introduce additional semantic meaning.
+GraphQL provides a number of [built-in scalars](#sec-Appendix-Built-in-Definitions.Scalars)
+which are fully defined in the sections below, however type systems may also add
+additional custom scalars to introduce additional semantic meaning.
 
 **Built-in Scalars**
 
@@ -1950,10 +1950,11 @@ GraphQL implementations that support the type system definition language should
 provide the `@specifiedBy` directive if representing custom scalar definitions.
 
 When representing a GraphQL schema using the type system definition language any
-_built-in directive_ may be omitted for brevity.
+[built-in directive](#sec-Appendix-Built-in-Definitions.Directives) may be omitted for brevity.
 
 When introspecting a GraphQL service all provided directives, including any
-_built-in directive_, must be included in the set of returned directives.
+[built-in directive](#sec-Appendix-Built-in-Definitions.Directives), must be included in the set of
+returned directives.
 
 **Custom Directives**
 
diff --git a/spec/Section 4 -- Introspection.md b/spec/Section 4 -- Introspection.md
index 3054a9f6c..b99e5be59 100644
--- a/spec/Section 4 -- Introspection.md	
+++ b/spec/Section 4 -- Introspection.md	
@@ -119,106 +119,9 @@ warnings.
 
 **Schema Introspection Schema**
 
-The schema introspection system is itself represented as a GraphQL schema. Below
-are the full set of type system definitions providing schema introspection,
-which are fully defined in the sections below.
+The schema introspection system is itself represented as a GraphQL schema.
 
-```graphql
-type __Schema {
-  description: String
-  types: [__Type!]!
-  queryType: __Type!
-  mutationType: __Type
-  subscriptionType: __Type
-  directives: [__Directive!]!
-}
-
-type __Type {
-  kind: __TypeKind!
-  name: String
-  description: 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
-  # may be non-null for custom SCALAR, otherwise null.
-  specifiedByURL: String
-}
-
-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
-  locations: [__DirectiveLocation!]!
-  args(includeDeprecated: Boolean = false): [__InputValue!]!
-  isRepeatable: Boolean!
-}
-
-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
-}
-```
+See [Appendix C](#sec-Introspection-types) for more details about the schema type definitions.
 
 ### The \_\_Schema Type
 

From 6b14c8918ef215939a04ca5f5e7ee9e107c59126 Mon Sep 17 00:00:00 2001
From: Martin Bonnin <martin@mbonnin.net>
Date: Sat, 5 Aug 2023 15:24:24 +0200
Subject: [PATCH 02/11] =?UTF-8?q?formatting=20and=20spelling.=20Spec=20is?=
 =?UTF-8?q?=20American,=20not=20British=20=F0=9F=98=84?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 spec/Appendix C -- Built-in Definitions.md |  4 ++--
 spec/Section 3 -- Type System.md           | 14 ++++++++------
 spec/Section 4 -- Introspection.md         |  3 ++-
 3 files changed, 12 insertions(+), 9 deletions(-)

diff --git a/spec/Appendix C -- Built-in Definitions.md b/spec/Appendix C -- Built-in Definitions.md
index b50f6630e..f69dd368a 100644
--- a/spec/Appendix C -- Built-in Definitions.md	
+++ b/spec/Appendix C -- Built-in Definitions.md	
@@ -69,11 +69,11 @@ directive @deprecated(
 ) on FIELD_DEFINITION | ARGUMENT_DEFINITION | ENUM_VALUE | INPUT_FIELD_DEFINITION
 
 """
-Exposes a URL that specifies the behaviour of this scalar.
+Exposes a URL that specifies the behavior of this scalar.
 """
 directive @specifiedBy(
   """
-  The URL that specifies the behaviour of this scalar.
+  The URL that specifies the behavior of this scalar.
   """
   url: String!
 ) on SCALAR
diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md
index 29b76d3b3..3e98b5caa 100644
--- a/spec/Section 3 -- Type System.md	
+++ b/spec/Section 3 -- Type System.md	
@@ -388,9 +388,10 @@ Scalar types represent primitive leaf values in a GraphQL type system. GraphQL
 responses take the form of a hierarchical tree; the leaves of this tree are
 typically GraphQL Scalar types (but may also be Enum types or {null} values).
 
-GraphQL provides a number of [built-in scalars](#sec-Appendix-Built-in-Definitions.Scalars)
-which are fully defined in the sections below, however type systems may also add
-additional custom scalars to introduce additional semantic meaning.
+GraphQL provides a number of
+[built-in scalars](#sec-Appendix-Built-in-Definitions.Scalars) which are fully
+defined in the sections below, however type systems may also add additional
+custom scalars to introduce additional semantic meaning.
 
 **Built-in Scalars**
 
@@ -1950,11 +1951,12 @@ GraphQL implementations that support the type system definition language should
 provide the `@specifiedBy` directive if representing custom scalar definitions.
 
 When representing a GraphQL schema using the type system definition language any
-[built-in directive](#sec-Appendix-Built-in-Definitions.Directives) may be omitted for brevity.
+[built-in directive](#sec-Appendix-Built-in-Definitions.Directives) may be
+omitted for brevity.
 
 When introspecting a GraphQL service all provided directives, including any
-[built-in directive](#sec-Appendix-Built-in-Definitions.Directives), must be included in the set of
-returned directives.
+[built-in directive](#sec-Appendix-Built-in-Definitions.Directives), must be
+included in the set of returned directives.
 
 **Custom Directives**
 
diff --git a/spec/Section 4 -- Introspection.md b/spec/Section 4 -- Introspection.md
index b99e5be59..885139740 100644
--- a/spec/Section 4 -- Introspection.md	
+++ b/spec/Section 4 -- Introspection.md	
@@ -121,7 +121,8 @@ warnings.
 
 The schema introspection system is itself represented as a GraphQL schema.
 
-See [Appendix C](#sec-Introspection-types) for more details about the schema type definitions.
+See [Appendix C](#sec-Introspection-types) for more details about the schema
+type definitions.
 
 ### The \_\_Schema Type
 

From 014bff833d70b27b1b36c70dbc7a9fbc53bb5c67 Mon Sep 17 00:00:00 2001
From: Martin Bonnin <martin@mbonnin.net>
Date: Fri, 8 Sep 2023 15:23:41 +0200
Subject: [PATCH 03/11] keep current spec unchanged. Appendix C is purely
 additive

---
 spec/Section 3 -- Type System.md   |  13 ++--
 spec/Section 4 -- Introspection.md | 102 ++++++++++++++++++++++++++++-
 2 files changed, 104 insertions(+), 11 deletions(-)

diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md
index 3e98b5caa..d32b08566 100644
--- a/spec/Section 3 -- Type System.md	
+++ b/spec/Section 3 -- Type System.md	
@@ -388,10 +388,9 @@ Scalar types represent primitive leaf values in a GraphQL type system. GraphQL
 responses take the form of a hierarchical tree; the leaves of this tree are
 typically GraphQL Scalar types (but may also be Enum types or {null} values).
 
-GraphQL provides a number of
-[built-in scalars](#sec-Appendix-Built-in-Definitions.Scalars) which are fully
-defined in the sections below, however type systems may also add additional
-custom scalars to introduce additional semantic meaning.
+GraphQL provides a number of built-in scalars which are fully defined in the
+sections below, however type systems may also add additional custom scalars to
+introduce additional semantic meaning.
 
 **Built-in Scalars**
 
@@ -1951,12 +1950,10 @@ GraphQL implementations that support the type system definition language should
 provide the `@specifiedBy` directive if representing custom scalar definitions.
 
 When representing a GraphQL schema using the type system definition language any
-[built-in directive](#sec-Appendix-Built-in-Definitions.Directives) may be
-omitted for brevity.
+_built-in directive_ may be omitted for brevity.
 
 When introspecting a GraphQL service all provided directives, including any
-[built-in directive](#sec-Appendix-Built-in-Definitions.Directives), must be
-included in the set of returned directives.
+_built-in directive_, must be included in the set of returned directives.
 
 **Custom Directives**
 
diff --git a/spec/Section 4 -- Introspection.md b/spec/Section 4 -- Introspection.md
index 885139740..3054a9f6c 100644
--- a/spec/Section 4 -- Introspection.md	
+++ b/spec/Section 4 -- Introspection.md	
@@ -119,10 +119,106 @@ warnings.
 
 **Schema Introspection Schema**
 
-The schema introspection system is itself represented as a GraphQL schema.
+The schema introspection system is itself represented as a GraphQL schema. Below
+are the full set of type system definitions providing schema introspection,
+which are fully defined in the sections below.
 
-See [Appendix C](#sec-Introspection-types) for more details about the schema
-type definitions.
+```graphql
+type __Schema {
+  description: String
+  types: [__Type!]!
+  queryType: __Type!
+  mutationType: __Type
+  subscriptionType: __Type
+  directives: [__Directive!]!
+}
+
+type __Type {
+  kind: __TypeKind!
+  name: String
+  description: 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
+  # may be non-null for custom SCALAR, otherwise null.
+  specifiedByURL: String
+}
+
+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
+  locations: [__DirectiveLocation!]!
+  args(includeDeprecated: Boolean = false): [__InputValue!]!
+  isRepeatable: Boolean!
+}
+
+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
+}
+```
 
 ### The \_\_Schema Type
 

From fd020de8c470b164c43f19cb1a01d304fd2d1f70 Mon Sep 17 00:00:00 2001
From: Martin Bonnin <martin@mbonnin.net>
Date: Thu, 27 Mar 2025 12:23:32 +0100
Subject: [PATCH 04/11] add a note about descriptions

---
 spec/Appendix C -- Built-in Definitions.md | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/spec/Appendix C -- Built-in Definitions.md b/spec/Appendix C -- Built-in Definitions.md
index f69dd368a..15399e3fe 100644
--- a/spec/Appendix C -- Built-in Definitions.md	
+++ b/spec/Appendix C -- Built-in Definitions.md	
@@ -1,4 +1,10 @@
-# C. Appendix: Built-in Definitions
+# C. Appendix: Type System Definitions
+
+This appendix lists all the type system definitions mentioned throughout this
+specification.
+
+The descriptions are non-normative. Implementations are recommended to use them
+for consistency but different descriptions are allowed.
 
 ## Scalars
 

From 23d0b656cb80b51bbd5590b4004ef853d551ff01 Mon Sep 17 00:00:00 2001
From: Martin Bonnin <martin@mbonnin.net>
Date: Thu, 3 Apr 2025 13:44:04 +0200
Subject: [PATCH 05/11] Update spec/Appendix C -- Built-in Definitions.md

Co-authored-by: Benoit 'BoD' Lubek <BoD@JRAF.org>
---
 spec/Appendix C -- Built-in Definitions.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/spec/Appendix C -- Built-in Definitions.md b/spec/Appendix C -- Built-in Definitions.md
index 15399e3fe..e27b4ccc4 100644
--- a/spec/Appendix C -- Built-in Definitions.md	
+++ b/spec/Appendix C -- Built-in Definitions.md	
@@ -45,7 +45,7 @@ scalar ID
 
 ```graphql
 """
-Directs the executor to include this field or fragment only when the `if` argument is true
+Directs the executor to include this field or fragment only when the `if` argument is true.
 """
 directive @include(
   """

From 2ec1dbe5e22dee63bd627b0e852cced99cfb1414 Mon Sep 17 00:00:00 2001
From: Martin Bonnin <martin@mbonnin.net>
Date: Thu, 3 Apr 2025 13:44:10 +0200
Subject: [PATCH 06/11] Update spec/Appendix C -- Built-in Definitions.md

Co-authored-by: Benoit 'BoD' Lubek <BoD@JRAF.org>
---
 spec/Appendix C -- Built-in Definitions.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/spec/Appendix C -- Built-in Definitions.md b/spec/Appendix C -- Built-in Definitions.md
index e27b4ccc4..42e4e5868 100644
--- a/spec/Appendix C -- Built-in Definitions.md	
+++ b/spec/Appendix C -- Built-in Definitions.md	
@@ -65,7 +65,7 @@ directive @skip(
 ) on FIELD | FRAGMENT_SPREAD | INLINE_FRAGMENT
 
 """
-Marks the field, argument, input field or enum value as deprecated
+Marks the field, argument, input field or enum value as deprecated.
 """
 directive @deprecated(
   """

From a2bbab1912e1eda964da382103baf9c6d969c127 Mon Sep 17 00:00:00 2001
From: Martin Bonnin <martin@mbonnin.net>
Date: Thu, 3 Apr 2025 13:44:16 +0200
Subject: [PATCH 07/11] Update spec/Appendix C -- Built-in Definitions.md

Co-authored-by: Benoit 'BoD' Lubek <BoD@JRAF.org>
---
 spec/Appendix C -- Built-in Definitions.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/spec/Appendix C -- Built-in Definitions.md b/spec/Appendix C -- Built-in Definitions.md
index 42e4e5868..fc6a6dc22 100644
--- a/spec/Appendix C -- Built-in Definitions.md	
+++ b/spec/Appendix C -- Built-in Definitions.md	
@@ -69,7 +69,7 @@ Marks the field, argument, input field or enum value as deprecated.
 """
 directive @deprecated(
   """
-  The reason for the deprecation
+  The reason for the deprecation.
   """
   reason: String = "No longer supported"
 ) on FIELD_DEFINITION | ARGUMENT_DEFINITION | ENUM_VALUE | INPUT_FIELD_DEFINITION

From 8f5caad991f6ed540a834476de315aa72086268b Mon Sep 17 00:00:00 2001
From: Martin Bonnin <martin@mbonnin.net>
Date: Thu, 3 Apr 2025 13:44:23 +0200
Subject: [PATCH 08/11] Update spec/Appendix C -- Built-in Definitions.md

Co-authored-by: Benoit 'BoD' Lubek <BoD@JRAF.org>
---
 spec/Appendix C -- Built-in Definitions.md | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/spec/Appendix C -- Built-in Definitions.md b/spec/Appendix C -- Built-in Definitions.md
index fc6a6dc22..f1694c6fa 100644
--- a/spec/Appendix C -- Built-in Definitions.md	
+++ b/spec/Appendix C -- Built-in Definitions.md	
@@ -132,31 +132,31 @@ type __Type {
   name: String
   description: String
   """
-  must be non-null for OBJECT and INTERFACE, otherwise null.
+  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.
+  Must be non-null for OBJECT and INTERFACE, otherwise null.
   """
   interfaces: [__Type!]
   """
-  must be non-null for INTERFACE and UNION, otherwise null.
+  Must be non-null for INTERFACE and UNION, otherwise null.
   """
   possibleTypes: [__Type!]
   """
-  must be non-null for ENUM, otherwise null.
+  Must be non-null for ENUM, otherwise null.
   """
   enumValues(includeDeprecated: Boolean = false): [__EnumValue!]
   """
-  must be non-null for INPUT_OBJECT, otherwise null.
+  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.
+  Must be non-null for NON_NULL and LIST, otherwise null.
   """
   ofType: __Type
   """
-  may be non-null for custom SCALAR, otherwise null.
+  May be non-null for custom SCALAR, otherwise null.
   """
   specifiedByURL: String
 }

From 89c367af0687fa7da5475c25e7760ba0f4f19741 Mon Sep 17 00:00:00 2001
From: Martin Bonnin <martin@mbonnin.net>
Date: Thu, 3 Apr 2025 13:44:38 +0200
Subject: [PATCH 09/11] Update spec/Appendix C -- Built-in Definitions.md

Co-authored-by: Benjie <benjie@jemjie.com>
---
 spec/Appendix C -- Built-in Definitions.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/spec/Appendix C -- Built-in Definitions.md b/spec/Appendix C -- Built-in Definitions.md
index f1694c6fa..20a8ca48e 100644
--- a/spec/Appendix C -- Built-in Definitions.md	
+++ b/spec/Appendix C -- Built-in Definitions.md	
@@ -258,9 +258,9 @@ additional information to the executor.
 type __Directive {
   name: String!
   description: String
-  isRepeatable: Boolean!
   locations: [__DirectiveLocation!]!
   args(includeDeprecated: Boolean = false): [__InputValue!]!
+  isRepeatable: Boolean!
 }
 
 """

From efb8eb48f0e723330840bb095415a2d2ed26f6bd Mon Sep 17 00:00:00 2001
From: Martin Bonnin <martin@mbonnin.net>
Date: Thu, 3 Apr 2025 13:44:52 +0200
Subject: [PATCH 10/11] Update spec/Appendix C -- Built-in Definitions.md

Co-authored-by: Benjie <benjie@jemjie.com>
---
 spec/Appendix C -- Built-in Definitions.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/spec/Appendix C -- Built-in Definitions.md b/spec/Appendix C -- Built-in Definitions.md
index 20a8ca48e..583be97f0 100644
--- a/spec/Appendix C -- Built-in Definitions.md	
+++ b/spec/Appendix C -- Built-in Definitions.md	
@@ -71,7 +71,7 @@ directive @deprecated(
   """
   The reason for the deprecation.
   """
-  reason: String = "No longer supported"
+  reason: String! = "No longer supported"
 ) on FIELD_DEFINITION | ARGUMENT_DEFINITION | ENUM_VALUE | INPUT_FIELD_DEFINITION
 
 """

From c0648103ddcf0db4a5bacb67adbb244542d49572 Mon Sep 17 00:00:00 2001
From: Martin Bonnin <martin@mbonnin.net>
Date: Thu, 3 Apr 2025 13:45:16 +0200
Subject: [PATCH 11/11] Update spec/Appendix C -- Built-in Definitions.md

Co-authored-by: Benjie <benjie@jemjie.com>
---
 spec/Appendix C -- Built-in Definitions.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/spec/Appendix C -- Built-in Definitions.md b/spec/Appendix C -- Built-in Definitions.md
index 583be97f0..a3b1ea601 100644
--- a/spec/Appendix C -- Built-in Definitions.md	
+++ b/spec/Appendix C -- Built-in Definitions.md	
@@ -72,7 +72,7 @@ directive @deprecated(
   The reason for the deprecation.
   """
   reason: String! = "No longer supported"
-) on FIELD_DEFINITION | ARGUMENT_DEFINITION | ENUM_VALUE | INPUT_FIELD_DEFINITION
+) on FIELD_DEFINITION | ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION | ENUM_VALUE
 
 """
 Exposes a URL that specifies the behavior of this scalar.