JSON Schema

json schema · schema validation · json validation · data contract · feed validation · ajv

Definition

JSON Schema is a language for describing the structure and constraints of JSON documents; it is used to validate product feeds, events and the API contracts of a personalization platform.

What JSON Schema is

JSON Schema is a JSON document that describes what another JSON document must look like. The standard is maintained by the JSON Schema Foundation, and the current version is Draft 2020-12.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["item_id", "event", "timestamp"],
  "properties": {
    "item_id":   { "type": "string" },
    "event":     { "type": "string", "enum": ["view_item", "add_to_cart", "purchase"] },
    "timestamp": { "type": "integer", "description": "Unix timestamp in milliseconds" },
    "price":     { "type": "number", "minimum": 0 }
  }
}

That schema says unambiguously: the object must carry item_id, event and timestamp; the value of event comes only from the list; price is a non-negative number. Any JSON validator checks incoming data against it in a fraction of a second.

Use in e-commerce integrations

Validating a product feed

For personalization platforms the product feed is a critical data source. A typical feed schema covers:

Field	Type	Required
`id`	string	Yes
`title`	string	Yes
`price`	number	Yes
`availability`	enum: in_stock / out_of_stock	Yes
`category_path`	array of strings	Recommended
`images`	array of URLs	Recommended

Validating the feed against the schema before loading catches problems such as empty id values, negative prices or missing mandatory fields before they affect recommendation quality.

The event data contract

Every analytics event — view, click, purchase — is described by its own schema. That protects against accidental changes in frontend code: if a developer renames item_id to product_id, the CI pipeline raises a validation error immediately.

Tip: keep event schemas in the repository next to the integration code. When the platform updates an event format, update the schema in the same pull request. That removes silent contract breaks.

Validation tools

ajv (Node.js) — the fastest validator, supporting every current draft of the standard
jsonschema (Python) — the standard choice for Python feed-processing pipelines
Swagger / OpenAPI — uses JSON Schema as the basis for describing REST APIs; IDE plugins give inline validation
Postman / Bruno — built-in schema checks on responses inside API tests

Frequently asked questions

Why bother with a schema when the developers already know the format?

A schema is a machine-readable contract. It validates data automatically without manual checks, generates documentation, produces mock responses for testing and surfaces mismatches the moment an API changes.

How does JSON Schema help when integrating a personalization platform?

The platform publishes the expected schema for events (view_item, add_to_cart, purchase) and for the product feed. The store's developers can run their own data through a validator before deploying and confirm that required fields are present, types are correct and formats match.

Which tools work with JSON Schema?

Swagger and OpenAPI use JSON Schema to describe APIs. Postman supports schema validation of responses. In CI/CD, product feed validation is wired in through ajv (Node.js) or jsonschema (Python) — that catches errors before invalid data reaches production.