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:
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
fieldBankAccount
typeUser.bankAccount
fieldAccount
union’sBankAccount
type
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:
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 theextends
clause of all other interfaces - Union types marked with
@inaccessible
MUST be excluded
@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.