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
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
| @voxgig/model | Entities, services, messages and environments in one model that your own actions read | A root include list that every added file edits, and a unified file to read | Your teams describe HTTP APIs and want a client generated from them |
| Backstage software catalog | Each service repository describes itself for a portal | It catalogs components and their relations, not their fields, so code is generated from elsewhere | You generate code, which needs the fields themselves |
| Fern | An existing Fern Definition split into files that import each other’s types | One type name per definition, and generation runs on Fern’s cloud or a local container | Your model is not an API, or you are new to Fern |
| JHipster JDL | Entities and relationships for a JHipster application | The files are passed together to one command, and JHipster writes the application | Your stack is not JHipster |
| orval | An OpenAPI document split with external $ref files, and a TypeScript client | External refs need an allow list, and a field typed twice becomes never silently | You want a conflicting field refused before code is written |
| Smithy | Services described in shapes across many files and namespaces | A modeling language your teams learn, and shapes repeated across files must match member for member | Your 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.
Related how-tos
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
-
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$refcan name a local file or a remote URL. ↩︎ Back to text