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

Source: https://voxgig.com/howto/split-an-application-model-into-aon-files

- Audience: platform-team
- Level: beginner
- Verified: 2026-11-22
- Published: 2026-11-22

## 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](https://github.com/voxgig/model/blob/main/docs/reference.md) | 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](https://backstage.io/docs/features/software-catalog/descriptor-format/) | 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](https://buildwithfern.com/learn/api-definitions/ferndef/imports) | 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](https://www.jhipster.tech/jdl/getting-started/) | 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](https://orval.dev/docs/reference/configuration/input/) | 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](https://smithy.io/2.0/spec/model.html) | 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.

```aontu title="model/model.aontu"
# 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.

```aontu title="model/entity/order.aontu"
# 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.

```aontu title="model/srv/orders.aontu"
# 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`.

```bash
node build.mjs
```

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

```bash
node read-model.mjs
```

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

```bash
node --test split.test.mjs
```

```text output
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](https://buildwithfern.com/learn/api-definitions/ferndef/imports) 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.

```bash
node others.mjs
```

```text output
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](https://buildwithfern.com/learn/sdks/current/overview/how-it-works) by
default or in Docker or Podman with
[`--local`](https://buildwithfern.com/learn/cli-api-reference/cli-reference/sdk-commands), 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.

```bash
node pitfall.mjs
```

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

```bash
node merge.mjs
```

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

- [Emit TypeScript types and SQL from one application model](/howto/generate-typescript-types-and-sql-from-one-model)

- [Vet an aontu model for contradictions before you generate](/howto/vet-a-model-file-before-you-generate)

- [Explain why a unified config has a given value](/howto/explain-why-a-unified-config-value)

- [Add a custom generation action to an application model](/howto/add-a-generation-action-to-a-model)

- [Scaffold a service system from a model file](/howto/scaffold-a-service-system-from-a-model)

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

[^1]: The [input reference](https://orval.dev/docs/reference/configuration/input/) 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.