link v1.0

for linking schemas together

StatusDraft
Version1.0

@link other schemas by their URL and import: definitions from them.

2Import

scalar Import

An element, possibly aliased, to import into the document.

Import can take the form of a string:

Example โ„– 3 import a string name
  @link(url: "https://specs.apollo.dev/link/v1.0", import: ["@link", "Purpose"])

or an object with name and (optionally as):

Example โ„– 4 import an aliased name
  @link(url: "https://example.com/", import: [{
    name: "@example",
    as: "@eg"
  }, { name: "Purpose", as: "LinkPurpose" }])

name and as MUST be of the same type:

Counter Example โ„– 5 incorrectly importing a type as a directive
  @link(url: "https://example.com/", import: [{
    name: "SomeType",
    as: "@someDirective"
  }])

Imports cannot currently reference transitive schemas:

Counter Example โ„– 6 incorrectly importing a transitive schema reference
  @link(url: "https://example.com/", import: ["otherSchema::"])
Note Future versions may support this.

3Purpose

The role of a @linked schema.

This is not intended to be an exhaustive list of all the purposes a foreign schema or its metadata might serve. Rather, it is intended to capture cases where the default fail‐open behavior of core schema consumers is undesirable.

Note we’ll refer to directives from links which are for: SECURITY or for: EXECUTION as “SECURITY directives” and “EXECUTION directives”, respectively.

3.1SECURITY

SECURITY links provide metadata necessary to securely resolve fields. For instance, a hypothetical auth schema may provide an @auth directive to flag fields which require authorization. If a data core does not support the auth schemas and serves those fields anyway, these fields will be accessible without authorization, compromising security.

Security‐conscious consumers MUST NOT serve a field if:

  • the schema definition has any unsupported SECURITY directives,
  • the field’s parent type definition has any unsupported SECURITY directives,
  • the field’s return type definition has any unsupported SECURITY directives, or
  • the field definition has any unsupported SECURITY directives

Such fields are not securely resolvable. Security‐conscious consumers MAY serve schemas with fields which are not securely resolvable. However, they MUST remove such fields from the schema before serving it.

Less security‐conscious consumers MAY choose to relax these requirements. For instance, servers may provide a development mode in which unknown SECURITY directives are ignored, perhaps with a warning. Such software may also provide a way to explicitly disable some or all SECURITY links during development.

More security‐conscious consumers MAY choose to enhance these requirements. For instance, production servers MAY adopt a policy of entirely rejecting any schema which contains ANY unsupported SECURITY links, even if those links are never used to annotate the schema.

3.2EXECUTION

EXECUTION schemas provide metadata necessary to correctly resolve fields. For instance, a hypothetical ts schemas may provide a @ts__resolvers annotation which references a TypeScript module of field resolvers. A consumer which does not support the ts schemas will be unable to correctly resolve such fields.

Consumers MUST NOT serve a field if:

  • the schema’s definition has any unsupported EXECUTION directives,
  • the field’s parent type definition has any unsupported EXECUTION directives,
  • the field’s return type definition has any unsupported EXECUTION directives, or
  • the field definition has any unsupported EXECUTION directives

Such fields are unresolvable. Consumers MAY attempt to serve schemas with unresolvable fields. Depending on the needs of the consumer, unresolvable fields MAY be removed from the schema prior to serving, or they MAY produce runtime errors if a query attempts to resolve them. Consumers MAY implement stricter policies, wholly refusing to serve schemas with unresolvable fields, or even refusing to serve schemas with any unsupported EXECUTION schemas, even if those schemas are never used in the schema.

ยงIndex

  1. @link
  2. @link.as
  3. @link.for
  4. @link.import
  5. @link.url
  6. Import
  7. Purpose
  8. Purpose.EXECUTION
  9. Purpose.SECURITY
  1. 1@link
    1. 1.1url: String!
    2. 1.2as: String
    3. 1.3import: [Import]
    4. 1.4for: Purpose
  2. 2Import
  3. 3Purpose
    1. 3.1SECURITY
    2. 3.2EXECUTION
  4. ยงIndex