CleanedWeb

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"] }
  }
}

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

Related terms

All glossary entries

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.