About

Tool No. 45 of Pikkola

A schema is the part of a payload that survives the payload. Writing one by hand is slow, and copying one from a coworker's repository is how two services end up disagreeing about the same field. This page reads a real payload and writes the shape down in five languages, then checks another payload against it.

What it does

How a value becomes a shape

Every value is walked once. A string becomes a string, a whole number becomes an integer, a number with a fraction becomes a number, an object becomes a set of properties, and an array becomes an array of whatever its items are. Nothing is guessed from a key name.

An array is where the interesting part happens. The items are merged pairwise, so an array of thirty rows produces one shape that all thirty satisfy. A property that all rows carry is required; a property that only some rows carry is optional, and the count of rows is kept so the writers know how many times a key went missing. When two items disagree about a type, the result is a union rather than a guess, and the JSON Schema output writes it as anyOf.

One object is the weakest evidence there is, and the tool does not pretend otherwise: with a single row, every key in it is required. Pasting an array of two or three real rows is the single most useful thing a person can do here.

Formats, read from values

A format is only claimed when the value shows it. A string that parses as an ISO 8601 timestamp gets format date-time, one shaped like an address gets email, one shaped like a UUID gets uuid, one that starts with a scheme and two slashes gets uri, and a dotted quad gets ipv4. A plain word gets no format at all, which is the honest answer.

The writers use the format where the language has something for it. Zod gets .email(), .uuid() and .datetime({ offset: true }); Go and Python get a plain string, because their standard library has no such type; TypeScript gets string, because the format is a runtime fact. The JSON Schema keeps the format keyword, which is where it belongs.

What the validator checks

The schema keywords understood here are type, required, properties, items (as a schema or as a tuple), additionalProperties, enum, const, minimum, maximum, exclusiveMinimum, exclusiveMaximum, multipleOf, minLength, maxLength, pattern, format, minItems, maxItems, anyOf, oneOf, allOf, not and a local $ref such as #/$defs/Row. Format is enforced as a check, not left as an annotation, because a person who wrote email in a schema wants to know when a value is not one.

Everything else is left alone rather than half-implemented. A remote $ref is not fetched, since the page cannot make a network request by design. unevaluatedProperties, dependentSchemas, if and then, contentEncoding and the 2019-09 vocabulary are not interpreted. A schema that uses them will still be read, but those keywords simply do not add or remove a failure.

One run lists every failure, not just the first. That is a deliberate difference from the way a validator stops at the first exception: the point of the tab is to see all of the problems in a payload at once, so they can be fixed in one pass.

The five writers

Nested objects become named types in TypeScript, Go and Python, and inline objects in Zod. A property that holds an array of objects becomes a singular type, so items becomes Item and addresses becomes Address. Property names that are not valid identifiers are quoted. Go field names follow the language's habit of capitalising initialisms, so id becomes ID and avatar_url becomes AvatarURL, while the JSON tag keeps the wire name exactly.

Go and Python mark an optional member with a pointer and NotRequired respectively, and both keep the wire name in the tag or the key. Zod chains .optional() and .nullable() so the schema fails in the same places the JSON Schema would.

What it deliberately does not do

Why it is free

Pikkola builds small tools that do one job and keeps them free, with no account and no advertising. A static page that does its work in the browser costs almost nothing to serve, so there is no reason to charge for it.

Contact

A shape that is written wrongly in Korean or Japanese, a keyword that should be supported, a payload that breaks the page: hello@pikkola.com. Send the smallest payload that shows the problem, and what you expected to see.

Back to the studio