From JSON Schema to Sample JSON: Mock Data, Examples and Edge Cases

A JSON Schema says what data is allowed. It does not show what the data looks like, and that is often what a teammate, a frontend prototype or a test actually needs. Generating a sample document from a schema fills that gap. It is a simple idea with a few sharp edges, mostly around the difference between "has the right shape" and "is valid".

How a generator picks values

A generator walks the schema the same way a validator does, but instead of checking a value at each node it produces one. The type keyword does most of the work:

{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "email": { "type": "string" },
    "age": { "type": "integer" },
    "roles": { "type": "array", "items": { "type": "string" } }
  },
  "required": ["name", "email"]
}

{
  "name": "John Doe",
  "email": "[email protected]",
  "age": 11,
  "roles": ["sample string", "sample string"]
}

Notice that age and roles are present even though they are not required. Most generators include every property by default, because a sample that shows all fields is more useful as documentation.

Keywords beyond type

Type-only generation gives you the right shape. Whether the result is valid depends on the other keywords in the schema. A structural generator like the one on this site reads type, properties and items and ignores the rest, so you may need to adjust the output by hand:

Always validate the sample

The check takes a few lines and catches the mismatch before a reader copies a broken example. With Ajv:

import Ajv2020 from 'ajv/dist/2020';

const validate = new Ajv2020({ allErrors: true }).compile(schema);
if (!validate(sample)) {
  for (const err of validate.errors) {
    console.log(err.instancePath || '(root)', err.message);
  }
}

Running this in CI for every example in your documentation is one of the cheapest ways to keep docs and schema from drifting apart.

Choosing the right kind of generator

• A structural sample (this site's tool) is enough when you need to see the shape, scaffold a fixture or hand a frontend developer something to render.
• A keyword-aware faker such as json-schema-faker respects formats, ranges, patterns and enums and produces random valid data. Use it for mock servers and load tests.
• Property-based testing libraries (for example hypothesis-jsonschema in Python) generate many valid documents, including awkward ones: empty strings, zero, maximum lengths. Use them to test the code that consumes the data.
• Hand-written examples in the schema itself are still the best documentation. A generator is the fallback for the schemas nobody annotated.

Edge cases worth knowing

• Recursive schemas. A tree node that references itself would generate forever. Generators need a depth limit; when writing one, stop at optional recursive properties first.
• Contradictory schemas. { "type": "string", "enum": [1, 2] } accepts nothing. No sample exists, and a failed generation is a useful signal that the schema is wrong.
• Optional versus required. For negative tests, generate the full sample and then delete one required key at a time. Each variant should be rejected.

Try it

Starting from data instead of a schema? See inferring a JSON Schema from sample JSON.