1Parts of a Core Schema

When talking about a core schema, we can broadly break it into two pieces:

• an API consisting of schema elements (objects, interfaces, enums, directives, etc.) which SHOULD be served to clients, and
• machinery containing document metadata. This typically consists of directives and associated input types (such as enums and input objects), but may include any schema element. Machinery MUST NOT be served to clients. Specifically, machinery MUST NOT be included in introspection responses or used to validate or execute queries.

This reflects how core schemas are used: a core schema contains a GraphQL interface (the API) along with metadata about how to implement that interface (the machinery). Exposing the machinery to clients is unnecessary, and may in some cases constitute a security issue (for example, the machinery for a public‐facing graph router will likely reference internal services, possibly exposing network internals which should not be visible to the general public).

A key feature of core schemas is that it is always possible to derive a core schema’s API without any knowledge of the features used by the document (with the exception of the core feature itself). Specifically, named elements are not included in the API schema if they are named something__likeThis or are a directive named @something, and something is the prefix of a feature declared with @core.

A formal description is provided by the IsInAPI algorithm.

2Actors

• Authors (either human or machine) write an initial core schema as specified in this document, including versioned @core requests for all directives they use
• Machine processors can process core schemas and output new core schemas. The versioning of directives and associated schema elements provided by the @core allows processors to operate on directives they understand and pass through directives they do not.
• Human readers can examine the core schema at various stages of processing. At any stage, they can examine the @core directives and follow URLs to the specification, receiving an explanation of the requirements of the specification and what new directives, types, and other schema objects are available within the document.
• Data cores can then pick up the processed core schema and provide some data‐layer service with it. Typically this means serving the schema’s API as a GraphQL endpoint, using metadata defined by machinery to inform how it processes operations it receives. However, data cores may perform other tasks described in the core schema, such as routing to backend services, caching commonly‐accessed fields and queries, and so on. The term “data core” is intended to capture this multiplicity of possible activities.

3Basic Requirements

Core schemas:

1. MUST be valid GraphQL schema documents,
2. MUST contain exactly one SchemaDefinition, and
3. MUST use the @core directive on their schema definition to declare any features they reference by using @core to reference a well‐formed feature URL.

The first @core directive on the schema MUST reference the core spec itself, i.e. this document.

schema
  @core(feature: "https://specs.apollo.dev/core/v0.1")
  @core(feature: "https://specs.example.com/example/v1.0")
{
  query: Query
}

type Query {
  field: Int @example
}

directive @example on FIELD_DEFINITION

directive @core(feature: String!, as: String) repeatable on SCHEMA

schema
  @core(feature: "https://specs.apollo.dev/core/v0.1")
{
  query: Query
}

type SomeType {
  field: Int @another
}

# `@another` is unspecified. Core processors will not extract metadata from
# it, but its definition and all usages within the schema will be exposed
# in the API.
directive @another on FIELD_DEFINITION

directive @core(feature: String!, as: String) repeatable on SCHEMA

schema
  @coreSchema(feature: "https://specs.apollo.dev/core/v0.1", as: "coreSchema")
  @coreSchema(feature: "https://example.com/example/v1.0")
{
  query: Query
}

type SomeType {
  field: Int @example
}

directive @coreSchema(feature: String!, as: String)
  repeatable on SCHEMA
directive @example on FIELD_DEFINITION

4Directive Definitions

All core schemas use the @core directive to declare their use of the core feature itself as well as any other core features they use.

In order to use these directives in your schema, GraphQL requires you to include their definitions in your schema.

Processors MUST validate that you have defined the directives with the same arguments, locations, and repeatable flag as given below. Specifically, the bootstrapping algorithm validates that the @core directive has a definition matching the definition given below. (The bootstrapping algorithm does not require processors to validate other aspects of the directive declaration such as description strings or argument ordering. The main purpose of this validation is to ensure that directive arguments have the type and default values expected by the specification.)

The following declares the directive defined by this specification. You SHOULD define the directives in your core schema by including the following text in your schema document.

directive @core(feature: String!, as: String) repeatable on SCHEMA

When writing a specification for your own core feature, you SHOULD include a section like this one with sample definitions to copy into schemas, and you SHOULD require processors to validate that directive definitions in documents match your sample definitions.

5Directives

directive @core(
  feature: String!,
  as: String)
  repeatable on SCHEMA

schema
  @core(feature: "https://specs.apollo.dev/core/v0.1")
  @core(feature: "https://spec.example.com/example/v1.0", as: "eg")
{
  query: Query
}

type User {
  # Specifying `as: "eg"` transforms @example into @eg
  name: String @eg(data: ITEM)
}

# Additional specified schema elements must have their prefixes set
# to the new name.
#
# The spec at https://spec.example.com/example/v1.0 calls this enum
# `example__Data`, but because of the `as:` argument above, processors
# will use this `eg__Data` enum instead.
enum eg__Data {
  ITEM
}

# Name transformation must also be applied to definitions pulled in from
# specifications.
directive @eg(data: eg__Data) on FIELD_DEFINITION

directive @core(feature: String!, as: String) repeatable on SCHEMA

6Prefixing

With the exception of a single root directive, core feature specifications MUST prefix all schema elements they introduce. The prefix:

1. MUST match the name of the feature as derived from the feature’s specification URL,
2. MUST be a valid GraphQL name, and
3. MUST NOT contain the core namespace separator, which is two underscores ("__"), and
4. MUST NOT end with an underscore (which would create ambiguity between whether "x___y" is prefix x_ for element y or prefix x for element _y).

Prefixed names consist of the name of the feature, followed by two underscores, followed by the name of the element, which can be any valid GraphQL name. For instance, the core specification (which you are currently reading) introduces an element named @core, and the join specification introduces an element named @join__field (among others).

A feature’s root directive is an exception to the prefixing requirements. Feature specifications MAY introduce a single directive which carries only the name of the feature, with no prefix required. For example, the core specification introduces a @core directive. This directive has the same name as the feature (”core”), and so requires no prefix.

schema
 @core(feature: "https://specs.apollo.dev/core/v0.1")
 @core(feature: "https://spec.example.com/example/v1.0") {
  query: Query
}

type User {
  name: String @example(data: ITEM)
}

# An enum used to provide structured data to the example spec.
# It is prefixed with the name of the spec.
enum example__Data {
  ITEM
}

directive @example(data: example__Data) on FIELD_DEFINITION

directive @core(feature: String!, as: String) repeatable on SCHEMA

The prefix MUST NOT be elided within documentation; definitions of schema elements provided within the spec MUST include the feature’s name as a prefix.

schema
  @core(feature: "https://specs.apollo.dev/core/v0.1")
  @core(feature: "https://spec.example.com/featureA/v1.0")
  @core(feature: "https://spec.example.com/featureB/v2.0", as: "B") {
  query: Query
}

"""
featureA__SomeType is a type defined by feature A.
"""
type featureA__SomeType {
  """
  nativeField is a field defined by featureA on a type also defined
  by featureA (namely featureA__SomeType)
  """
  nativeField: Int @featureA__fieldDirective
}

"""
featureA__SomeInput is an input specified by feature A
"""
input featureA__SomeInput {
  """
  nativeInputField is defined by featureA
  """
  nativeInputField: Int
}

"""
featureA__Items is specified by feature A
"""
enum featureA__Items { ONE, TWO, THREE @B }

"""
@B is the root directive defined by featureB

Root directives are named after their feature
"""
directive @B on ENUM_VALUE

"""
@featureA__fieldDirective is a non-root (prefixed) directive defined by featureA
"""
directive @featureA__fieldDirective on FIELD_DEFINITION

directive @core(feature: String!, as: String) repeatable on SCHEMA

7Versioning

Specs are versioned with a subset of a Semantic Version Number containing only the major and minor parts. Thus, specifications SHOULD provide a version of the form vMajor.Minor, where both integers ≥ 0.

v2.2
v1.0
v1.1
v0.1

As specified by semver, spec authors SHOULD increment the:

Patch and pre‐release qualifiers are judged to be not particularly meaningful in the context of core features, which are (by definition) interfaces rather than implementations. The patch component of a semver denotes a bug fix which is backwards compatible—that is, a change to the implementation which does not affect the interface. Patch‐level changes in the version of a spec denote wording clarifications which do not require implementation changes. As such, it is not important to track them for the purposes of version resolution.

As with semver, the 0.x version series is special: there is no expectation of compatibility between versions 0.x and 0.y. For example, a processor must not activate implementation 0.4 to satisfy a requested version of 0.2.

8Processing Schemas

A common use case is that of a processor which consumes a valid input schema and generates an output schema.

The general guidance for processor behavior is: don’t react to what you don’t understand.

Specifically, processors:

• SHOULD pass through @core directives which reference unknown feature URLs
• SHOULD pass through prefixed directives, types, and other schema elements
• SHOULD pass through directives which are not associated with a @core feature

Processors MAY accept configuration which overrides these default behaviors.

Additionally, processors which prepare the schema for final public consumption MAY choose to eliminate all unknown directives and prefixed types in order to hide schema implementation details within the published schema. This will impair the operation of tooling which relies on these directives—such tools will not be able to run on the output schema, so the benefits and costs of this kind of information hiding should be weighed carefully on a case‐by‐case basis.

9Validations & Algorithms

This section lays out algorithms for processing core schemas.

Algorithms described in this section may produce validation failures if a document does not conform to the requirements core schema document. Validation failures SHOULD halt processing. Some consumers, such as authoring tools, MAY attempt to continue processing in the presence of validation failures, but their behavior in such cases is unspecified.

schema
  @core(feature: "https://specs.apollo.dev/core/v0.1")
  @core(feature: "https://spec.example.com/featureA/v1.0")
  @core(feature: "https://spec.example.com/featureB/v2.0", as: "B") {
  query: Query
}

schema
  @core(feature: "https://specs.apollo.dev/core/v0.1")
  @core(feature: "https://specs.example.com/A/1.0")               # name is A
  @core(feature: "https://specs.example.com/A/2.0", as: "A2")     # name is A2
{
  query: Query
}

schema
  @core(feature: "https://specs.apollo.dev/core/v0.1")
  @core(feature: "https://specs.example.com/A/1.0") # name is A
  @core(feature: "https://specs.example.com/A/2.0") # name is A
{
  query: Query
}

schema
  @core(feature: "https://specs.apollo.dev/core/v0.1")
  @core(feature: "https://specs.example.com/A/1.0")              # name is A
  @core(feature: "https://www.specs.com/specA/1.1", as: "A")     # name is A
{
  query: Query
}