Glossary
JSON Schema
JSON Schema is a vocabulary for describing the shape of JSON data: which properties exist, what type each has, which are required and which values are allowed. A validator checks a document against the schema and reports every violation.
An example
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"required": ["sku", "price"],
"properties": {
"sku": { "type": "string" },
"price": { "type": "number", "minimum": 0 },
"list_price": { "type": ["number", "null"] },
"availability": { "enum": ["in_stock", "out_of_stock"] }
}
}
type,propertiesandrequiredcarry most of the weight.enumlimits a value to a list, anditemsdescribes the elements of an array.additionalProperties: falserejects any property you did not list. That also rejects a new optional field the source adds later, so use it only when you want that failure.format(for exampledate-time) is an annotation in recent drafts, and validators differ in whether they enforce it.
Why it matters for web data
Validating each response before you store it catches a missing field or a changed type at the door, instead of in a report weeks later. The same schema can document the data for your team and generate types for your code.
A schema checks shape, not truth. A price can be a valid number and still be wrong, so keep checking samples against the source. Keep three cases apart: a field that is missing, one that is null, and one that is an empty string or zero. They mean different things.
In CleanedWeb
Every CleanedWeb API has an output schema: the validated structure and types of its records. It is specific to that API, and a version of the API identifies the schema it follows (see API versioning). Review it before you make a field mandatory downstream. A missing or null field means the value is unavailable, so do not invent a default. Published catalog APIs show their output fields and a sample record on their page.
Tools and docs
- JSON Schema generator Paste sample records and get a schema, TypeScript interfaces and Pydantic models.
- Fields and schemas Read an API's field types and required values.
- JSON to CSV converter Check how records with nested fields flatten into columns.
Related terms
-
Structured data
JSON-LD and schema.org markup: what sites publish for machines and where it falls short.
-
API versioning
How APIs label changes, why you pin a version, and how major versions, deprecation and sunset work.
-
Pagination
How lists are split into pages and how to collect every record without gaps or repeats.
Build an API from a website
CleanedWeb turns a website into a maintained REST API that returns structured records, with a versioned schema and repairs when the site changes.