JSON in GraphQL: Variables, Scalars, and Responses

Written and reviewed by the Jsonic editorial team — every guide is verified against the official spec or runtime before publication.

Last updated: May 19, 2026

GraphQL and JSON are deeply intertwined: every GraphQL HTTP request is a JSON object, every response is JSON, and storing arbitrary data in a GraphQL field requires a custom JSON scalar. This guide covers all three layers — the request format, the JSON/JSONObject scalar types, parsing the response envelope, using graphql-request, and generating TypeScript types with graphql-codegen.

GraphQL Request Format as JSON

Every GraphQL operation is sent over HTTP as a JSON POST body. The body is a JSON object with three possible keys: query (the GraphQL document string, required), variables (a JSON object, optional), and operationName (a string, optional). This structure is defined by the GraphQL over HTTP specification.

// Minimal request — query only
{ "query": "query { users { id name } }" }

// Full request with variables and operationName
{
  "query": "query GetUser($id: ID!, $includeEmail: Boolean!) { user(id: $id) { name email @include(if: $includeEmail) } }",
  "variables": {
    "id": "usr_42",
    "includeEmail": true
  },
  "operationName": "GetUser"
}

// Send with fetch — standard HTTP POST
const response = await fetch('https://api.example.com/graphql', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer ' + token,
  },
  body: JSON.stringify({
    query: `
      query GetUser($id: ID!) {
        user(id: $id) {
          id
          name
          email
        }
      }
    `,
    variables: { id: 'usr_42' },
  }),
})

const json = await response.json()
// json.data.user → { id: "usr_42", name: "Alice", email: "alice@example.com" }
// json.errors   → undefined on success

The operationName field is required only when the document contains multiple named operations. It selects which operation to execute. For mutations, use the mutation keyword in the query string — the HTTP method and body format are identical to queries.

Query Variables

Variables decouple dynamic values from the query string. Instead of interpolating user input directly into the query, declare typed variables in the operation signature and pass values in the variables object. This is required for security (prevents GraphQL injection) and performance (servers can cache parsed query documents by hash when the query string is constant).

// ✅ Correct — variables keep the query string constant
const query = `
  mutation CreateProduct($input: CreateProductInput!) {
    createProduct(input: $input) {
      id
      name
      price
    }
  }
`

const variables = {
  input: {
    name: 'Widget Pro',
    price: 29.99,
    category: 'tools',
    metadata: { sku: 'WGT-001', warehouse: 'US-WEST' },
  },
}

const body = JSON.stringify({ query, variables })

// ❌ Unsafe — never interpolate user data into query strings
// const query = `mutation { createProduct(name: "${userInput}") { id } }`
// This bypasses query caching and opens injection vulnerabilities

Variable Type Declarations

Variable types in the GraphQL operation must match the schema. Declare them after the operation name in parentheses. Non-null types use !; lists use []:

# String variable — nullable
query Search($term: String) { search(term: $term) { id title } }

# Non-null ID variable
query GetPost($id: ID!) { post(id: $id) { title body } }

# Non-null list of non-null IDs
query GetPosts($ids: [ID!]!) { posts(ids: $ids) { id title } }

# Input object variable
mutation UpdateUser($id: ID!, $input: UpdateUserInput!) {
  updateUser(id: $id, input: $input) { id name email }
}

# JSON scalar variable (custom scalar — see Section 3)
mutation SaveMetadata($id: ID!, $meta: JSON!) {
  saveMetadata(id: $id, meta: $meta) { ok }
}

JSON Scalar Type

GraphQL has five built-in scalars — String, Int, Float, Boolean, and ID — but no JSON type. To store arbitrary JSON data in a field, define a custom scalar. The graphql-scalars library provides production-ready JSON and JSONObject scalars.

npm install graphql-scalars

# schema.graphql — declare the custom scalars
scalar JSON
scalar JSONObject

type Product {
  id: ID!
  name: String!
  price: Float!
  metadata: JSONObject  # arbitrary key-value object
  variants:  JSON       # any JSON value (array, object, string, etc.)
}

type Query {
  product(id: ID!): Product
}

type Mutation {
  updateMetadata(id: ID!, metadata: JSONObject!): Product
}

// resolvers.ts — wire up the graphql-scalars resolvers
import { GraphQLJSON, GraphQLJSONObject } from 'graphql-scalars'

export const resolvers = {
  JSON:       GraphQLJSON,
  JSONObject: GraphQLJSONObject,

  Query: {
    product: async (_: unknown, { id }: { id: string }) => {
      return db.products.findById(id)
      // metadata field returns a plain JS object — serialized automatically
    },
  },

  Mutation: {
    updateMetadata: async (
      _: unknown,
      { id, metadata }: { id: string; metadata: Record<string, unknown> }
    ) => {
      // metadata is already a plain JS object — no JSON.parse needed
      return db.products.update(id, { metadata })
    },
  },
}

JSON vs JSONObject Scalar

Prefer JSONObject when you know the field will always be a key-value map — it gives clients a stronger contract. Use JSON only when the field genuinely could be any JSON value, including arrays or primitives.

Parsing GraphQL JSON Responses

Every GraphQL response is a JSON object with a fixed envelope structure. The top-level keys are data (the query result), errors (an array of error objects, present only when at least one error occurred), and extensions (optional server metadata). Both data and errors can appear together in a partial-success response.

// Successful response
{
  "data": {
    "product": {
      "id": "prod_1",
      "name": "Widget Pro",
      "metadata": { "sku": "WGT-001", "warehouse": "US-WEST" }
    }
  }
}

// Partial success — data and errors coexist
{
  "data": {
    "product": {
      "id": "prod_1",
      "name": "Widget Pro",
      "metadata": null
    }
  },
  "errors": [
    {
      "message": "Metadata access denied",
      "locations": [{ "line": 5, "column": 5 }],
      "path": ["product", "metadata"],
      "extensions": { "code": "FORBIDDEN" }
    }
  ]
}

// Fatal error — data is null
{
  "data": null,
  "errors": [
    {
      "message": "Product not found",
      "locations": [{ "line": 2, "column": 3 }],
      "path": ["product"],
      "extensions": { "code": "NOT_FOUND" }
    }
  ]
}

Parsing the Envelope in TypeScript

// Define a typed envelope wrapper
interface GraphQLResponse<T> {
  data?: T
  errors?: Array<{
    message: string
    path?: Array<string | number>
    locations?: Array<{ line: number; column: number }>
    extensions?: Record<string, unknown>
  }>
  extensions?: Record<string, unknown>
}

// Generic fetch wrapper
async function graphqlFetch<T>(
  endpoint: string,
  query: string,
  variables?: Record<string, unknown>
): Promise<GraphQLResponse<T>> {
  const res = await fetch(endpoint, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ query, variables }),
  })

  if (!res.ok) throw new Error(`HTTP ${res.status}: ${res.statusText}`)
  return res.json() as Promise<GraphQLResponse<T>>
}

// Usage — always check both data and errors
const { data, errors } = await graphqlFetch<{ product: Product }>(
  '/graphql',
  `query GetProduct($id: ID!) { product(id: $id) { id name metadata } }`,
  { id: 'prod_1' }
)

if (errors) {
  // Log all errors; data may still be partially available
  for (const err of errors) {
    console.error(`[${err.extensions?.code}] ${err.message} at ${err.path?.join('.')}`)
  }
}

if (data?.product) {
  const { name, metadata } = data.product
  // metadata is typed as unknown (JSON scalar) — validate before use
  if (typeof metadata === 'object' && metadata !== null && 'sku' in metadata) {
    console.log((metadata as { sku: string }).sku)
  }
}

graphql-request Client

graphql-request is a minimal GraphQL client (~5 kB gzipped) that handles the JSON serialization and envelope parsing automatically. It sets Content-Type: application/json, serializes variables with JSON.stringify, and returns response.data directly — not the full envelope.

npm install graphql-request graphql

import { GraphQLClient, gql } from 'graphql-request'

const client = new GraphQLClient('https://api.example.com/graphql', {
  headers: { Authorization: 'Bearer ' + process.env.API_TOKEN },
})

// Define the query with the gql tagged template literal
const GET_PRODUCT = gql`
  query GetProduct($id: ID!) {
    product(id: $id) {
      id
      name
      price
      metadata   # JSON scalar — returned as plain JS object
    }
  }
`

// Define a TypeScript type for the response
type ProductQuery = {
  product: {
    id: string
    name: string
    price: number
    metadata: Record<string, unknown> | null
  }
}

// request() returns data directly — envelope is unwrapped
const data = await client.request<ProductQuery>(GET_PRODUCT, { id: 'prod_1' })
console.log(data.product.name)     // 'Widget Pro'
console.log(data.product.metadata) // { sku: 'WGT-001', warehouse: 'US-WEST' }

// Error handling — graphql-request throws ClientError on GraphQL errors
import { ClientError } from 'graphql-request'

try {
  const data = await client.request<ProductQuery>(GET_PRODUCT, { id: 'not-found' })
} catch (err) {
  if (err instanceof ClientError) {
    console.error(err.response.errors)  // GraphQL errors array
    console.error(err.response.status)  // HTTP status
  }
}

Sending JSON Variables

Variables are passed as a plain JavaScript object — graphql-request calls JSON.stringify internally. For JSON scalar fields, the value is a plain JS object or array:

const UPDATE_METADATA = gql`
  mutation UpdateMetadata($id: ID!, $metadata: JSONObject!) {
    updateMetadata(id: $id, metadata: $metadata) {
      id
      metadata
    }
  }
`

type UpdateMetadataMutation = {
  updateMetadata: {
    id: string
    metadata: Record<string, unknown>
  }
}

// metadata is a plain JS object — no JSON.stringify needed
const result = await client.request<UpdateMetadataMutation>(UPDATE_METADATA, {
  id: 'prod_1',
  metadata: {
    sku: 'WGT-002',
    warehouse: 'EU-CENTRAL',
    tags: ['sale', 'featured'],
    dimensions: { weight: 0.5, unit: 'kg' },
  },
})

console.log(result.updateMetadata.metadata)
// { sku: 'WGT-002', warehouse: 'EU-CENTRAL', tags: [...], dimensions: {...} }

TypeScript Types with graphql-codegen

graphql-codegen generates TypeScript types from your GraphQL schema and query files, keeping types always in sync with the schema. For JSON scalar fields, configure the scalar mapping to control the generated TypeScript type.

npm install --save-dev @graphql-codegen/cli @graphql-codegen/typescript @graphql-codegen/typescript-operations

// codegen.ts — configure scalar type mappings
import type { CodegenConfig } from '@graphql-codegen/cli'

const config: CodegenConfig = {
  schema: 'schema.graphql',
  documents: 'src/**/*.graphql',
  generates: {
    'src/generated/graphql.ts': {
      plugins: ['typescript', 'typescript-operations'],
      config: {
        // Map custom scalars to TypeScript types
        scalars: {
          JSON:       'unknown',
          JSONObject: 'Record<string, unknown>',
          // Or use more specific types:
          // JSONObject: 'Record<string, string | number | boolean | null>',
        },
      },
    },
  },
}

export default config

# Run codegen — generates src/generated/graphql.ts
npx graphql-codegen

# Watch mode — regenerates on schema or query changes
npx graphql-codegen --watch

Given the schema from Section 3, codegen generates:

// src/generated/graphql.ts — auto-generated, do not edit

export type Scalars = {
  ID:         { input: string;                   output: string }
  String:     { input: string;                   output: string }
  Boolean:    { input: boolean;                  output: boolean }
  Int:        { input: number;                   output: number }
  Float:      { input: number;                   output: number }
  JSON:       { input: unknown;                  output: unknown }
  JSONObject: { input: Record<string, unknown>;  output: Record<string, unknown> }
}

export type Product = {
  __typename?: 'Product'
  id:        Scalars['ID']['output']
  name:      Scalars['String']['output']
  price:     Scalars['Float']['output']
  metadata?: Scalars['JSONObject']['output'] | null
  variants?: Scalars['JSON']['output'] | null
}

// Operation-specific types generated from query files
export type GetProductQueryVariables = {
  id: Scalars['ID']['input']
}

export type GetProductQuery = {
  __typename?: 'Query'
  product?: {
    __typename?: 'Product'
    id:       string
    name:     string
    metadata: Record<string, unknown> | null
  } | null
}

Use the generated types with graphql-request for end-to-end type safety:

import { GetProductQuery, GetProductQueryVariables } from './generated/graphql'

const data = await client.request<GetProductQuery, GetProductQueryVariables>(
  GET_PRODUCT,
  { id: 'prod_1' }
)

// Fully typed — no manual interface needed
data.product?.metadata  // Record<string, unknown> | null | undefined

Error Handling in GraphQL JSON

GraphQL errors appear in the errors array, not in the HTTP status code. Each error object has a required message field and optional path, locations, and extensions fields. The path array maps an error to the exact field that failed; extensions.code provides a machine-readable error code.

// Full error object structure
{
  "errors": [
    {
      "message": "Cannot access metadata: insufficient permissions",
      "locations": [{ "line": 5, "column": 5 }],
      "path": ["product", "metadata"],
      "extensions": {
        "code": "FORBIDDEN",
        "http": { "status": 403 }
      }
    }
  ]
}

// Error handling with error-code classification
async function loadProduct(id: string) {
  const res = await fetch('/graphql', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      query: `query GetProduct($id: ID!) {
        product(id: $id) { id name metadata }
      }`,
      variables: { id },
    }),
  })

  if (!res.ok) throw new Error(`Transport error: HTTP ${res.status}`)

  const { data, errors } = await res.json()

  // Index errors by path for targeted handling
  const errorByPath: Record<string, string> = {}
  for (const err of errors ?? []) {
    const key = (err.path ?? []).join('.')
    const code = err.extensions?.code ?? 'UNKNOWN'
    errorByPath[key] = code
  }

  return {
    product:       data?.product ?? null,
    metadataError: errorByPath['product.metadata'] ?? null,
    // e.g. 'FORBIDDEN' if metadata was blocked
  }
}

Error Codes from Apollo Server

Build error-handling logic against extensions.code, not message — messages are human-readable and may change between server versions; codes are stable API contracts.

Key Definitions

GraphQL scalar

A GraphQL scalar is a primitive leaf type that resolves to a single value. The five built-in scalars are String, Int, Float, Boolean, and ID, each serialized as the corresponding JSON value type in responses. Custom scalars extend this set with application-specific types.

JSON scalar

A custom GraphQL scalar — not built into the spec — that accepts any valid JSON value as input or output. The graphql-scalars library provides a production-ready implementation. JSON scalar fields are typed as unknown in TypeScript generated code because their shape is not known at compile time.

Query variables

A JSON object sent alongside a GraphQL operation in the variables field of the request body. Variables decouple dynamic values from the query string, prevent injection attacks, and allow servers to cache parsed query documents by their stable string hash. They are declared with typed signatures in the GraphQL operation: query GetUser($id: ID!).

Data envelope

The top-level structure of every GraphQL JSON response: a JSON object containing a data key (the query result), an optional errors array (field-level errors), and an optional extensions object (server metadata). The envelope is defined by the GraphQL specification and is the same regardless of server implementation.

graphql-codegen

A code generation tool (@graphql-codegen/cli) that reads a GraphQL schema file and query documents, then outputs TypeScript types for every schema type and operation. Custom scalar types are mapped to TypeScript types via the scalars config key. Running npx graphql-codegen regenerates all types in under one second whenever the schema or queries change.

FAQ