JSON to GraphQL Schema Generator

What is a GraphQL Schema?

A GraphQL schema is the central contract that defines every piece of data available in a GraphQL API. Written in the GraphQL Schema Definition Language (SDL), it declares the types of objects the API works with, the fields each type exposes, and the relationships between types. Unlike REST APIs where the structure is implicit, a GraphQL schema is explicit, strongly typed, and self-documenting.

Every GraphQL API has at least three built-in root types: Query (read operations), Mutation (write operations), and optionally Subscription (real-time updates). Under these root types, you define your own custom object types that represent the data entities in your application.

A simple GraphQL type definition looks like this:

type User {
  id: ID!
  name: String!
  email: String!
  age: Int
  active: Boolean!
  createdAt: String
}

type Query {
  user(id: ID!): User
  users: [User!]!
}

The exclamation mark (!) denotes a non-nullable field. Fields without it may return null. This maps directly to whether a JSON field is always present or sometimes missing/null.

How Types Are Inferred from JSON

The generator inspects your JSON structure and infers the appropriate GraphQL type for every field. The inference logic examines the JavaScript type of each value and applies the closest GraphQL scalar type. For nested objects, it recursively generates new named types.

Example JSON input:

{
  "id": 1,
  "username": "alice_dev",
  "score": 98.5,
  "verified": true,
  "bio": null,
  "tags": ["javascript", "graphql"],
  "profile": {
    "avatar": "https://example.com/avatar.png",
    "followers": 1200
  }
}

Generated GraphQL schema:

type Profile {
  avatar: String!
  followers: Int!
}

type RootType {
  id: Int!
  username: String!
  score: Float!
  verified: Boolean!
  bio: String
  tags: [String!]!
  profile: Profile!
}

Notice that bio is nullable (no !) because its JSON value is null, and the nested profile object becomes a separate Profile type.

Scalar Types: JSON to GraphQL Mapping

GraphQL has five built-in scalar types. Every JSON primitive maps to one of them:

Note: JSON does not have a native Date type. Dates stored as ISO strings ("2024-01-15T10:00:00Z") map to String in the generated schema. If your API uses dates heavily, consider using the custom DateTime scalar from the graphql-scalars library and manually update the generated type.

Use Cases: When to Generate GraphQL Schema from JSON

The JSON to GraphQL schema generator is most useful in four common development scenarios:

Wrapping an existing REST API with GraphQL

When building a GraphQL layer over an existing REST API, the REST responses are the source of truth for your data shapes. Copy a sample API response JSON into the generator to scaffold your GraphQL types instantly. This avoids manually transcribing field names and types, which is tedious and error-prone for large response structures.

Schema-first API design

In schema-first development, you define the GraphQL schema before writing any resolvers. If your data model is already expressed as JSON (e.g., in a database seed file or API documentation), the generator gives you a head start on the SDL definition that you can refine before implementation begins.

Migrating from REST to GraphQL

Teams migrating from REST to GraphQL need to define GraphQL types for all their existing data models. Using JSON examples from the current REST API as input to the generator dramatically speeds up the migration process, ensuring no fields are missed and types are correctly inferred.

Learning and prototyping

Developers learning GraphQL can use the generator to understand how JSON data maps to GraphQL types. Paste any JSON from a public API, see the resulting schema, and immediately understand the relationship between the two formats.

Frequently Asked Questions

What is a GraphQL schema?

A GraphQL schema is a strongly typed contract that defines every type, field, and relationship available in a GraphQL API. Written in the GraphQL SDL (Schema Definition Language), it tells both clients and servers exactly what data can be queried, what arguments are accepted, and what types will be returned.

How are JSON types mapped to GraphQL scalar types?

JSON strings map to String, integers to Int, decimals to Float, booleans to Boolean, null values to nullable fields (no !), objects to new named types, and arrays to list types like [String] or [User].

Can I use a generated GraphQL schema directly in my API?

The generated schema provides the type definitions as a ready-to-use starting point. You still need to implement resolvers - the functions that actually fetch or compute the data for each field. The generator handles structural boilerplate; business logic and data fetching are your responsibility to add.

How do nested JSON objects get represented in GraphQL?

Nested JSON objects become separate named GraphQL types. A JSON object with an address field containing city and zip generates an Address type with those fields, and the parent type references it as address: Address!.