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
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
| @voxgig/apidef model JSON | Several consumers want entities, operation kinds, field types and flows from one file | A second artifact to publish, a check that keeps it matched, and an extractor to pin | One consumer reads the spec, and it already parses operations |
| Hey API output.source | Your TypeScript SDK should ship with the document it was generated from | The copy is the parsed document, so its bytes and hash differ from the published spec | Consumers need entities rather than operations |
| openapi-typescript and openapi-fetch | Each TypeScript consumer derives types from the spec and calls by path | Every consumer infers for itself, and --check guards only the copy it owns | Several tools need one shared reading of the API |
| Publishing only the OpenAPI document | Your consumers are generators that read OpenAPI natively | Each consumer re-derives the model, and two readings can name one thing twice | Docs, agents and generators disagree about entity names |
| The Smithy JSON AST | You author the model first and generate OpenAPI from it | You re-author the API in Smithy, and an existing OpenAPI document stops being the source | Your 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.
Related how-tos
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
-
Smithy reaches a single JSON file by another road. Its
smithy-buildreference 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