How-to › Model, configure and generate

How to split an application model into entity and service files#

Give each entity, service, message set and environment its own @voxgig/model file, unify them into one model.json, and read the error a field typed twice produces.

Audience
Platform team
Level
beginner
Topic
Model an application and generate from it
Verified

Every team edits one model file, so every pull request touches it and every review reads all of it. The billing team types the order total as text, the orders team types it as an integer, and both edits sit hundreds of lines apart. Nobody can say which team owns which line.

What you get

You will end up with one file per entity, service, message set and environment, unified into one model.json. The build refuses a field that two files type differently. This is for you if several teams own parts of one model.

Short answer

Write each entity, service, message set and environment of an @voxgig/model model in its own aontu file, and include them all from one root file. voxgig-model unifies the files into one model.json with sorted keys, the same unified model it hands to each action. A field given two types in two files stops the build with an error that names both files.

You will need

Node 22 or later, and npm ci in the sample directory, which installs @voxgig/model and pino, its logger. The install prints EBADENGINE warnings on Node 22, because aontu declares Node 24. The model files use the .aontu extension, which the release here reads. An include of a .aon file, the extension the create-system scaffold writes, fails with include not readable: ./part.aon (extension: .aon). This page uses aontu’s include syntax and nothing else of the language.

Approaches compared

ApproachWhen it fitsWhat it costs youWhen to pick something else
@voxgig/modelEntities, services, messages and environments in one model that your own actions readA root include list that every added file edits, and a unified file to readYour teams describe HTTP APIs and want a client generated from them
Backstage software catalogEach service repository describes itself for a portalIt catalogs components and their relations, not their fields, so code is generated from elsewhereYou generate code, which needs the fields themselves
FernAn existing Fern Definition split into files that import each other’s typesOne type name per definition, and generation runs on Fern’s cloud or a local containerYour model is not an API, or you are new to Fern
JHipster JDLEntities and relationships for a JHipster applicationThe files are passed together to one command, and JHipster writes the applicationYour stack is not JHipster
orvalAn OpenAPI document split with external $ref files, and a TypeScript clientExternal refs need an allow list, and a field typed twice becomes never silentlyYou want a conflicting field refused before code is written
SmithyServices described in shapes across many files and namespacesA modeling language your teams learn, and shapes repeated across files must match member for memberYour model is entities and environments, not service shapes

Voxgig maintains @voxgig/model, the subject of this page. Backstage, Fern, JHipster, orval and Smithy are maintained elsewhere, and only Fern and orval were run here.

All six accept a model split by file. What differs is what happens when two files disagree: the model and Smithy refuse it, Fern refuses a repeated name, and orval writes the disagreement into a type. Backstage keeps each file as an entity of its own, and an entity’s name must be unique per kind within its namespace, so two teams cannot declare one service twice there.

Give each part its own file

The root file holds only includes. Each included file writes its declarations at their full path, so a reviewer of entity/order.aontu can see where every line lands without opening another file.

# The root file. It holds no declarations of its own: each include is one file that one
# team owns, and voxgig-model unifies them into model.json.
@"./field.aontu"
@"./entity/customer.aontu"
@"./entity/order.aontu"
@"./msg/order.aontu"
@"./srv/orders.aontu"
@"./env/local.aontu"
@"./env/prod.aontu"

The shared shape of a field lives in one file, and each entity narrows it per field.

# Owned by the orders team.
main: ent: order: field: {
  id:       $.shape.field & { kind: 'int', required: true }
  customer: $.shape.field & { kind: 'int', required: true }
  total:    $.shape.field & { kind: 'int', required: true }
  paid:     $.shape.field & { kind: 'bool' }
}

Services, messages and environments follow the same rule, one file each.

# The orders service: which messages it answers and what it needs to run.
main: srv: orders: {
  in: 'aim:order'
  port: *8080 | number
}

Unify the files into model.json

Build the root file. The sample’s script runs voxgig-model model/model.aontu -g warn on a scratch copy and compares the result with the committed model/model.json.

node build.mjs
voxgig-model model/model.aontu, on a scratch copy
  model.json: 1511 bytes, keys sorted: true, trailing newline: false
  top-level keys: main, shape
  main: ent, env, msg, srv
  identical to the committed model/model.json: true

The keys are sorted, so the order fields come out as customer, id, paid, total whatever order the source used. The file ends without a newline, which matters to a tool that compares it byte for byte. The helper shape key is in the output too, beside main.

Read model.json as the thing generated from

A generator never sees the seven files. An action receives the unified model, and a tool outside the model reads model.json. Read that file when you review a change, and use the split to find who owns each part. The script builds each include on its own, beside field.aontu, and matches what it declares against the whole model.

node read-model.mjs
declaration in model.json  declared in
main.ent.customer          model/entity/customer.aontu
main.ent.order             model/entity/order.aontu
main.env.local             model/env/local.aontu
main.env.prod              model/env/prod.aontu
main.msg.aim.order.create  model/msg/order.aontu
main.msg.aim.order.load    model/msg/order.aontu
main.srv.orders            model/srv/orders.aontu

The script fails if a declaration comes from two files or from none, so the table can serve as an ownership check in CI. The same model written as one file builds to the same bytes, which the test asserts.

Check it worked

Run the test. It rebuilds the model, checks the ownership table, a part with the wrong extension, the pitfall in the next section, the merges, and what the Fern and orval runs recorded.

node --test split.test.mjs
1..7
# tests 7
# suites 0
# pass 7
# fail 0
# cancelled 0
# skipped 0
# todo 0
# duration_ms 7458.522954

Split the same model with Fern and orval

A team that keeps its API in Fern’s own format, the Fern Definition, splits it into files that import each other. A team on orval splits its OpenAPI document with external $ref files. Both were run on the order types, with the billing team declaring its own Order in a second file.

node others.mjs
fern-api 5.227.0
fern.config.json names 5.227.0
fern --version in the project: 5.227.0
== as committed: Order in order.yml and in billing.yml
exit 1
[sdk] 1 error
    [error]
        path: order.yml -> types -> Order
        issue: Order is already declared in billing.yml

Found 1 error and 0 warnings in N seconds.
For guidance, run `fern instructions spec`.
== billing.yml declares BillingOrder instead
exit 0
All checks passed

orval 8.48.0
flags only: exit 1, generated/flags.ts written: no
External $ref targets are not allowed by default.
orval.config.mjs: exit 0, generated/shop.ts written: yes
  export type LoadOrder200 = {
    id: number;
    customer: number;
    total: number;
    paid?: boolean;
  } & {
    total?: string;
  };
typescript 5.9.3
tsc --strict check.ts: exit 2
check.ts(5,58): error TS2322: Type 'number' is not assignable to type 'never'.

fern check ran offline with no account, as the release the project’s fern.config.json names, and refused a type name declared in two files, although the imports page writes imported types with a file prefix. Renaming one type passed. The same page says Fern does not recommend the Fern Definition to new customers and keeps it supported for existing users. Fern’s generation, which runs on Fern’s cloud by default or in Docker or Podman with --local, was not run. The recording sets FERN_DISABLE_TELEMETRY=true, the variable the CLI reads before it reports usage.

orval refuses external refs until input.parserOptions.externalRefs.allow lists them. Its documentation advises listing specific documents, and the sample allows '*'.1 With refs allowed, the billing schema’s allOf became an intersection, so total is number & string, which TypeScript reduces to never. orval exited 0, and only the type check found it.

When it goes wrong

The billing team adds srv/billing.aontu, typing the order total as text. The build fails and writes nothing, and the error names the line in each file.

node pitfall.mjs
model/srv/billing.aontu: main: ent: order: field: total: { kind: 'text' }
  build ok: false, model.json unchanged: true
  [aontu/scalar_value]: Cannot unify values at path $.main.ent.order.field.total.kind

  Literal scalar values of the same kind can only unify if they are
  exactly equal.

  Examples:
    1 & 1   -> 1    # Does unify (equal Integers);
    a & a   -> a    # Does unify (equal Strings);
    1 & 2   -> nil  # Does not unify (unequal Integers);
    1 & 1.0 -> nil  # Does not unify (kinds: Integer & Float).

   Cannot unify value: "int" with value: "text"
    --> model/entity/order.aontu:5:37
    3 |   id:       $.shape.field & { kind: 'int', required: true }
    4 |   customer: $.shape.field & { kind: 'int', required: true }
    5 |   total:    $.shape.field & { kind: 'int', required: true }
                                            ^ value was: "int"
    6 |   paid:     $.shape.field & { kind: 'bool' }
    7 | }

   Cannot unify value: "text" with value: "int"
    --> model/srv/billing.aontu:1:41
    1 | main: ent: order: field: total: { kind: 'text' }
                                                ^ value was: "text"
    2 |
    3 |

model/srv/billing.aontu: main: ent: order: field: total: { required: 'yes' }
  build ok: false, model.json unchanged: true
  [aontu/scalar_kind]: Cannot unify values at path $.main.ent.order.field.total.required

Read the path first, then the two --> lines: they are the two files to reconcile. Two strings that differ give scalar_value, and a string against a boolean gives scalar_kind. The raw log also carries color codes, absolute paths and internal fields, so the script prints only the error’s msg field.

A change that adds a file collides in the root file. Two teams each adding an entity append an include to model.aontu, and git stops the merge there.

node merge.mjs
each team adds a field to its own entity file (split layout)
  merged cleanly
each team adds an entity file and its include (split layout)
  conflict in model/model.aontu: 2 lines between the markers
the same two entities, with the model in one file (single layout)
  conflict in model/model.aontu: 4 lines between the markers

Splitting shrank that conflict, and it did not remove it. Resolve it by keeping both include lines.

When not to do this

Do not split a model that one person maintains. Seven files and an include list cost review time and buy nothing until a second owner appears.

Do not treat the files as the model. @voxgig/model hands your actions the unified result, so review model.json beside the diff, or the effect of a one-line include stays invisible.

Choose Fern when you already keep a Fern Definition and want clients in several languages: the definition splits by file, and fern check refused the repeated type offline. Choose orval for a TypeScript client from an OpenAPI document split with $ref files, and put a strict type check in CI, since orval writes a contradiction without a warning. JHipster JDL also accepts several files at once, which suits a JHipster application better than a model it never reads.

Last verified

Verified 2026-11-22 against Node 22.23.5, @voxgig/model 12.0.2, the newest on npm, with aontu 0.76.3 and pino 10.4.0. fern-api 5.227.0, orval 8.48.0 and TypeScript 5.9.3 ran once, in record.sh, and their output is committed. Backstage, JHipster and Smithy were read from their documentation and not run.

Footnotes

  1. The input reference describes ['*'] as allowing every external reference, “the previous behavior”, so the refusal is a default that changed between releases rather than one orval always had. The same entry gives the reason: the document may be untrusted, and a $ref can name a local file or a remote URL. ↩︎ 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.