Graphql Schema

The GraphQL Schema is a machine readable collection of schema organized into a graph. The GraphQL Schema has emerged as a proven way to stitch together much of the API sprawl that has emerged behind the infrastructure, integrations, and applications that we depend on to do business today.

Also known as: GraphQL SDL, Schema Definition Language, GraphQL IDL

Standards

GraphQL Foundation (Linux Foundation) GraphQL Specification (October 2021)
GraphQL Foundation (draft) GraphQL over HTTP
Apollo (de facto) GraphQL Federation v2
Meta (de facto) Relay Cursor Connections Specification
Community GraphQL Scalars

HTTP Headers

Header	Direction	Spec	Description
`Content-Type`	request	GraphQL over HTTP	application/json for the JSON request form; application/graphql for raw query bodies.
`Accept`	request	GraphQL over HTTP	Should include application/graphql-response+json to opt into the strict response semantics.

Status Codes

200 OK — GraphQL over HTTP — Default status — GraphQL surfaces field-level errors in the response body, not as HTTP errors, when using application/json.
400 Bad Request — GraphQL over HTTP — Returned for request-document errors under application/graphql-response+json.

Media Types

application/graphql-response+json — GraphQL over HTTP — Response media type for GraphQL responses.
application/json — Widely accepted request and response media type.
application/graphql — De facto request media type for raw GraphQL query strings (not IANA-registered).

OpenAPI Expression

n/a (GraphQL) — GraphQL does not use OpenAPI; the schema itself (SDL or introspection result) is the contract.

Governance Rules

graphql-eslint/naming-convention (graphql-eslint) — Enforce naming conventions across types, fields, enums.
graphql-eslint/no-deprecated (graphql-eslint) — Disallow use of deprecated fields/enums in operations.
graphql-eslint/require-description (graphql-eslint) — Types and fields should carry descriptions.
graphql-inspector breaking-changes (GraphQL Inspector) — Block PRs that introduce schema-breaking changes.

Risk & Compliance

OWASP:

OWASP API Security Top 10: API4:2023 Unrestricted Resource Consumption — unbounded queries / depth / aliases
OWASP API Security Top 10: API1:2023 Broken Object Level Authorization — resolver-level auth bugs
OWASP API Security Top 10: API3:2023 Broken Object Property Level Authorization — over-fetching via field selection

Compliance:

SOC 2 CC6.1 — per-field authorization decisions must be auditable
GDPR Art. 5(1)(c) — selection-based access enables data minimization when enforced

Security: GraphQL collapses many endpoints into one — depth limits, complexity analysis, persisted queries, disabled introspection in production, and per-resolver authorization are required. Treat introspection as sensitive.

Tools

GraphiQL — IDE / Explorer (MIT)
Apollo Studio / Rover — Schema registry / CLI
GraphQL Inspector — Diff / governance (MIT)
graphql-eslint — Linter (MIT)
GraphQL Code Generator — Codegen (MIT)
Hasura — GraphQL engine

Suggested Metrics

graphql_query_depth_p95 — 95th-percentile depth of executed queries.
graphql_query_complexity_p95 — 95th-percentile complexity score of executed queries.
graphql_field_usage — Per-field call counts; drives deprecation decisions.
graphql_error_rate — Share of responses that include an errors array.
persisted_query_ratio — Share of traffic served via persisted queries vs ad-hoc.

Example Implementations

GitHub — Publishes a public GraphQL API alongside REST.
Shopify — Admin API is GraphQL-first.
Contentful — Content Delivery API offered via GraphQL.

Related Properties

Openapi
Json schema
Webhooks