JSON and GraphQL: How They Work Together

JSON and GraphQL share a symbiotic relationship. While GraphQL is a query language and runtime, JSON is the wire format that carries queries, responses, and schema definitions. Understanding how JSON integrates with GraphQL is essential for building efficient, type-safe APIs. This guide covers GraphQL JSON queries, response formats, schema definitions, variable serialization, and best practices. Use our JSON to GraphQL Schema generator to convert JSON samples to GraphQL types.

How JSON and GraphQL Work Together

GraphQL Component	JSON Role	Example
Queries	Sent as JSON over HTTP POST	{"query": "..."}
Variables	JSON object with variable values	{"variables": {"id": 1}}
Responses	JSON with data/errors structure	{"data": {...}, "errors": [...]}
Schema	SDL (not JSON), but can be described as JSON	Introspection returns JSON
Introspection	JSON response describing the schema	{"__schema": {...}}

GraphQL Request as JSON

// GraphQL HTTP POST body (JSON)
POST /graphql
Content-Type: application/json

{
  "query": "query GetUser($id: ID!, $includePosts: Boolean) { user(id: $id) { id name email posts @include(if: $includePosts) { title createdAt } } }",
  "variables": {
    "id": "42",
    "includePosts": true
  },
  "operationName": "GetUser"
}

// Simplified query without variables
{
  "query": "{ user(id: 42) { id name email } }"
}

GraphQL Response Format

// Successful response
{
  "data": {
    "user": {
      "id": "42",
      "name": "Alice",
      "email": "alice@example.com",
      "posts": [
        { "title": "GraphQL Guide", "createdAt": "2025-01-15T10:00:00Z" }
      ]
    }
  }
}

// Response with errors (partial data)
{
  "data": {
    "user": null
  },
  "errors": [
    {
      "message": "User not found",
      "locations": [{ "line": 2, "column": 5 }],
      "path": ["user"],
      "extensions": {
        "code": "NOT_FOUND",
        "userId": "999"
      }
    }
  ]
}

Converting JSON to GraphQL Schema

// Sample JSON data
{
  "id": 1,
  "name": "Alice",
  "email": "alice@example.com",
  "age": 30,
  "address": {
    "city": "New York",
    "zip": "10001"
  },
  "tags": ["developer", "graphql"]
}

// Generated GraphQL Schema
// type Address {
//   city: String!
//   zip: String!
// }
//
// type User {
//   id: Int!
//   name: String!
//   email: String!
//   age: Int
//   address: Address
//   tags: [String!]
// }
//
// type Query {
//   user(id: Int!): User
// }

Use our JSON to GraphQL Schema tool to automatically convert your JSON samples to GraphQL type definitions.

GraphQL Variables as JSON

// Variables must match the query's variable definitions
// Query:
// mutation CreateUser($input: UserInput!) {
//   createUser(input: $input) { id name }
// }

// Variables (JSON):
{
  "input": {
    "name": "Bob",
    "email": "bob@example.com",
    "age": 25,
    "address": {
      "city": "San Francisco",
      "zip": "94105"
    }
  }
}

// Full request:
{
  "query": "mutation CreateUser($input: UserInput!) { createUser(input: $input) { id name } }",
  "variables": {
    "input": {
      "name": "Bob",
      "email": "bob@example.com",
      "age": 25
    }
  }
}

Apollo Client: JSON Caching

import { ApolloClient, InMemoryCache, gql } from '@apollo/client';

const client = new ApolloClient({
  uri: '/graphql',
  cache: new InMemoryCache({
    typePolicies: {
      User: {
        fields: {
          // Custom merge for paginated fields
          posts: {
            merge(existing = [], incoming) {
              return [...existing, ...incoming];
            }
          }
        }
      }
    }
  })
});

// The cache stores normalized JSON objects
// Each type+id combination is stored once (normalization)
// This allows consistent updates across components

GraphQL vs REST JSON Comparison

Feature	REST JSON	GraphQL JSON
Request format	URL + optional JSON body	JSON with query + variables
Response structure	Envelope (status, data, meta)	Standardized data + errors
Over-fetching	Common — returns all fields	Rare — client specifies fields
Under-fetching	Common — multiple endpoints needed	Rare — nested queries in one request
Versioning	URL or header based	Schema evolution via deprecation
Caching	HTTP caching (URL-based)	Client-side normalization cache
File upload	multipart/form-data	GraphQL multipart request spec

Next Steps

Generate GraphQL schemas from your JSON with JSON to GraphQL Schema. Generate GraphQL queries with JSON to GraphQL Query. Convert GraphQL schemas back to JSON with GraphQL Schema to JSON.