Why JSON Schema Generators Miss Null and Array Type Gaps
A JSON Schema generator that turns a single sample JSON into a schema is genuinely convenient for drafting API docs or form validation. But "it generated a schema" and "the schema is accurate" are two different claims. This guide digs into the actual code logic behind two structural gaps that this tool — and most sample-based schema generators in general — share: how they handle null values, and how they infer array types. We'll look at why these gaps exist and how to fix them by hand.
1. The fundamental limit of sample-based inference
A JSON Schema generator isn't magic, just a simple rule engine. It checks the typeof of each value in the input JSON and maps it to a matching schema type: strings become string, booleans become boolean, integers become integer, and so on. The catch is that this approach only ever looks at the one value that happens to be in this sample. It never considers the possibility that, in real production data, the same field could hold a value of a different type on a different request. Null and arrays are the two places where this limitation shows up most clearly.
2. Null values: you get a "null-only" schema, not a nullable one
Looking at the actual inference function in the JSON Schema generator, the first line is if(val===null)return{type:'null'};. In other words, if a value is null, it unconditionally returns just {"type":"null"} — there's no logic anywhere in the generator to produce a union like {"type":["string","null"]} that combines null with another type. The trouble is that in real-world API responses, it's common for a field to be a string when present and null when absent. If that field happened to be null in the sample you fed the tool, the generated schema will reject every future record where that field actually holds a string.
{"middleName": null} and the generated schema is"middleName": {"type": "null"}Validate perfectly normal data like
{"middleName": "Kim"} against that schema and you get a type mismatch error. The correct fix is to manually change it to"middleName": {"type": ["string", "null"]}
3. Arrays: only the first element is inspected, the rest are discarded
The array-handling logic is just as simple. if(val.length>0)s.items=inferSchema(val[0],...) — it recursively infers a schema from only the first element of the array and adopts that result wholesale as the items schema. Even if the array contains a mix of types (a heterogeneous array), the second element onward is never even read. The JSON Schema spec itself supports expressing multiple item types via anyOf or tuple validation (prefixItems), but this generator doesn't attempt any of that — it simply reduces everything to the type of the first element.
| Input array | Actual composition | Generated items schema | Problem |
|---|---|---|---|
[1,"two",3] | Mixed numbers + string | {"type":"integer"} | The string "two" fails validation |
["admin","user"] | Strings only | {"type":"string"} | No problem (happens to be homogeneous) |
In the second row, the array happens to be homogeneous (every element is the same type), so the generated schema is correct by coincidence. The problem is that from a single sample alone, a developer can't tell whether an array was "genuinely homogeneous" or "actually mixed, but the sample happened to line up uniformly."
4. It gets riskier when the objects inside an array differ in shape
This limitation gets worse when array elements are objects. Say the first object in a list of users has an email field, but starting from the second object there's also a phone field — the generator only looks at the first object's properties and locks in the items schema from that alone. The phone field never shows up anywhere in the generated schema, so if you validate real data that includes it against a schema with additionalProperties: false, you end up in the ironic position of perfectly valid data being rejected.
5. A practical checklist: don't ship the generated schema as-is
- If the sample JSON has even one null value, manually change that field's
"type":"null"to an array like["actual type","null"]. - For array fields, first check whether element types are actually consistent in production data; if they're mixed, add
anyOfby hand. - If objects inside an array vary in field composition, gather several samples and manually merge the union of fields into
properties. - Treat the generated result as a draft only — constraints like
minLength,minimum, orenumaren't added by this tool, so you'll need to fill those in separately.
Frequently Asked Questions
Q. What happens if I use a schema with a null field for API validation as-is?
A. Validation fails as soon as the field actually holds a non-null value (a string, number, etc.). You have to manually rewrite it as ["actual type","null"] for it to work correctly.
Q. Is there any way to automatically catch mixed types in an array?
A. No. This tool only applies a simple rule that looks at the first element of one sample, so it has no automatic detection. If there's any chance an array's element types vary, you must review the generated schema by hand.
Q. Does combining several sample JSONs into one input fix this?
A. No. The tool only accepts a single JSON value at a time and reflects that structure as-is — there's no feature for merging multiple samples. Comparing several samples and taking the union of fields and types is something you have to do manually.
Q. Is the generated schema's required array accurate?
A. The required array lists every key that's actually present in the sample object as mandatory. If a particular field should be optional, you need to manually remove its name from the required array after generation.