# 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.

Source: https://voxgig.com/howto/publish-a-semantic-model-as-json

- Audience: api-producer
- Level: beginner
- Languages: typescript
- Verified: 2026-11-22
- Published: 2026-11-22

## 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](https://github.com/voxgig/apidef/blob/main/docs/reference/model.md) | 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](https://heyapi.dev/docs/openapi/typescript/configuration/output) | 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](https://openapi-ts.dev/cli) | 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](https://spec.openapis.org/oas/v3.0.3.html) | 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](https://smithy.io/2.0/spec/json-ast.html) | 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](https://smithy.io/2.0/guides/model-translations/converting-to-openapi.html).
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](https://github.com/voxgig/apidef/blob/main/docs/reference/api.md)
documents `ApiDef.makeBuild` and the `generate: false` step flag the extraction uses.

```js title="publish.mjs"
/** 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
}
```

```bash
node publish.mjs api/openapi.json site/apis/park-trails/v2
```

```text output
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.

```json title="site/apis/park-trails/v2/model.json"
  "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.

```bash
node consume.mjs
```

```text output
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.

```js title="check.mjs"
  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.

```bash
node pitfall.mjs
```

```text output
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](https://nodejs.org/api/test.html) 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.

```bash
node --test publish.test.mjs
```

```text output
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:

```bash
node check.mjs site/apis/park-trails/v2 --release 8.33.1; echo "exit $?"
```

```text output
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](/howto/regression-test-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](https://openapi-ts.dev/cli) is the
same guard applied to the consumer's copy, and `record.sh` ran it against the 2.4.0 spec.

```bash
grep -A5 'openapi.next.json' records/openapi-typescript.txt
```

```text output
$ 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`](https://openapi-ts.dev/openapi-fetch/api) 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.

```bash
cat records/hey-api.txt
```

```text output
@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](https://heyapi.dev/docs/openapi/typescript/configuration/parser) 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

- [Classify OpenAPI operations into CRUD kinds by path shape](/howto/classify-openapi-operations-by-path-shape)

- [Handle endpoints that do not map to an entity](/howto/endpoints-that-map-to-no-entity)

- [Diff two semantic models from successive spec versions](/howto/diff-two-semantic-models-across-versions)

- [Regression test model extraction in CI](/howto/regression-test-model-extraction-in-ci)

- [Verify an SDK, CLI and MCP server share one model version](/howto/verify-surfaces-share-one-model-version)

- [Reconcile an extracted entity model with a domain model](/howto/reconcile-an-extracted-model-with-a-domain-model)

## 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.

[^1]: Smithy reaches a single JSON file by another road. Its
[`smithy-build` reference](https://smithy.io/2.0/guides/smithy-build-json.html) 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](https://smithy.io/2.0/spec/json-ast.html) calls the JSON form isomorphic to the
IDL, so no extraction stands between the file and the source.