Add Appendix C - all built-in definitions

Author: martinbonnin

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
+}
+```

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)

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**