How-to › Describe your API

How to publish a semantic model as JSON beside your OpenAPI spec#

Write the apidef model of your OpenAPI document to model.json beside it, stamp the spec hash and extractor release, and fail CI when the two files stop matching.

Audience
API producer
Level
beginner
Topic
Extract a semantic model from a spec
Languages
TypeScript
Verified

Read first: Classify OpenAPI operations into CRUD kinds by path shape, Handle endpoints that do not map to an entity

Your docs builder, an agent’s tool loader, and a downstream generator each read your OpenAPI document and work out its entities for themselves. They work them out with different code, so the docs list trail_forecast while an SDK built on a later extractor exposes forecast. No file says which document, or which extractor, any of them read.

What you get

You will end up with model.json published beside openapi.json, stamped with the spec’s hash and the extractor release, and a CI check that fails when they drift. This is for you if several tools consume a model of your API.

Short answer

Run @voxgig/apidef as a library, pinned in a lockfile, and write res.apimodel.main.kit to model.json with the sha256 of the spec bytes and the extractor release beside it. Publish it in the same directory as openapi.json, so one URL prefix serves both. In CI, hash the published spec, compare it with the stamp, extract again, and fail on any difference, because nothing else regenerates the model.

You will need

Node 22 or later, an OpenAPI 3 document, and a static host that already serves your spec. The sample pins apidef 8.32.4, the release that the ~8.32.3 range in a @voxgig/create-sdkgen 0.31.9 scaffold resolves to, and installs 8.33.1 beside it under an alias. The document is api/openapi.json, a small trails API with six operations.

Approaches compared

ApproachWhen it fitsWhat it costs youWhen to pick something else
@voxgig/apidef model JSONSeveral consumers want entities, operation kinds, field types and flows from one fileA second artifact to publish, a check that keeps it matched, and an extractor to pinOne consumer reads the spec, and it already parses operations
Hey API output.sourceYour TypeScript SDK should ship with the document it was generated fromThe copy is the parsed document, so its bytes and hash differ from the published specConsumers need entities rather than operations
openapi-typescript and openapi-fetchEach TypeScript consumer derives types from the spec and calls by pathEvery consumer infers for itself, and --check guards only the copy it ownsSeveral tools need one shared reading of the API
Publishing only the OpenAPI documentYour consumers are generators that read OpenAPI nativelyEach consumer re-derives the model, and two readings can name one thing twiceDocs, agents and generators disagree about entity names
The Smithy JSON ASTYou author the model first and generate OpenAPI from itYou re-author the API in Smithy, and an existing OpenAPI document stops being the sourceYour OpenAPI document is the contract and stays hand-written

Voxgig maintains apidef, the extractor on this page. The other four rows are not Voxgig’s.

Publishing only the spec costs nothing to keep current, and it leaves the inference to every reader. A published model removes that duplication and adds an artifact that can go stale. Smithy has no inference step to drift, because its JSON AST serializes the authored model rather than an extraction,1 and its documentation covers converting Smithy to OpenAPI. The price is moving your source of truth into Smithy.

Publish the model and the spec in one step

publish.mjs reads the spec once, builds the model with apidef’s file-writing step switched off, and writes both files into one directory. The programmatic API documents ApiDef.makeBuild and the generate: false step flag the extraction uses.

/** Write openapi.json and model.json side by side in one directory: one URL prefix, two files. */
export async function publish(specPath, outDir, release = PINNED) {
  const spec = resolve(specPath)
  const out = resolve(outDir)
  const bytes = readFileSync(spec)
  const kit = await extract(spec, release)
  mkdirSync(out, { recursive: true })
  // The spec is copied byte for byte. The hash in model.json is the hash of these bytes.
  writeFileSync(join(out, 'openapi.json'), bytes)
  const published = envelope(bytes, kit, release)
  writeFileSync(join(out, 'model.json'), serialize(published))
  return published
}
node publish.mjs api/openapi.json site/apis/park-trails/v2
site/apis/park-trails/v2/openapi.json  Park Trails API 2.3.0, sha256 71efdb6a2e6f9438
site/apis/park-trails/v2/model.json    2 entities, 6 operations, 9 fields, 2 flows, @voxgig/apidef 8.32.4

Upload site/ as it is. The model’s address is the spec’s address with the filename changed, and the v2 directory keeps that address stable across the minor releases of the API. The model itself holds no spec hash and no extractor version, so envelope adds both beside it.

  "spec": {
    "file": "openapi.json",
    "openapi": "3.0.3",
    "sha256": "71efdb6a2e6f9438a00fba46d658fac4c5e95ae66c18aba5160744080892c15c",
    "title": "Park Trails API",
    "version": "2.3.0"
  }
}

Keys are sorted before writing, and the model carries no clock time and no path, so two runs write the same bytes. A test publishes twice and compares both with the committed file.

Read what the model carries from its URL

consume.mjs serves site/ on a loopback port, fetches both files the way a docs builder would, and checks the hash before it trusts the model.

node consume.mjs
GET /apis/park-trails/v2/model.json    200 application/json
GET /apis/park-trails/v2/openapi.json  200 application/json
the spec beside the model has the hash the model records: yes
Park Trails API 2.3.0, extracted by @voxgig/apidef 8.32.4
trail
  create  POST   /v1/trails
  list    GET    /v1/trails
  load    GET    /v1/trails/{trailId}
  remove  DELETE /v1/trails/{trailId}
  update  PUT    /v1/trails/{trailId}
  fields  difficulty string required, id string required, length_km number, name string required, open boolean, updated_at string date-time
trail_forecast
  list    GET    /v1/forecast
  fields  date string date, rain_mm number, summary string
flow BasicTrailFlow: create list update load remove list
flow BasicTrailForecastFlow: list
enum values in the spec: easy, moderate, hard; 0 of 3 in the model
operationIds in the spec: 6; 0 of 6 in the model

Entity names, operation kinds, field types and flow steps are all in the file, which is what a reader of it needs. The last two lines are what it lacks. difficulty reads as a plain string, because the model keeps no enum value, and no operation keeps its operationId. Tests check both on 8.32.4 and 8.33.1. A consumer that needs either reads the spec at the sibling URL, and the hash proves it is the same document.

Fail the build when the hash no longer matches

check.mjs reads the published directory rather than the repository, because the pitfall is a spec that reached the host without its model.

  const problems = []
  const stamp = published?.spec?.sha256
  const actual = sha256(specBytes)
  if (typeof stamp !== 'string') problems.push('model.json records no spec hash')
  else if (stamp !== actual) problems.push(`spec hash: model.json records ${stamp.slice(0, 16)}, openapi.json is ${actual.slice(0, 16)}`)
  const by = published?.extractor
  if (by?.name !== '@voxgig/apidef' || by?.version !== release) {
    problems.push(`extractor: model.json was written by ${by?.name} ${by?.version}, this check runs @voxgig/apidef ${release}`)
  }
  if (Object.keys(published?.model?.entity ?? {}).length === 0) problems.push('model.json holds no entities')
  // Extract again from the published bytes and compare the whole file, not one projection of it.
  const fresh = envelope(specBytes, await extract(join(at, 'openapi.json'), release), release)
  const changes = serialize(fresh) === text ? [] : diffPaths(published, JSON.parse(serialize(fresh)))
  if (changes.length) problems.push(`model.json differs from a fresh extraction at ${changes.length} path${changes.length === 1 ? '' : 's'}`)
  return { problems, changes }
}

pitfall.mjs copies the site to a scratch directory, puts release 2.4.0 of the spec over openapi.json the way an API build would, and leaves model.json alone.

node pitfall.mjs
the API build published openapi.json 2.4.0 over 2.3.0 and left model.json alone
check: fail
  spec hash: model.json records 71efdb6a2e6f9438, openapi.json is b7fd762413cbf256
  model.json differs from a fresh extraction at 5 paths
    + .model.entity.trail_closure
    + .model.flow.BasicTrailClosureFlow
    ~ .model.info.version
    ~ .spec.sha256
    ~ .spec.version
after node publish.mjs on the same spec, check: pass

The hash line catches the drift, and the path list says what a reader of the stale model misses: the closures entity that 2.4.0 adds. Run node check.mjs on the directory your deploy step uploads, so it reads the bytes the host receives.

Check it worked

Sixteen tests with the Node test runner pin the behavior. They cover the committed site, the stale spec, a reformatted spec, the extractor bump, and a hand edit to the model. Others feed malformed input, check an empty model on both releases, and probe the loopback host.

node --test publish.test.mjs
1..16
# tests 16
# suites 0
# pass 16
# fail 0
# cancelled 0
# skipped 0
# todo 0

Look for # pass 16. The hand-edit test changes one field type and keeps the hash, and the check still fails at .model.entity.trail.fields.length_km.t.

When it goes wrong

The check fails after a dependency update and the spec has not changed. A lockfile bump moved the extractor, and the model it writes is different. Run the check with the release installed beside the pinned one:

node check.mjs site/apis/park-trails/v2 --release 8.33.1; echo "exit $?"
site/apis/park-trails/v2: model.json is stale
  extractor: model.json was written by @voxgig/apidef 8.32.4, this check runs @voxgig/apidef 8.33.1
  model.json differs from a fresh extraction at 5 paths
    ~ .extractor.version
    + .model.entity.forecast
    - .model.entity.trail_forecast
    + .model.flow.BasicForecastFlow
    - .model.flow.BasicTrailForecastFlow
run node publish.mjs on the spec you publish, and publish both files together
exit 1

The diff covers the whole file, and a test that renames the entity in the 8.32.4 model gets the 8.33.1 model byte for byte. Every consumer that reads entity.trail_forecast loses it. record.sh ran the SDK Catalog’s Open-Meteo document on both releases, and 8.33.1 renamed weather_forecast to forecast there, with no other change to the model. Regression testing model extraction in CI traces the rule behind the rename. Treat the bump as an API change, and publish under a fresh version directory.

The hash fails after a formatter ran on the spec. The hash is over bytes, so a reformatted document with the same meaning fails, and a test pins that case. Run publish.mjs after the formatter.

The check passes on a document with no paths. extract refuses a model with no entities, because apidef reports success for a document cut short after "paths": .

Publish types or a source copy with openapi-typescript and Hey API

Neither generator writes a model file beside its output. A team on openapi-typescript publishes only the spec, and each consumer runs the generator. Its --check flag is the same guard applied to the consumer’s copy, and record.sh ran it against the 2.4.0 spec.

grep -A5 'openapi.next.json' records/openapi-typescript.txt
$ openapi-typescript openapi.next.json -o types/schema.d.ts --check
openapi-typescript 7.13.0
x Generated types are not up-to-date!
exit 1
types/schema.d.ts left unchanged by --check: yes
enum values in types/schema.d.ts: Difficulty: "easy" | "moderate" | "hard";

The types keep the three enum values that apidef’s model drops. They group operations by path rather than by entity, so openapi-fetch calls each one by method and path.

Hey API’s output.source: true writes source.json into the client folder, which its documentation describes as a copy of the input to keep beside the generated files.

cat records/hey-api.txt
@hey-api/openapi-ts 0.99.0, typescript 5.9.3
$ openapi-ts -f source.config.mjs
  top-level files: client.gen.ts index.ts sdk.gen.ts source.json types.gen.ts
  sha256 71efdb6a2e6f9438 openapi.json, 0bf1bdbc843c05de hey/source.json: different bytes
  same JSON value: no; schemas added: TrailWritable
$ openapi-ts -f source-rw-off.config.mjs
  top-level files: client.gen.ts index.ts sdk.gen.ts source.json types.gen.ts
  sha256 71efdb6a2e6f9438 openapi.json, 0ae6122b74190aa1 hey-rw-off/source.json: different bytes
  same JSON value: yes; schemas added: none

The copy is the document after Hey API’s parser ran. Its default read-write transform added TrailWritable, and with that transform off the value matched but the bytes did not, so a published hash of openapi.json never matches source.json.

When not to do this

Do not publish apidef’s model when one consumer reads it. The spec already serves that reader, and the model is a second file with a check of its own.

Do not publish a model file that no CI step regenerates or checks. A committed model.json describes the spec of the day it was written, and the host serves it beside every later spec.

A team that can author the model first does better with Smithy, since its JSON AST serializes the source and no extractor release sits between the two. openapi-typescript suits a TypeScript-only audience that calls the API by path, where the spec is the only artifact. Hey API fits when the SDK should ship with the parsed document that built it.

Last verified

Verified 2026-11-22 against Node 22.23.5 and @voxgig/apidef 8.32.4 and 8.33.1, which the captured commands run. record.sh ran openapi-typescript 7.13.0 and @hey-api/openapi-ts 0.99.0 with TypeScript 5.9.3, and apidef on the Open-Meteo document fetched at a fixed commit. Smithy was not run in this sandbox, so its row rests on the JSON AST and smithy-build pages of its documentation.

Footnotes

  1. Smithy reaches a single JSON file by another road. Its smithy-build reference lists the model plugin among three that are always run in every non-abstract projection, and that plugin serializes a self-contained and filtered version of the model as a single file. The JSON AST page calls the JSON form isomorphic to the IDL, so no extraction stands between the file and the source. ↩︎ Back to text

Read this page as markdown · All how-to guides

Generate the client instead of writing it#

Retries, timeouts, pagination and auth are the same problems in every client. Voxgig generates them from your OpenAPI description, in 23 languages, from one model.

Listen to Fireside, the Voxgig podcast

Since 2018, Richard Rodger has talked with developer advocates, event organizers, and the people who build developer-facing companies about the specifics of the work.