JSON Schema Generator: Complete Guide to Inference & Exports

What Is JSON Schema?

JSON Schema is a declarative vocabulary for describing the structure of JSON data. It defines which fields an object should have, what types those fields can be, whether they are required, and what constraints apply — like string formats, numeric ranges, or array item types.

The standard is maintained by the JSON Schema organization and has gone through several draft versions. Draft 2020-12 is the latest and is recommended for new projects. Older drafts (2019-09 and Draft 07) remain widely used in existing toolchains, particularly in OpenAPI 3.0 specifications which rely on Draft 07.

A simple JSON Schema for a user object looks like this:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": { "type": "integer" },
    "name": { "type": "string" },
    "email": { "type": "string", "format": "email" }
  },
  "required": ["id", "name", "email"]
}

This schema says: the root is an object with three properties — id (an integer), name (a string), and email (a string with email format). All three are required.

Why Generate Schema from JSON?

Writing JSON Schema by hand is tedious. A moderately complex API response with nested objects and arrays can produce a schema hundreds of lines long. Generating the schema from sample data eliminates this manual work.

Common use cases for generated schemas:

• API validation — validate incoming request bodies and outgoing responses against a schema to catch breaking changes early
• Code generation — use the schema to generate TypeScript types, C# classes, or other language bindings
• Documentation — include the schema in API docs so consumers know exactly what to expect
• Data pipeline quality — validate data at each stage of an ETL pipeline to catch malformed records
• Form generation — libraries like react-jsonschema-form render UI forms directly from a JSON Schema
• Contract testing — ensure that a service's actual output matches the agreed-upon schema

How Schema Inference Works

Schema inference examines each value in the JSON and determines its type, then builds a schema recursively. Here is how the generator handles each JSON type:

Primitives

Strings, numbers, booleans, and null are straightforward: the generator emits "type": "string", "type": "number" (or "integer" if the value is a whole number and integer detection is on), "type": "boolean", or "type": "null".

String Format Detection

When format detection is enabled, the generator checks string values against patterns for common formats: email addresses, URIs (http/https), ISO 8601 date-time strings, and UUIDs. If a match is found, a "format" keyword is added to the schema — for example, "format": "email".

Objects

For each object, the generator collects all keys and recursively infers a schema for each value. The required array depends on the selected mode: "all" marks every observed key as required, "none" omits the required array entirely, and "heuristic" marks a key as required only if its value is non-null, non-empty-string, non-empty-array, and non-empty-object.

Arrays

Arrays are where inference gets interesting. The generator needs to produce a single items schema that describes all elements. Three modes are available:

• Union — merges the schemas of all items (up to the sample limit). For arrays of objects, this means taking the union of all properties and the intersection of required fields.
• First item — uses only item[0] to infer the items schema. Faster, but may miss optional fields.
• Strict — infers from the first item and warns if any subsequent items have a different structure.

When merging two object schemas, the generator takes the union of property keys. If a key exists in one schema but not the other, it becomes optional (removed from required). If two values for the same key have different types, the generator produces a type union — for example, "type": ["string", "integer"].

Inference Settings Explained

Export Formats

TypeScript Types

The TypeScript export maps the schema to type definitions. Objects become interface-like types with required and optional properties. Arrays become T[]. Union types use |. Nullable fields become string | null. This gives you type safety in TypeScript projects without writing types manually.

type Root = {
  id: number;
  name: string;
  email?: string | null;
  tags: string[];
};

Zod Validation Schemas

Zod is a TypeScript-first schema validation library. The Zod export produces a runtime validator that matches the inferred schema. This is useful when you need both compile-time types and runtime validation — for example, validating API responses in a Next.js application.

import { z } from "zod";

export const Root = z.object({
  id: z.number().int(),
  name: z.string(),
  email: z.string().email().nullable().optional(),
  tags: z.array(z.string()),
});

C# POCO Classes

The C# export generates plain old CLR objects (POCOs) suitable for System.Text.Json or Newtonsoft.Json deserialization. Nested objects become separate classes. Arrays become List<T>. Nullable types use the ? suffix.

SQL DDL

The SQL export generates a CREATE TABLE statement from flat object properties. Strings map to NVARCHAR(255), integers to INT, numbers to DECIMAL(18,6), booleans to BIT, and date-time strings to DATETIME2. Nested objects and arrays are stored as NVARCHAR(MAX) with a JSON comment. This is most useful for quick prototyping of SQL Server tables from JSON data.

Edge Cases and Warnings

The generator shows warnings in the following situations:

• Mixed types — when the same field has different types across array items (e.g., sometimes a string, sometimes an integer), a type union is created and a warning is shown.
• Empty arrays — an empty array produces an items: {} schema because there are no items to infer from.
• Missing fields — when objects in an array have different keys, the required array is reduced to the intersection and a warning lists the inconsistent fields.
• Sample limits — for arrays with more than 200 items, only the first 200 are inspected. A warning indicates that the schema is based on a sample.
• Depth limits — recursion stops at 30 levels deep to prevent stack overflow on pathological inputs.

Best Practices

• Use representative samples. The schema is only as good as the input. If your JSON sometimes has a field that is absent in your sample, the schema won't include it.
• Review the required array. The "all present" mode marks everything as required, which may be too strict. Try the heuristic mode or switch to "none" and add required fields manually.
• Choose the right null handling. If your API returns null for missing values, use "nullable" mode. If nulls are exceptional, "ignore" mode produces cleaner schemas.
• Validate the generated schema. Paste the output into a JSON Schema validator (like JSON Validator) and test it against additional sample data.
• Start with 2020-12. Use the latest draft unless your toolchain requires an older one. Draft 07 is needed for OpenAPI 3.0; 2020-12 works with OpenAPI 3.1.

Frequently Asked Questions

What is JSON Schema and why generate it from JSON?

JSON Schema is a vocabulary for annotating and validating JSON data. Generating it from a sample avoids hand-writing verbose schema definitions — the tool infers types, required fields, and formats automatically.

How does the generator handle arrays with different object shapes?

In union mode, the generator merges all item schemas by taking the union of properties and the intersection of required fields. Fields that appear in some items but not others become optional. A warning is shown listing the inconsistent fields.

Can I use the generated TypeScript types in production?

The generated types are a strong starting point. Review them for edge cases — particularly union types and optional fields — and add custom validation logic where needed. Consider using the Zod output for runtime validation alongside the TypeScript types.

Which JSON Schema draft should I use?

Draft 2020-12 is the latest and recommended for new projects. Use Draft 07 if your toolchain (e.g., older validators, OpenAPI 3.0, or certain code generators) requires it. Draft 2019-09 is a middle ground but is less commonly targeted.