API Tools

JSON Schema and OpenAPI in one paragraph each

JSON Schema is a vocabulary for describing the shape of JSON data. A schema is itself a JSON document that lists the expected properties, their types, their formats, and the constraints they must satisfy — required fields, minimum and maximum values, regex patterns, enums, nested objects, arrays of a specific item type. Once you have a schema, you can validate any incoming JSON against it and get a precise list of what is wrong before any code touches the payload. Schemas are also self-describing: tools can read them to generate forms, mock data, type definitions, and human-readable documentation. The standard is published in numbered drafts, and the ones in common use are 4, 6, 7, 2019-09, and 2020-12; the validation keywords are stable enough that most schemas written in one draft work in any modern validator with minor adjustments. JSON Schema is the right tool whenever you need to describe data — a request body, an event payload, a configuration file, a database record — without committing to a specific transport.

OpenAPI is a vocabulary for describing an entire HTTP API. Where JSON Schema describes a single payload, OpenAPI describes endpoints, methods, parameters, request and response bodies, authentication, error formats, and the relationships between them. Internally, the request and response bodies in an OpenAPI document are themselves JSON Schemas — OpenAPI 3.1 is fully aligned with JSON Schema 2020-12 — so the two specifications nest cleanly. From an OpenAPI document you can generate client SDKs in any language, server stubs, interactive documentation, mock servers, and contract tests. Its cost is verbosity: a spec for a moderate API runs to hundreds of lines of YAML. The payoff is that every consumer — frontend, mobile, partner, internal service — works against the same source of truth, and breaking changes become detectable instead of accidental.

When to validate, when to generate, when to convert

Validate when you have data and want to confirm it matches a contract. The classic case is server-side input validation: a webhook arrives, you check it against the published schema before doing anything else, and you reject malformed payloads at the boundary instead of letting a typo crash a downstream service. Validation is also how you keep test fixtures honest — if a fixture stops matching the current schema, you find out at CI time rather than in production. Use the JSON Schema Validator for the data side; an API Validator for checking responses against an OpenAPI contract is planned.

Generate when you have an example and want to skip the typing. Most engineers can produce a representative JSON sample faster than they can author a complete schema by hand. The JSON to Schema Generator infers types, common formats, and array element shapes from a real payload, and lets you tighten the result before publishing. The same logic applies to mock data: from a schema, the Mock Data Generator produces realistic, locale-aware fixtures suitable for storybook screens, integration tests, or load testing without a backend.

Convert when an existing artifact is in the wrong shape. The Schema Converter turns JSON Schema, TypeScript interfaces, GraphQL types, or a JSON example into TypeScript, Zod, Pydantic, Go structs, GraphQL, or JSON Schema, so one definition can feed each layer of the stack. Review the output: recursive and cross-referencing schemas aren't ordered for Zod and Pydantic yet.

Versioning, breaking changes, and contract testing

APIs without versioning collapse the moment the first consumer ships. Once a client is in the wild, every field name, type, and required-ness becomes a public commitment. Removing a field, renaming it, tightening a constraint, or making an optional field required is a breaking change — and breaking changes shipped without warning are how mobile apps stop working overnight.

A workable versioning policy distinguishes three kinds of edits. Safe additions — a new optional field, a new endpoint, a new enum value where consumers tolerate unknowns — never break clients and can ship anytime. Warnings — deprecating a field, narrowing a type, changing default values — should be announced, dated, and shipped through a parallel version. Breaking changes — removing fields, changing types, changing required-ness, restructuring responses — require a major version bump and a deprecation window long enough for slow-moving consumers to migrate.

The Breaking Change Detector automates this triage. It compares two versions of a JSON Schema or OpenAPI spec and labels each change it finds: safe, warning, or breaking. For OpenAPI it compares the paths, methods, and component schemas. The output doubles as a changelog you can drop into release notes — and it catches the breaks that are easy to miss, like a field type that quietly shifted from integer to string because the producer started using a UUID.

Contract testing extends the same idea into CI. The producer's schema becomes a test fixture: every consumer's mock and every recorded request is replayed against the current spec, and any drift fails the build. Cheaper than discovering the drift in production.

Which API tool should you use?

If you receive JSON and need to confirm it is well-formed, use the JSON Schema Validator. Paste the schema and the payload, get a structured list of errors with the path to each failing value. Best when the schema already exists.

If you have JSON and need to produce the schema, use the JSON to Schema Generator. It infers types, formats, and required-ness from a real example, then lets you refine the inference with an interactive editor before exporting.

If you are designing an API, use the OpenAPI Editor. Write the spec in YAML or JSON, or start from a template, and see the documented endpoints update live beside it. Basic checks catch structural mistakes such as a missing info.version or an operation without responses as you type.

If you need realistic test data fast, use the Mock Data Generator. Point it at a JSON Schema, or an OpenAPI document's first component schema, and get seeded, locale-aware fake data — names, emails, addresses, dates — exportable as JSON or CSV. If you are preparing a release and need to know what changed, use the Breaking Change Detector to diff two versions of a spec, see each change it finds classified, and copy the result straight into your changelog.