Schemas & data models
Author shared data models, reuse them across endpoints, and validate runtime payloads.
Schemas describe the shape of your data — request bodies, response payloads, parameter values. OpenAPI Studio gives you a dedicated Schemas view for authoring shared models you can $ref from anywhere in the spec.
Schemas view
Open Schemas from the workspace navigation to see a list of every named schema in your spec (components.schemas). Click one to open its detail page with three tabs:
- Fields — visual schema builder for properties, types, constraints, descriptions.
- Example — author a sample payload, validate it against the schema, generate one from the schema.
- Samples — multiple named examples for richer docs.
Visual schema builder
Each property has:
- Name
- Type — string / integer / number / boolean / array / object / null
- Format — for strings (date, date-time, email, uuid, etc.)
- Required flag
- Constraints — min/max, pattern, enum, multipleOf
- Description — markdown supported
- Default value
- Nested schema — for objects and arrays, drill in
Composition keywords (oneOf, anyOf, allOf) are supported via the Compose menu.
Shared schemas vs inline
When you reference a shared schema from an endpoint’s request body or response, the editor shows:
- A “Used by N operations” badge so you know how many places break if you change it.
- An Open in Schemas link that jumps to the shared definition.
Inline schemas (defined directly on the operation) are fine for one-off shapes; shared schemas are better when the same shape repeats.
Examples
The Example tab provides:
- A textarea for the example payload (JSON).
- Generate from schema — produces a valid example matching the constraints.
- Validate — Ajv-backed validation that reports unknown properties, missing required fields, and constraint violations inline.
The first example on a request body schema seeds the Run tab body — so good examples mean less typing during testing.
Validation in the runner
If your operation declares a response schema (or references one), the Run tab validates real responses against it and surfaces violations next to the response viewer. Useful for catching contract drift as you iterate.
$ref and deref
$ref is preserved in the spec as-is — that’s the OpenAPI standard and what tooling expects. The editor and exporter dereference on demand for views that need the resolved shape (e.g. JSON Schema validation against a response).