Masterbelt

masterbelt/masterbelt

JSON Export

Synced from main@9490864MarkdownSource

#JSON Export

The JSON exporter serialises an entire project's imported master data into one JSON document. Its on-disk shape is the canonical Masterbelt export format consumed by every codegen target's LoadJSON-shaped helper.

#Kind

The export-kind identifier is json.

#Configuration

A JSON export is configured under exports: in the project configuration file:

YAML
exports:
  - kind: json
    out: data/masterdata.json
  • kind selects this exporter.
  • out is the file system path the exporter writes to. Relative paths resolve against the project root. The exporter creates any missing parent directories.

No options keys are recognised at this stage; unknown keys are silently ignored to leave room for future extensions.

#Document Shape

The exporter writes one JSON object per run. Top-level keys are the masters' flat camelCased identifiers (the same name the per-target MasterData accessor uses). Values are arrays of record objects in importer-supplied order:

JSON
{
  "items": [
    {"count": 10, "id": 1, "name": "alpha"},
    {"count": 20, "id": 2, "name": "beta"}
  ],
  "userFriendships": [
    {"friend": 9, "owner": 7}
  ]
}
  • Top-level keys appear in the project's master-declaration order. A master that declared no source section appears with an empty array.
  • Per-record keys appear in lexicographic order so two records with the same field set always produce byte-identical encodings regardless of producer iteration order.
  • The exporter ends the file with a trailing newline.

A nested master master User { master Friendships { ... } } appears at the top level under its flattened-then-camelCased name (userFriendships) — no nested object layout is used.

#Value Encoding

Masterbelt valueJSON encoding
nullnull
booltrue / false
int whose abs value < 2^53JSON number (decimal digits)
int whose abs value >= 2^53JSON string (quoted decimal digits)
stringJSON string with standard escapes
list<T>JSON array, elements recursed
map<K, V>JSON object keyed by rendered key, entries sorted by key
nested productJSON object, keys sorted lexicographically

The safe-integer guard at 2^53 keeps the document round-trippable through JavaScript consumers. Loaders that promote those values back to a numeric type are free to detect the quoted form and parse it through a big-integer constructor; the exporter never emits a bigint JavaScript literal because plain JSON does not have one.

#Field Names

Per-record keys are the master's surface field names as written in Masterbelt source. Names are emitted verbatim; no case transformation is applied at the field level. A ref<T> field expands to the target master's primary-key fields under the surrounding field's name joined with _ (field_pk1, field_pk2, ...) before serialisation.

#Determinism

Two runs against the same input produce byte-identical output:

  • Top-level keys appear in master-declaration order.
  • Per-record keys are sorted lexicographically inside each object.
  • Map entries are sorted by their rendered key.
  • List elements preserve the producer's order (the producer's order is itself deterministic for every importer defined in import-csv.md and friends).

#Loader Contract

Every codegen target produces a LoadJSON / loadJSON / LoadJson helper that consumes this format and returns a fully wired MasterData. The per-target signatures and casing are defined in:

The format is the contract between the exporter and the loaders; changes to the document shape are coordinated through all three target specifications.

Specification