JSON Schema Generator

Where a schema like this actually earns its keep

The first scenario is a contract between a frontend and a backend. Someone builds a form from a sample response, and a month later a validation error arrives for a field nobody ever discussed. A draft schema kept next to that sample turns a silent assumption into an explicit list of fields, and the mismatch becomes visible immediately. The second scenario is generating types for a client: the structure under properties turns into an interface or a TypeScript type, and the editor starts suggesting fields while you type.

The third scenario is checking config and data files. If a service reads YAML or JSON configuration, a schema derived from a sample is handy to keep alongside and to run every file through at startup. A typo in a key or a missing mandatory field gets caught before the service breaks in production. The fourth is documentation: the same schema works as an appendix to an API description because it shows types, nesting and requiredness in a machine-readable form. Next to a walkthrough of how a URL breaks into parts it answers most of a beginner's questions.

• A format agreement between two teams
• Form templates and hints in a code editor
• Validation of config files when a service starts
• A machine-readable description of a format in the docs
• Generating TypeScript types from a response structure
• Regression checks on a response shape after backend changes

Mistakes that produce a wrong schema

The most common mistake is treating a draft as a finished contract. A schema built from one sample looks solid: types are in place, required is filled, the structure is tidy. What it lacks is ranges, formats, enums and descriptions, and that creates an illusion of completeness. The second mistake is over-engineering types: if a field arrived as a string in the sample, should the schema forbid numbers? The strict answer depends on the server rather than the sample, and such decisions are better made explicitly than inherited from a single response.

The third mistake is not noticing mixed types. A field that arrives as a number in some records and a string in others produces a list of types in the schema, and that is not a generator failure but a warning about a real problem on the server. The fourth is forgetting nesting: if an object holds an array of objects, the required inside items follows its own logic, and it is easy to miss when editing by hand. The fifth is leaving descriptions empty, which means that someone reading the schema in six months will have no idea what a field is for. For more on formats and data structures, the piece on JSON and XML helps.

• Mistaking a draft for a complete contract
• Inheriting type strictness from a single sample
• Ignoring mixed types in the same field
• Forgetting required inside nested arrays
• Leaving descriptions blank
• Noticing fields only after the sample missed them

Walking through a sample step by step

Take a small response: an array of two objects where the first one has a note field and the second does not. The generator sees two objects, merges their keys, and counts for each key how many times it appeared. The keys id and title appeared twice out of two, so they went into required. The key note appeared once, so it lives in properties but not in required. The type of note came out as null, and that is honest: the sample held exactly null there.

Nested objects and array elements are parsed the same way: the type of a value is established first, then the keys of all encountered objects are merged, and only after that is required computed. The order matters, because required is not a property of an individual field but a conclusion about whether a key shows up in every record. That is also why a sample of a single object produces a schema where every field is mandatory: there is nothing to compare against.

Parsing is a single pass over the input JSON and runs entirely in the browser: the sample is never sent anywhere.

What to do with the draft next

The first step after generating is to read the schema yourself and fix it by hand. Three things deserve a look: mandatory fields that do not always arrive, types the server changes from time to time, and descriptions that do not exist at all. The second step is to run the schema through the validator you will actually use in the project, against several real responses. That exposes the gap between expectation and what the server really sends and saves you from surprises in production.

The third step is to keep the schema in the repository next to the code that uses it and to update it whenever the format changes. A schema living apart from the code goes stale first. If your project is a monorepo or generates types, it helps to see how JSON to TypeScript conversion and diffing two JSON documents work: the difference shows which fields appeared and which disappeared after a server-side change.

• Read the schema yourself and fix it by hand
• Validate it with the same validator the project uses
• Run it against several real responses
• Add descriptions and constraints wherever you know them
• Keep the schema next to the code and update both together