Schemas
What Is an API Schema? A Practical Guide to Request and Response Contracts
What an API schema constrains in a JSON message, how OpenAPI 3.1 relates to JSON Schema, and which decisions the schema file does not make.
SchemaVela
Independent notes on API schemas, data contracts, versioning, webhooks, and the tests that keep integrations compatible.
SchemaVela is a desk for people who design or consume HTTP APIs: backend and integration engineers, platform engineers, and technical product managers. Each note separates the schema of a message from the behavior around it, and says which document a factual claim comes from. This is not a product site. There is no client list, and there is no claim of a long archive before the first set of notes.
-
Schema
Fields, types, and which names have to be present in a message.
-
Behavior
Status codes, errors, retries, and effects a schema file does not state.
-
Checks
Validation and tests that compare a real message with the published contract.
Topic areas
The sections below are the subject index. A note lives in one section. Related questions are linked from the text, not repeated as a second copy of the same article.
-
Schemas
What a schema states about a message, and which rules it leaves unstated.
-
API contracts
Where a contract is more than the schema: behavior, compatibility, and client migration.
-
Versioning
How a publisher signals a compatible addition and an incompatible break.
-
Webhooks
Event envelopes, retries, signatures, and the receiver that must tolerate duplicates.
-
Integration design
Boundaries, error bodies, and the mapping between two schemas.
-
Testing
Schema checks, contract tests, and the cases that still need a joined run.
Featured guides
Start here if you are deciding what a contract should promise. The full set is listed with the current notes.
-
-
Versioning
API Contract Versioning: How to Avoid Breaking Integrations
How to record a compatibility promise with SemVer, OpenAPI document versions, and URL or media-type signals, without pretending one of them is required by HTTP.
-
Contracts
Backward Compatibility in APIs: Fields, Enums, and Behavioral Changes
How to tell a compatible API change from a breaking one, using JSON Schema keywords and Google's AIP-180 as a published guide rather than a universal law.
-
Webhooks
Webhook Payload Design: Structure, Versioning, and Reliability
How to shape a webhook payload using CloudEvents and the Standard Webhooks specification, including identity, signatures, duplicates, and retries.
All current notes
Notes that share a publication date are listed alphabetically. This set was published together.
-
Versioning
API Contract Versioning: How to Avoid Breaking Integrations
How to record a compatibility promise with SemVer, OpenAPI document versions, and URL or media-type signals, without pretending one of them is required by HTTP.
-
Integration
API Error Models: Designing Errors That Integrators Can Actually Use
How RFC 9457 structures an HTTP error body, which parts a program can rely on, and how to change an error contract without stranding clients.
-
Contracts
Backward Compatibility in APIs: Fields, Enums, and Behavioral Changes
How to tell a compatible API change from a breaking one, using JSON Schema keywords and Google's AIP-180 as a published guide rather than a universal law.
-
Testing
Contract Testing vs Integration Testing: Where Each One Fits
How Pact defines a contract test, how that differs from schema validation and from a joined integration run, and which bugs each one can and cannot show.
-
Contracts
How to Migrate an API Contract Without Breaking Existing Clients
A three-phase sequence, expand then migrate then contract, for changing an API contract while old clients keep working, with rollback called out as its own case.
-
Schemas
Schema Validation in API Integrations: What to Validate and When
Where schema validation belongs in an integration, what JSON Schema Draft 2020-12 actually checks, and how schema drift shows up without a fake metric.
-
Webhooks
Webhook Payload Design: Structure, Versioning, and Reliability
How to shape a webhook payload using CloudEvents and the Standard Webhooks specification, including identity, signatures, duplicates, and retries.
-
Schemas
What Is an API Schema? A Practical Guide to Request and Response Contracts
What an API schema constrains in a JSON message, how OpenAPI 3.1 relates to JSON Schema, and which decisions the schema file does not make.
Checklists
These are working lists inside the notes. They are editorial review aids, not measurements of how often a change breaks a client.
-
Check
Field checklist
Required names, unknown fields, enums, and null before a schema is published.
-
Check
Compatibility checklist
A review list for fields, enums, and behavior inside one major version.
-
Check
Webhook receiver checklist
Identity, signature, duplicates, and the response a sender will retry.
-
Check
Where to validate
Producer, consumer, and the CI check, plus what a passing schema still misses.
-
Check
Which test to run
When a contract test is the right evidence, and when a joined run is still required.
-
Check
Migration sequence
Expand, migrate, and contract, and what to do if clients have not moved.
How these notes are written
Scope
The opening paragraph says what the note covers. It does not imply a result the page cannot show.
Table
A specification rule and an editorial reading stay in different columns. An empty cell is not a measurement.
Sources
A factual claim names its document. Illustrations are labeled as illustrations. The rules are on the editorial policy, and changes to a published fact go on corrections.