JSON to GraphQL Schema Generator

Schema Definition Language Basics

GraphQL schemas are written in SDL, a small declarative language with very few concepts. A type declares a named object with a set of fields. Each field has a name and a type. The leaf types are scalars, which hold actual values rather than further structure.

Generating SDL from a JSON sample maps cleanly: each object becomes a type, each key becomes a field, each nested object becomes another type, and each array becomes a list. The generator's job is choosing scalars and inventing type names.

Side by Side Example

A blog post payload and the schema it produces.

Scalar Mapping

Int overflowing is a real production issue rather than a theoretical one. A Unix timestamp in milliseconds is about 1.7 trillion, comfortably outside the 32 bit range, and a server will raise a serialisation error when it tries to return it as an Int. Define a custom scalar for large numbers, dates, and money.

Nullability Is Inverted

This is the concept that trips up everyone arriving from another language. In GraphQL, every field is nullable by default. The exclamation mark marks a field as non-null. It is the opposite of TypeScript, where a field is required unless you mark it optional.

The reason is error handling. If a resolver fails, GraphQL returns null for that field and reports the error alongside the partial data. Marking a field non-null removes that option: the error must propagate upward to the nearest nullable parent, and if there is none, the entire response data becomes null. Non-null is therefore a statement about failure behaviour, not just about data.

Lists have four combinations

For a collection, [Comment!]! is nearly always the right choice, because an empty list already expresses the absence of results and a null list adds a second empty case for clients to handle.

Naming Conventions

• Types are PascalCase and singular: Post, Comment, AuthorProfile.
• Fields are camelCase, so a JSON key of word_count becomes wordCount.
• Enum types are PascalCase and their values are SCREAMING_SNAKE_CASE.
• Input types used as mutation arguments are suffixed with Input, as in CreatePostInput.
• Boolean fields read naturally as questions: isPublished or hasComments rather than published_flag.
• Avoid the Get prefix on query fields. The field is post, not getPost, because the operation type already says it is a read.

A Generated Schema Is a Starting Point

What comes out of a JSON sample is a set of object types. A working GraphQL API needs considerably more, and none of it can be inferred from data.

1. A Query type defining the entry points, including arguments for filtering and pagination.
2. A Mutation type for writes, with input types rather than long argument lists.
3. Resolvers, since the schema describes shape and nothing about where data comes from.
4. Deliberate nullability. The generator marks fields non-null because the sample had values, which is not the same as those fields being guaranteed.
5. Enums for fields with a fixed set of values. A status field typed String tells a client nothing, while an enum makes the possibilities discoverable in any GraphQL explorer.
6. Interfaces and unions where several types share a shape or a field can return one of several types.
7. Pagination, usually the connection pattern with edges, nodes, and a cursor, rather than a bare list.
8. Descriptions, written in triple quoted strings. They surface as documentation in every GraphQL client and cost almost nothing to add.

Two more things the generator cannot see: a field that appeared once in your sample may be repeatable in reality and should be a list, and circular references between types are normal in GraphQL but impossible to spot in a single flat payload.