inaccessible v0.1

for removing elements from a core schema

Status	Release
Version	0.1

This document defines the @inaccessible directive, which marks schema elements which should not be accessible in the public‐facing schema. This version of the spec supports Object, Interface, and Union types.

1How to read this document

This document uses RFC 2119 guidance regarding normative terms: MUST / MUST NOT / REQUIRED / SHALL / SHALL NOT / SHOULD / SHOULD NOT / RECOMMENDED / MAY / OPTIONAL.

2Definitions

2.1Processor

This specification makes references to Processors. Processors are described in the Actors section of the @core spec as an actor which can perform transformations on a core schema. In the case of @inaccessible, the Processor will be expected to remove various parts of a core schema.

3Example: Sensitive User Data

This section is non‐normative.

We’ll refer to this example of a core schema with sensitive user data throughout the document:

Example № 1 Core schema example

directive @core(as: String, feature: String!, for: core__Purpose) repeatable on SCHEMA
directive @inaccessible on FIELD_DEFINITION | OBJECT | INTERFACE | UNION

enum core__Purpose {
  EXECUTION
  SECURITY
}

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

type Query {
  user(id: String!): User
}

type User {
  id: String! @inaccessible
  name: String!
  email: String!
  bankAccount: BankAccount @inaccessible
  accounts: [Account]
}

type BankAccount @inaccessible {
  id: String!
  accountNumber: String!
}

type ForumAccount {
  handle: String!
}

union Account = BankAccount | ForumAccount

The schema above contains both a field (User.id) and type (BankAccount) that are marked as @inaccessible. These symbols should be omitted from the processed schema anywhere they would appear. When the processed schema below is generated from this core schema, notice what has been removed:

User.id field
BankAccount type
User.bankAccount field
Account union’s BankAccount type

Example № 2 Core schema after processing

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

enum core__Purpose {
  EXECUTION
  SECURITY
}

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

type Query {
  user(id: String!): User
}

type User {
  name: String!
  email: String!
  accounts: [Account]
}

type ForumAccount {
  handle: String!
}

union Account = ForumAccount

4Overview

This section is non‐normative. It describes the motivation behind the directives defined by this specification.

A core schema which has been processed according to the inaccessible spec is a queryable graph, intended to be served by a Data Core. Various use cases require that fields and types should not be visible to or queried for by clients. The @inaccessible directive fulfills this requirement, providing schema authors a mechanism to specify which fields and types should be omitted from the processed schema.

5Basic Requirements

Schemas using @inaccessible must be valid core schema documents and must reference this specification.

Here is an example @core usage:

Example № 3 required @core directives

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

As described in the core schema specification, your schema may rename the @inaccessible directive by including an as argument to the @core directive which references this specification. All references to @inaccessible in this specification MUST be interpreted as referring to names with the appropriate prefix chosen within your schema.

5.1@inaccessible

In order to use the directive described by this specification, GraphQL requires you to include the definition in your schema.

directive @inaccessible on FIELD_DEFINITION | OBJECT | INTERFACE | UNION

5.2Producer Responsibilities

Producers MUST include a definition of the directive compatible with the above definition and all usages in the document.

5.3Processor Responsibilities

The Processor is responsible for excluding all inaccessible elements from the API. Within the API,

Field Definitions marked with @inaccessible MUST be excluded
Object types marked with @inaccessible MUST be excluded
Object types marked with @inaccessible MUST be excluded from membership in any unions
Interfaces marked with @inaccessible MUST be excluded
Interfaces marked with @inaccessible MUST be excluded from the extends clause of all other interfaces
Union types marked with @inaccessible MUST be excluded

Note applying this process may result in an invalid schema. For example, fields which return @inaccessible types which are not themselves marked @inaccessible will now return an invalid type which is not present in the schema. This is intentional. @inaccessible does NOT cascade. If applying @inaccessible results in an invalid schema, the serving process SHOULD apply standard polices to determine whether or how to serve it. Generally, invalid schemas SHOULD NOT be served, though some server configurations—particularly those used for development—MAY OPTIONALLY elect to serve such schemas in a degraded mode. The semantics of such a mode are not within the scope of this spec.

§Index

@inaccessible