Are fields nullable or non-null by default?

Non-null by default — every field gets a trailing ! since the inference can't know which fields are optional from a single sample. Refine manually: drop the ! for fields the API may omit, especially in input types.

How are scalar types inferred?

Strings to String, integers to Int, decimals to Float, booleans to Boolean. JSON nulls fall back to nullable String. Refine to ID, custom scalars (DateTime, JSON), or enums manually based on your domain.

Will this generate resolvers?

No. The tool produces the schema (SDL) only. Resolvers map types to data sources and depend on your server framework (Apollo, Yoga, gqlgen). Once the schema lands, your codegen tool of choice can stub resolvers from the SDL.

Is my JSON sent to a server?

No. Conversion runs entirely in your browser — safe for production payloads.

May 2, 20268 min read

How to Convert JSON to GraphQL Schema (SDL Step-by-Step)

Need a JSON to GraphQL schema generator? Here's the path from sample to working SDL. You're wrapping a REST API in GraphQL. The vendor returns JSON; your gateway should expose typed GraphQL queries. The schema is the contract that resolvers fulfill — and writing it by hand from a 30-field payload is error-prone.

In this guide you'll learn how to convert JSON to a GraphQL schema with PDFFlare's JSON to GraphQL tool — how SDL types are inferred, why every field is non-null by default, when to refine to ID / DateTime / enum, and the federation patterns that build on top of single-shape schemas.

What Does the Generated SDL Look Like?

Standard GraphQL Schema Definition Language: type definitions with fields, scalar types (Int, Float, String, Boolean, ID), and required markers (!). One type per unique object shape, named after the property it's nested under (singularized for arrays of objects).

How to Convert JSON to GraphQL (Step by Step)

Open PDFFlare's JSON to GraphQL tool.
Paste a representative JSON sample. Real production payload — sample data is often missing edge cases.
Set the root type name. User, Order, Post — clean PascalCase nouns.
Click Convert to GraphQL. Each unique object shape becomes its own type; fields default to non-null.
Refine and ship. Mark optional fields, add arguments, declare unions or interfaces — the SDL is the starting point.

Real Use Cases

Wrapping a REST API in GraphQL

Generate the SDL from real responses, write resolvers that fetch from the underlying REST API, and clients query the gateway.

Schema-first prototyping

Sketch a payload as JSON, paste it, get a starting SDL file. Faster than writing SDL by hand when you're still iterating.

Federated subgraphs

Bootstrap a subgraph schema from sample data; refine with @key, @external, and @requires directives once core types land.

Documentation and onboarding

Show new engineers the payload in their familiar GraphQL syntax. Easier to read than JSON Schema or a TS interface for many GraphQL-first teams.

Common Mistakes (and How to Avoid Them)

Treating every field as non-null. The generator marks every field !. Mark optional fields nullable (drop the !) where the API may omit them.
Using String for IDs. Refine to ID manually for primary key fields — it has specific serialization semantics in many client libs.
Skipping enums. Status fields modeled as strings should be GraphQL enums. Refine after generation.
Confusing types and inputs.Generated types are output types. For mutations, you'll typically also define input types — derive them from the same JSON sample if needed.

Privacy: Your JSON Stays Local

Conversion runs in your browser. Safe for production payloads.

Related Workflows in the JSON Suite

Adjacent tools you might find useful while working on the same JSON document: the JSON to Protobuf and JSON Schema both pair well with the conversion above. The first handles a different output format that consumers of your data may prefer; the second covers the validation side of the same workflow.

Related Tools

JSON to Protobuf — alternative schema target for gRPC.
JSON to TypeScript — matching client types.
JSON Schema — for runtime input validation.
JSON Formatter — pretty-print before converting.

Schema Design for Long-Lived Services

A GraphQL schema is a long-lived contract between your service and every client that consumes it. Getting initial design decisions right matters because changing them later requires deprecation cycles and coordinated client updates. Several design habits separate schemas that age well from schemas that accumulate technical debt.

The first habit is to design for query patterns, not data structures. The generator emits types that mirror your JSON shape, which mirrors your data store. But GraphQL is a query language, and its strength is letting clients ask for the data they need in the shape they need it. Audit the generated schema and ask: are the relationships in the schema the relationships clients will actually traverse? If not, restructure. A schema that follows query patterns performs better and reads more naturally than a schema that merely reflects storage.

The second habit is to use enums liberally. A status field that takes values from a small known set should be an enum, not a String. Enums document the permitted values inline, give clients autocomplete, and surface unknown values at development time rather than runtime. The generator emits String for stringly-typed fields by default; promote them to enums during the design pass. The cost is small, the payoff in client ergonomics and runtime safety is large.

The third habit is to think carefully about nullability. Every type in GraphQL is nullable unless explicitly marked non-null with the bang. The generator marks everything non-null, which is convenient at first but breaks the moment a field can be missing. Audit every field and mark as non-null only the fields you are willing to commit to always returning. Marking too aggressively creates breaking changes when reality intervenes. Marking conservatively gives clients clearer expectations and lets you add stricter guarantees over time without breaking backward compatibility.

Production Patterns for JSON to GraphQL Schema

A generated SDL schema is a draft. Production schemas need care:

Mark Optional Fields Explicitly

The generator marks every field as required (non-null) by default. Real APIs usually have optional fields. Drop the ! from any field that might be null in production payloads. The schema then accurately describes what callers can expect.

Use Connection Pattern for Lists

The generator emits posts: [Post!]! — a flat list. For paginated lists, refactor to the Relay-style Connection pattern: posts(first: Int): PostConnection withedges, node, and pageInfo. The client gets cursor-based pagination for free.

Add Custom Scalars for Domain Types

GraphQL scalars are String, Int, Float, Boolean, ID. Add custom scalars for things like DateTime, EmailAddress, URL — your resolvers handle parsing/validation, and clients get richer typing.

When to Use a Different Schema Format

GraphQL is ergonomic for many APIs but not always the right fit:

For binary efficiency, use JSON to Protobuf — far smaller wire format.
For pure validation, JSON Schema is simpler.
For OpenAPI-style REST docs, generate an OpenAPI spec instead of converting to GraphQL.

Common Mistakes to Avoid

Marking everything required. The generator does this; you should not. Audit each field and drop the! where genuinely optional. Otherwise clients crash on real-world payloads.
Not naming union types. Mixed-type arrays in JSON become List<Object> by default. Refactor to a real GraphQL union with discriminator types. Better client-side ergonomics, better schema documentation.
Putting cyclic references in the schema. Posts reference Authors, Authors have Posts. The generator emits the cycle. That's usually fine, but check your resolvers don't infinite-loop when traversing them.
Skipping descriptions. GraphQL has built-in doc strings ("A user account." before a type). Use them for every type and field — your clients get autocomplete with descriptions in tools like Apollo Studio.
Treating schema as immutable. Adding a field to a type is non-breaking. Removing or renaming requires deprecation: oldName: String @deprecated(reason: "use newName") — signals to clients without breaking existing queries.

Real-World Use Cases

Apollo Server / Yoga schema scaffolding. Take a sample API response, generate the SDL, drop into your typeDefs, write resolvers.
Federating REST APIs into a GraphQL gateway. Capture each upstream's sample response, generate schemas, federate via Apollo Federation or schema stitching.
Mobile/web BFF (backend for frontend). Generate a GraphQL layer over your existing REST APIs — single endpoint, client picks fields.
Documentation generation. SDL parses with many tools (graphql-doc, SpectaQL) for human-readable docs. Generate the schema, generate the docs, ship.

Polishing the Generator's Output

GraphQL schemas evolve continuously, and the discipline of caring about that evolution from day one separates services that age well from services that accumulate breaking changes. Whatever your specific use case, treat the generated output as a draft that deserves a careful read-through. Generators are excellent at producing the mechanical structure of an artifact and not at the editorial decisions that make the difference between something a colleague will tolerate and something a colleague will appreciate. Read every section of the output the way you would read a piece of writing you were proofreading for a friend. Look for inconsistent naming, missed opportunities to consolidate similar items, and places where the structure is mechanically correct but conceptually awkward. The five minutes spent on this review are the difference between an artifact that pays back over months and one that needs a second pass before it can be used. The generator handles the heavy lifting; you handle the polish that turns a draft into a deliverable. This division of labor is what makes generated code worthwhile in the first place. Without that final pass of human editorial judgment, the generator's output is merely fast rather than valuable, and the value matters more than the speed in nearly every real production setting.

The same logic applies to documentation, comments, and inline context that your generator output rarely supplies. A generated artifact has structure but no narrative; the narrative is what makes the thing useful to the next person who reads it. Add the few sentences of context that explain why a particular choice was made, what the surrounding system expects, and what the next person should look out for. These small editorial gestures cost almost nothing in the moment and pay back many times over when someone is trying to understand what you produced months later. Treat generation as the first ten percent of the work and these editorial passes as the remaining ninety percent that turns mechanical output into something a colleague will reach for again and again. Build the habit early and the gap between your generated artifacts and hand-written ones gets very small over time, which is the real prize.

Wrapping Up

A clean GraphQL SDL is the start of every GraphQL service. PDFFlare's JSON to GraphQL tool gets you to the first draft in two clicks; refining is where the design work happens.