tag v0.1

for tagging GraphQL schema elements with names

Status	Release
Version	0.1

This document defines a core feature named tag for labeling schema elements with arbitrary names (or tags).

This specification provides machinery to apply arbitrary tags to schema elements via the application of @tag directive usages. Tags can be applied to field, object, interface, and union definitions.

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.

1.1What this document isn't

This document specifies only the definition of the @tag directive. Tags have a number of useful applications including metadata and schema processing, none of which are specified within this document.

2Example: Team Ownership Metadata

The following example demonstrates how team ownership over types and fields can be declaratively expressed via inline metadata. One might imagine a CI workflow which analyzes a schema diff and uses @tag names to authorize or require approval for changes to parts of the graph.

Example № 1

directive @tag(name: String!) repeatable on 
  | FIELD_DEFINITION
  | INTERFACE
  | OBJECT
  | UNION

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

type Query {
  customer(id: String!): Customer @tag(name: "team-customers")
  employee(id: String!): Employee @tag(name: "team-admin")
}

interface User @tag(name: "team-accounts") {
  id: String!
  name: String!
}

type Customer implements User @tag(name: "team-customers") {
  id: String!
  name: String!
  cart: [Product!] @tag(name: "team-shopping-cart")
}

type Employee implements User @tag(name: "team-admin") {
  id: String!
  name: String!
  ssn: String!
}

3Overview

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

The @tag directive is, in its simplest form, a mechanism for applying arbitrary string metadata to the fields and types of a schema. This metadata is potentially useful throughout the schema’s lifecycle, including, but not limited to, processing, static analysis, and documentation.

4@tag

A schema which implements the @tag spec MUST provide a definition which is compatible with the definition below:

directive @tag(name: String!) repeatable on
  | FIELD_DEFINITION
  | INTERFACE
  | OBJECT
  | UNION

§Index

@tag