Schema Coordinates

A schema coordinate is a compact string that identifies a schema element. It is useful when logs, registries, schema checks, documentation tools, or policy systems need to refer to the same field, argument, directive, or enum value without embedding a whole schema document.

Examples:

Business
Business.name
Query.searchBusiness(criteria:)
SearchCriteria.filter
SearchFilter.OPEN_NOW
@private
@private(scope:)

Resolving coordinates

Use resolveSchemaCoordinate(schema, coordinate) when you want to resolve a coordinate string directly against a schema:

import { buildSchema, resolveSchemaCoordinate } from 'graphql';
 
const schema = buildSchema(`
  type Query {
    searchBusiness(criteria: SearchCriteria!): [Business]
  }
 
  input SearchCriteria {
    name: String
    filter: SearchFilter
  }
 
  enum SearchFilter {
    OPEN_NOW
    DELIVERS_TAKEOUT
  }
 
  type Business {
    id: ID
    name: String
  }
`);
 
const resolved = resolveSchemaCoordinate(
  schema,
  'Query.searchBusiness(criteria:)',
);
 
if (resolved?.kind === 'FieldArgument') {
  console.log(resolved.fieldArgument.type.toString());
}

The result is a discriminated object. Depending on the coordinate, the kind can be NamedType, Field, InputField, EnumValue, FieldArgument, Directive, or DirectiveArgument.

If the final element does not exist, GraphQL.js returns undefined. If the coordinate refers through a containing element that cannot exist, GraphQL.js throws. For example, Business.unknown returns undefined, but Unknown.field throws because Unknown is not a type in the schema.

Parsing coordinates

Use parseSchemaCoordinate() when tooling needs the AST form before resolving:

import { parseSchemaCoordinate } from 'graphql';
 
const coordinateNode = parseSchemaCoordinate('@private(scope:)');

GraphQL.js exposes coordinate AST node types and kinds:

• TypeCoordinateNode
• MemberCoordinateNode
• ArgumentCoordinateNode
• DirectiveCoordinateNode
• DirectiveArgumentCoordinateNode
• isSchemaCoordinateNode()

The coordinate parser uses a restricted lexer. It accepts coordinate syntax only; it is not the same as parsing an executable GraphQL document or SDL document.

Meta fields and introspection

GraphQL.js can resolve meta fields and introspection schema elements:

resolveSchemaCoordinate(schema, 'Business.__typename');
resolveSchemaCoordinate(schema, '__Directive.name');
resolveSchemaCoordinate(schema, '__DirectiveLocation.INLINE_FRAGMENT');

Meta-field resolution is implementation-defined rather than required for every GraphQL server. Treat it as GraphQL.js behavior when building tooling that must work across implementations.

Common uses

• Store schema change approvals against coordinates such as Query.searchBusiness(criteria:).
• Attach ownership metadata to fields, directives, or enum values.
• Connect validation errors, usage metrics, and schema registry entries.
• Build documentation links without relying on display text.

Schema coordinates identify schema elements; they do not describe executable operation paths. For operation-specific paths, use GraphQL response paths such as ["viewer", "name"].