API Design

Schemas

Schemas are reusable data structures that model the objects your API works with — a User, a CreateOrderRequest, a shared ErrorResponse. Define a structure once as a schema and reference it from every request body and response that needs it, instead of repeating the definition. Because schemas are standard JSON Schema, what you define here exports cleanly to OpenAPI and is understood by code generators, validators, and your mock server.

Schema kinds

Every schema has one of four structural kinds:

Kind What it models
Object A structured object with named properties — the most common kind.
Primitive A string, integer, number, or boolean — optionally with an enum.
Array An ordered list of items.
Composition A schema built from other schemas with allOf, oneOf, or anyOf.

You can switch a schema's kind at any time from the kind selector in the editor. If the switch would hide existing data — properties, enum values, composition members — Routebase warns you first, and offers to restore the previous state if you switch back.

A schema editor showing properties and required fields

Creating a schema

  1. Open the Schemas subsection under Components in the sidebar and click +.
  2. Give the schema a Name — PascalCase, e.g. User, CreateUserRequest, ErrorResponse — and an optional Description.
  3. Click Create, then define the structure in the editor.

While you type the name, Routebase checks for similar existing schemas. If a likely duplicate is found — matched on name and shared properties, with a percentage score — an alert offers three ways out: Use This (jump to the existing schema), View Diff (compare the two side by side), or Create Anyway.

Use Duplicate from a schema's … menu to start from an existing schema when two structures are similar; double-click a schema in the list to rename it.

Editing properties (object schemas)

Object schemas are edited in a Properties table. Each property has:

  • A Name and a Description.
  • A Type — string, integer, number, boolean, array, object, or a reference to another schema. The type field autocompletes both: type a primitive name, or switch to the Reference tab to pick a schema. Array properties additionally get an Items Type, which can itself reference a schema.
  • An optional Format (email, date-time, uuid, …) and, for enum-capable types, an enum value editor.
  • A Required toggle.

Naming and explaining enum values

An enum value like PARTIALLY_FULFILLED carries its meaning only for the person who invented it. Each value can therefore also get a display label and a description, both optional.

They travel with the spec rather than living only in Routebase: labels are exported as x-enumNames, descriptions as x-enumDescriptions, and the codegen-friendly x-enum-varnames is preserved on import. Your published documentation and portal show them next to the raw values, and generators that understand these extensions — NSwag among them — turn the labels into named constants instead of bare strings.

Structure the table the way you structure your data: nested object properties expand into indented child rows (up to three levels deep), rows can be dragged to reorder or to nest a property into an object, and the right-click menu offers move, insert, nest, and delete operations.

Primitive, array, and composition editors

  • Primitive schemas get a type and format selector, an enum editor, and validation constraints — length limits and regex pattern for strings, minimum/maximum and multiple-of for numbers.
  • Array schemas define their item type (primitive or schema reference) plus item-count and uniqueness constraints.
  • Composition schemas choose an Operator — allOf (all of these must match), oneOf (exactly one matches), or anyOf (one or more match) — and combine members that are either references to other schemas or inline JSON Schema fragments. For oneOf/anyOf, a discriminator editor maps a property value to the matching member schema.

Examples

The example panel below the properties table generates a realistic sample JSON payload from the schema — optional properties are dimmed so readers can tell them apart. Copy it, or regenerate it after structural changes.

Where a schema is used

Referencing one schema from many places keeps your API consistent: change the User shape once and every endpoint that returns a user updates with it. Routebase shows a usage count on each schema in the list ("Referenced by N endpoints") and a Used by section in the editor that lists every reference — endpoints (with method, path, and where in the contract the schema appears), other schemas that reference it, and reusable components built on it. Click any entry to jump there. This is handy for spotting unused definitions or gauging the blast radius of a change before you make it.

The schema list with usage counts

Referencing and extracting

Schemas are referenced from request bodies, responses, and array/property types. The fastest ways to connect them:

  • Drag a schema from the sidebar onto a response or request body to link it as the body structure.
  • Autocomplete a property's type and pick a schema from the Reference tab.
  • Extract Schema to Component on an inline body turns an ad-hoc structure into a named schema and re-links the endpoint to it.

Sharing across projects

A schema that several projects depend on — a company-wide ErrorResponse envelope or Money type — can be promoted via Promote to Library, making it available across projects so teams build on the same definitions. Linked library schemas carry an Org or Project badge, show an update indicator when the library version moves ahead, and can accept the update or be unlinked at any time. See Shared library.

Deleting a schema

Choose Delete from a schema's … menu. The dialog warns that endpoints referencing the schema will need to be updated and that the action cannot be undone — check the Used by section first.

Permissions

Creating and editing schemas requires specs:write; deleting requires specs:delete (Admins and Owners — the Delete action is hidden for Members). Promote to Library requires specs:write. On a published, locked version schemas are read-only.