Model Ledger (ModL) is a tool for managing the identity of a domain data model over time — tracking what exists, what changed, and what that means for the systems that consume it.

As a domain data model evolves, producers and consumers need stable answers to questions like:

• What concepts exist, and what do they mean?
• What changed between releases, and when?
• Has a change broken the data contract?
• What is the stable runtime address for a given model element?

ModL answers these by maintaining four normalized, append-only CSV tables — the ledger — co-released alongside the data model in a version-controlled repository. Records in the ledger are never deleted, only superseded. The git history provides point-in-time reproducibility.

ModL is language-agnostic. It does not parse model files directly. A language-specific adapter produces a diff report in modl's intermediate representation (IR), which is fed into modl along with the previous ledger state and a breaking change configuration.

flowchart LR
    A[Model snapshot] --> |Previous| DIFF[Model-specific diff]
    B[Model snapshot] --> |Current| DIFF
    DIFF --> |Diff report| ADAPTER[Intermediate Representation Adapter]
    ADAPTER --> |Diff in IR| SYNC
    LEDGER[Ledger] --> |Previous| SYNC
    F[Breaking change config] --> SYNC
    SYNC --> |Updated| LEDGER

The diff report describes changes using four element kinds:

ENTITY and PROPERTY cover the structural model. ENUMERATION_SET and ENUM_VALUE cover shared vocabulary — types, units, and code lists that properties reference. All four kinds receive concept URIs, revisions, and contracts in the ledger. Only PROPERTY concepts are runtime-addressable and therefore receive bindings.

graph TB
    E[ENTITY] --> |has property| P1[PROPERTY 1]
    E --> |has property| P2[PROPERTY 2]
    E --> |has property| PN[PROPERTY N]
    ES[ENUMERATION_SET] --> |has value| EV1[ENUM_VALUE 1]
    ES --> |has value| EV2[ENUM_VALUE 2]
    P1 -.->|references| ES

A Person that has a name and owns a Car

graph TB
    E[Person] --> |name| P1[String]
    E --> |ownsCar| P2[Car]

Notice that some properties can resolve to a primitive data type (e.g., name resolves to String), whereas others resolve to another entity (e.g., ownsCar resolves to Car). Hence, such a simple pattern resembles a graph when used systematically.

graph TB
    E[Person*] --> |name| P1[String]
    E --> |ownsCar| V[Vehicle*]
    V --> |speed| P3[Float]

* indicates that the element is an ENTITY.

A diff function (specific to the data modeling language and agnostic to ModL) must report changes to entities, properties, and vocabulary elements, indicating whether they were ADDED, REMOVED, or MODIFIED.

ModL tracks model identity across four dimensions. Namely: Concepts, Revisions, Contracts and Bindings. The following example, written in vspec, is used throughout:

Vehicle:  # This is an ENTITY
    type: branch

Vehicle.Speed:  # This is an PROPERTY
    type: sensor
    datatype: Float

Vehicle.Door:  # This is an ENTITY
    type: branch
    instances: [Left, Right]

Vehicle.Door.IsOpen:  # This is an PROPERTY
    type: sensor
    datatype: Boolean

A concept is the agreed meaning of a model element — what it is, independent of any implementation detail. Think of it as a dictionary entry.

Concepts are identified once and never reassigned. If a concept is renamed, the old label is recorded as a previous label — the concept identity does not change.

A revision is assigned to every detected change, regardless of whether it is breaking. It is the raw audit log of what happened.

Examples of changes that trigger a new revision:

• A typo fix (Vehicl → Vehicle)
• A unit change (km/h → mph)
• A description update
• A field being added or removed
• An instance list changing

A contract captures the specific data structure agreement between producers and consumers. It assigns identity to a concrete variant of the model that is relevant to the downstream users. What counts as "relevant" is user-defined via a configuration file. Any change to an essential attribute triggers a new contract. In other words, if a braking change is detected, a new contract identy is minted.

For example, if datatype is declared essential for Vehicle.Speed:

These are two contracts for the same concept — each a distinct variant of the essential metadata. The meaning of "speed" has not changed, but the data contract has.

Contracts apply to both entities and fields. An entity's essential metadata (e.g., its type or instance list) defines its contract just as a field's datatype defines its own. Each element's contract is governed independently by its own essential attribute configuration.

Bindings assign a stable identity to every runtime-addressable path a property can appear on.

For Vehicle.Door with instances: [Left, Right], the field Door.IsOpen expands into:

A system can then write a compact payload like 24: true to mean "the left door is open", without encoding the full path.

For a property whose parent entity has no instances (e.g., Battery.StateOfCharge), one binding is still minted with no instance label:

Note: Bindings are assigned to PROPERTY concepts only. ENTITY concepts are not directly addressable at runtime and therefore never receive bindings. Vocabulary kinds (ENUMERATION_SET, ENUM_VALUE) never receive bindings either. The engine reads the kind column of the concept row to enforce all three rules.

When instances change (e.g., Center is added), the behavior depends on the breaking change configuration for the entity:

In both cases, child property contracts are never changed by an instance-list delta — only bindings are affected. Existing binding IDs remain stable for continuing instances.

The table below shows which rows modl sync creates or updates for each type of change event, given the breaking-change classification configured by the user.

Key observations:

• Every event produces a revision — the revision log is unconditional and unfiltered.
• A contract is only created or superseded when a change is classified as breaking by the config. Non-breaking changes leave the active contract untouched.
• An instance-list change on an entity never creates or supersedes child property contracts — only bindings are affected. Added instances gain new bindings on the existing child contract; removed instances have their bindings marked REMOVED.
• A rename never changes the concept URI. It updates current_label and appends the old label to previous_labels in the concept row.
• ENUMERATION_SET and ENUM_VALUE events follow the same revision and contract rules as ENTITY and PROPERTY respectively, but never produce bindings regardless of configuration.

Each record minted is assigned a serial number — a monotonically increasing non-negative integer, never reused. The serial is permanently baked into the record's Uniform Resource Identifier (URI):

uri = namespace + table_name + "/" + base36(serial)

Base36 uses alphabet 0-9a-z (lowercase ASCII). Values 0–9 encode as single decimal digits, values 10–35 as single letters (a–z); larger values use multiple characters (e.g., serial 40 → 14, serial 103 → 2v).

Authorship rule: the ledger contains only records minted by the project owner. Every row has a serial number and a URI under the project namespace. Foreign Key (FK) columns (concept_uri, contract_uri, etc.) may reference URIs from other namespaces — those are foreign references, not rows authored here.

Cross-namespace imports (Work in progress): when a model references elements from an external project, the importing project ships its own ledger alongside a pruned copy of the external ledger containing only the referenced rows, annotated with provenance (source namespace, release URL, content hash).

The kind column records the structural kind of the concept permanently. Only PROPERTY concepts receive bindings. ENTITY, ENUMERATION_SET, and ENUM_VALUE concepts never do.

The third row is a singleton binding — Battery.StateOfCharge whose parent has no instances. instance_label is null; the binding still provides a stable, versioned identity for the runtime path.

erDiagram
    concepts ||--o{ revisions : "tracked by"
    concepts ||--o{ contracts : "realized as"
    revisions ||--o{ contracts : "triggers"
    contracts ||--o{ bindings : "expanded into"

    concepts {
        int serial PK
        string concept_uri UK
        string current_label
        string previous_labels
        string kind
        string status
    }
    revisions {
        int serial PK
        string revision_uri UK
        string concept_uri FK
        string previous_revision_uri FK
        string status
    }
    contracts {
        int serial PK
        string contract_uri UK
        string concept_uri FK
        string revision_uri FK
        string status
    }
    bindings {
        int serial PK
        string binding_uri UK
        string contract_uri FK
        string instance_label
        string status
    }

The following commands assume an active environment, see CONTRIBUTING for instructions on how to set it up.

Synchronises the ledger with a diff report. If no ledger exists yet, it is created. If no diff report is provided, an empty ledger is initialised.

modl sync --ledger-dir PATH --model-metadata PATH --breaking-aspects PATH [--diff-report PATH] [--dry-run] [--strict]

The model metadata file follows the s2dm metadata.yaml convention:

name: MyModel                           # human-readable model name
id: "http://namespace.example/"         # must end with '/' or '#'; full URIs are stored in the ledger
preferred_prefix: "ns"                  # optional display alias; used by inspection commands to shorten output

All three fields are required except preferred_prefix. id is used as the namespace base URI for minting ledger record identifiers.

entity:
  name.modified: false      # renames are non-breaking; suppresses --strict warnings
  properties.added: false   # adding a child property is non-breaking
  properties.removed: true  # removing a child property is breaking
  instances.added: false    # adding an instance is non-breaking
  instances.removed: true   # removing an instance is breaking
  type: true                # any change to 'type' aspect is breaking

property:
  name.modified: false
  output_type: true         # breaking — triggers a new contract
  unit: true                # breaking — triggers a new contract
  accuracy: true            # user-defined domain-specific attribute
  description: false        # known, non-breaking; suppresses --strict warnings

enumeration_set:
  name.modified: false
  values.added: false
  values.removed: true

enum_value:
  name.modified: true

All four sections (entity, property, enumeration_set, enum_value) default to empty — all changes are treated as non-breaking if omitted.

Keys use a flat dotted form to express per-operation classification:

unit: true           # shorthand — any op (added/removed/modified) is breaking
unit.added: true     # only gaining a unit for the first time is breaking
unit.modified: true  # changing the unit value is breaking
unit.removed: false  # dropping a unit annotation is non-breaking

A plain key is shorthand for all three operations. The granular dotted form takes precedence when both are present.

Each key maps to a boolean with three distinct states:

The reserved key name.modified governs rename events (renamed_from set on a diff event). It never appears in aspects — it is checked separately via renamed_from. Plain name and directional forms name.added/name.removed are forbidden.

The diff report is a JSON file produced by a language-specific adapter (e.g. for vspec, GraphQL SDL). It describes what changed between two model snapshots using modl's intermediate representation.

Each change event covers either an entity (container, object type, branch) or a property (field, attribute, signal). Key fields:

See diff_report_template.md for the full field reference, rename semantics, examples, and an adapter implementation checklist.

Your model released at v11 has a Vehicle.Speed property with unit: mph. An older system was built against v8, where the same property had unit: km/h. When it now receives v11 data it gets the wrong numbers — silently.

modl adapt answers two questions for every breaking change between two releases:

1. Is there a way to automatically bridge the gap? — Or does it require a human decision?
2. If yes, what exactly needs to happen? — A concrete, machine-readable step recipe.

The output is a YAML adaptation plan: a self-contained list of transformation rules that a downstream exporter (a data pipeline, a MongoDB aggregation generator, a migration script) can execute at runtime to serve old consumers from new data.

modl adapt never mutates the ledger — it is a read-only analysis tool.

Each rule in the adaptation plan encodes three explicit levels of information:

This separation means you can start by declaring the strategy (adaptation) and fill in the parameters (recipe) later, without losing the structural analysis.

newer ledger (v11)   ─┐
older ledger (v8)    ─┤──► modl adapt ──► compatibility report
diff (v8 → v11)      ─┤                   ├── JSON (per-entry detail)
breaking-change cfg  ─┤                   ├── Markdown (human summary)
adaptation cfg       ─┘                   └── YAML plan (transformation recipe)

• Newer release = the current platform contract (v11).
• Older release = the consumer or client that needs to be bridged (v8).
• Diff = the same diff.json you pass to modl sync, describing what changed from v8 to v11.

modl adapt runs in one or both of two directions, controlled by --direction:

With --direction both (the default) the engine runs both passes and emits two separate reports.

For each changed element the engine assigns a compatibility category and, where possible, emits a step pipeline.

Suppose the diff reports that Vehicle.Speed.unit changed from km/h (v8) to mph (v11), and you have declared this in your breaking-aspects config and adaptation config:

breaking-aspects.yaml:

property:
  unit.modified: true     # unit changes are breaking

adaptation.yaml — declares the strategy (Level 2) and the recipe (Level 3):

property:
  unit.modified:
    steps:
      - adaptation:
          kind: scale
        recipe:
          - source: mph     # what the newer release carries
            target: km/h   # what the older release consumers expect
            factor: 1.60934

modl adapt reads the diff, sees unit changed from km/h to mph, and emits:

rules:
  - rule_id: rule-0001
    concept_uri: https://myproject.org/model/concepts/1
    lossiness: none
    requires_policy: false

    change:                        # Level 1 — observed fact from diff
      kind: aspect_changed
      aspects:
        - key: unit
          newer_value: mph         # what the newer release carries (direction-neutral)
          older_value: km/h        # what the older release consumers expect (direction-neutral)

    steps:
      - adaptation:                # Level 2 — transformation class
          kind: scale
        recipe:                    # Level 3 — execution parameters
          status: complete
          source_value: mph        # what you have (direction-relative)
          target_value: km/h       # what you produce (direction-relative)
          factor: 1.60934

source_value / target_value inside the recipe are direction-relative: in newer_to_older mode source = newer value (what you have), target = older value (what you produce). change.aspects always records newer_value / older_value as direction-neutral facts about the model at each release.

When a recipe row has not yet been declared for a specific {source, target} pair, the step is emitted with recipe.status: incomplete and the entry is classified as adaptation_strategy rather than deterministic_transform. You can run the analysis before you have all conversion factors, then fill in the recipe rows incrementally.

Two separate config files feed into modl adapt:

1. Breaking-change config (--config) — the same file you use for modl sync --breaking-aspects. It declares which aspect changes are consumer-breaking. No new file needed if you already have one.

2. Adaptation config (--adaptation-config, optional) — declares the transformation step pipeline for each breaking aspect key. Every key declared here must resolve to a breaking aspect in the breaking-change config — modl adapt validates this at startup and exits with an error otherwise.

In short: only declare adaptation steps for breaking aspect keys whose values need a semantic transformation.

modl adapt \
  --diff PATH \
  --config PATH \
  [--newer-ledger PATH] \
  [--older-ledger PATH] \
  [--adaptation-config PATH] \
  [--newer-release LABEL] \
  [--older-release LABEL] \
  [--direction {both,newer-to-older,older-to-newer}] \
  [--output-dir DIR]

Exit codes: 0 — all breaking changes are bridgeable (no manual intervention required). 1 — at least one entry is manual_mapping_required or unsupported, or the adaptation config fails the consistency check.

Each entry maps a breaking aspect key to an ordered list of steps. Keys follow the same dotted form as the breaking-change config (unit.modified, datatype.modified, or a plain unit as shorthand for all ops). Every key declared here must resolve to a breaking aspect in breaking-aspects.yaml — mismatches are caught at startup.

Each step has two sub-blocks:

• adaptation — declares the transformation class (kind). Required.
• recipe — carries execution parameters. Optional for some kinds; see table below.

Recipe shapes by kind:

Full example:

# adaptation.yaml

property:
  unit.modified:
    steps:
      - adaptation:
          kind: scale
        recipe:
          - source: mph
            target: km/h
            factor: 1.60934

  datatype.modified:
    steps:
      - adaptation:
          kind: cast              # coerce source type → target type
      - adaptation:
          kind: round             # needed when the target type is narrower (e.g. Float → Int)
        recipe:
          policy: floor           # "floor" | "ceil" | "round" | "trunc"

enum_value:
  symbol.modified:
    steps:
      - adaptation:
          kind: lookup            # map the old symbol to its new equivalent
        recipe:
          - source: KMH
            target: KILOMETRES_PER_HOUR

Any extra fields you add to a recipe (e.g. operator, tolerance, your own keys) are passed through verbatim — modl never validates or interprets them. They are hints for your downstream exporter.

The step kinds are the fixed vocabulary understood by downstream exporters. kind is validated against this list at config load time — unknown values are rejected.

Each changed element is assigned a category that tells you how actionable the change is:

Only entries classified as projection_compatible, deterministic_transform, adaptation_strategy, or policy_required appear in the YAML adaptation plan.

Without --output-dir — a compact plain-text summary is printed to stdout:

Compatibility: v11 → v8  (3 changes)

  breaking — no adapter (1):
    - Vehicle.power  [field_removed]

  adapter candidates (2):
    - Vehicle.speed  [aspect_changed]  deterministic_transform
    - Vehicle.odometer  [field_renamed]  projection_compatible

  non-breaking: 0

With --output-dir DIR — three files are written into DIR (created if absent), named after the report ID (compat-{newer}-to-{older}):

compat-v11-to-v8.json — machine-readable per-entry detail plus an aggregated summary:

{
  "report_id": "compat-v11-to-v8",
  "newer_release": "v11",
  "older_release": "v8",
  "direction": "newer_to_older",
  "summary": {
    "total": 3,
    "projection_compatible": 1,
    "deterministic_transform": 1,
    "adaptation_strategy": 0,
    "policy_required": 0,
    "manual_mapping_required": 0,
    "unsupported": 0,
    "non_breaking": 1,
    "adapter_candidates": 2
  },
  "entries": [...]
}

compat-v11-to-v8.md — human-readable report listing adapter recipes for all actionable entries and a separate list of non-adaptable breaking changes that need manual attention.

compat-v11-to-v8.yaml — the machine-readable transformation recipe consumed by downstream exporters. Only adapter-candidate entries appear here. Each rule has a change section (Level 1) and a steps list where each step carries adaptation (Level 2) and recipe (Level 3) sub-blocks:

adapter_id: compat-v11-to-v8
newer_release: v11
older_release: v8
direction: newer_to_older
rules:
  - rule_id: rule-0001
    concept_uri: https://myproject.org/model/concepts/1
    lossiness: none
    requires_policy: false

    change:
      kind: aspect_changed
      aspects:
        - key: unit
          newer_value: mph
          older_value: km/h

    steps:
      - adaptation:
          kind: scale
        recipe:
          status: complete
          source_value: mph
          target_value: km/h
          factor: 1.60934

recipe.status is complete when all required parameters are available (the recipe row matched the actual diff values) and incomplete when the strategy is known but recipe parameters are still missing. The adaptation_strategy category is used for incomplete entries — they still appear in the plan so you can fill in the parameters incrementally.

Represent your domain model in your chosen modeling language (vspec, GraphQL SDL, JSON Schema, etc.). A snapshot is the complete state of the model at a point in time — a version-controlled file, a release artifact, or a git tag. The diff is always computed between two such snapshots: the previous release and the current one.

Compare two snapshots of your model to enumerate what was added, removed, or modified. The mechanism depends on your modeling language:

• Text-based formats (YAML, JSON): diff the files and post-process the output.
• Structured formats with tooling (vspec, Protobuf): use the language's own comparison tool if one exists, or write a script that loads both snapshots and walks the element tree.
• Schema registries: use the registry's diff API if available.

For the first release there is no previous snapshot — treat every element as ADDED.

The adapter is a script or tool — typically a short Python or shell program — that takes your language-specific diff output and writes a diff.json file in the ModL intermediate representation. At its simplest:

# pseudocode
previous = load("model-v1.yaml")
current  = load("model-v2.yaml")
changes  = compare(previous, current)   # language-specific logic
write_json("diff.json", to_modl_ir(changes))

The adapter is a one-time investment per modeling language. See diff_report_template.md for the full field reference, rename semantics, and an adapter implementation checklist.

Create a metadata.yaml that declares your project's namespace following the s2dm convention. Only name and id are required:

name: MyModel
id: "https://myproject.org/model/"
preferred_prefix: "mp"

Create a breaking-aspects.yaml that lists which aspect keys constitute a breaking change. Start minimal — an empty file (or {}) is valid and treats all changes as non-breaking:

entity:
  instances.added: false
  instances.removed: true
property:
  output_type: true
  unit: true

Use true for breaking aspects, false to explicitly mark a key as known-but-non-breaking (silences --strict warnings). Keys use a flat dotted form for per-op control (unit.added, unit.modified, unit.removed); a plain key is shorthand for all three.

Before touching the ledger, pass the diff report through modl sync with --dry-run and --strict:

modl sync --ledger-dir ledger/ --model-metadata metadata.yaml --breaking-aspects breaking.yaml --diff-report diff.json --dry-run --strict

Review any warnings about undeclared aspect keys. For each unknown key, decide: is it breaking (true) or intentionally non-breaking (false)? Update the config and re-run until the dry run is clean.

On the first run, the ledger does not exist yet. modl sync creates it. For a first release where you want to capture the initial model state, pass the diff report that treats every element as ADDED. To start with an empty ledger and add history in subsequent syncs, omit --diff-report.

modl sync --ledger-dir ledger/ --model-metadata metadata.yaml --breaking-aspects breaking.yaml --diff-report initial_diff.json

Persist (e.g., release) the four generated CSV files (concepts.csv, revisions.csv, contracts.csv, bindings.csv) alongside your model.

For each new model release, produce a diff between the previous and current snapshots, run the adapter, and sync:

modl sync --ledger-dir ledger/ --model-metadata metadata.yaml --breaking-aspects breaking.yaml --diff-report diff.json

Important: the id field in metadata.yaml is locked once the first modl sync run writes concept rows into the ledger. Every subsequent run must use the same id. Changing it causes modl sync to exit with a namespace-mismatch error, because the new namespace would be inconsistent with the URIs already stored in the ledger. If you need to change the namespace, create a fresh ledger.

Persist (e.g., release) the updated ledger files with the latest composed model. The ledger is append-only — existing records are never modified, only new rows are added or existing ones marked SUPERSEDED.

modl sync is designed to be a CI/CD step that runs automatically on every release. A typical pipeline stage looks like:

1. validate model
2. run adapter → diff.json
3. modl sync --ledger-dir ledger/ --model-metadata metadata.yaml --breaking-aspects breaking.yaml --diff-report diff.json --strict
4. commit and tag updated ledger CSV files

When the adapter emits a new aspect key that is not yet in the breaking-aspects config, modl warns. Decide whether it is breaking or non-breaking and add it to breaking-aspects.yaml. Run the dry run again to confirm the warning is resolved before syncing.

See here if you would like to contribute.

This section documents the rationale behind key design decisions and the alternatives that were considered and rejected. It serves as a reference when the design is challenged.

One could argue that concepts and contracts are sufficient: concepts capture identity, contracts capture the data contract. This is true only if what constitutes a breaking change is known a priori and applies uniformly to all downstream consumers. In practice, different teams have different definitions of "breaking". The four-table split reflects this:

• concepts — stable identity; what a thing is, regardless of how it changes
• revisions — a complete, unfiltered audit log of every detected change; does not judge whether a change is breaking
• contracts — derived from revisions using a user-configurable set of essential attributes; two rows share a contract only if nothing essential to that project's definition of "breaking" changed
• bindings — some modeling languages define entity instances (e.g., Door: [Left, Right]), which expand fields into multiple individually addressable runtime paths; bindings assign a stable identity to each such path

Merging revisions and contracts would either force a single global breaking-change policy or lose the audit trail. Merging bindings into contracts would require contracts to know about instance expansion, coupling two independent concepts.

The alternative is opaque integers or short labels. URIs were chosen because:

• They are globally unique without coordination — two independent projects can mint records and their identifiers will never collide
• They are self-describing: a URI encodes the namespace (who minted it), the table (what kind of record it is), and the serial (which record)
• They are dereferenceable in principle — a namespace owner can publish human-readable documentation at the URI
• They compose naturally across namespaces: FK columns in one project's ledger can reference URIs minted by another project without any registry or mapping table

Plain integers require a global registry to avoid collisions across projects. Short labels (CURIEs) require a prefix resolution context that must travel with every document that uses them.

CURIEs such as ns:0 are shorter but require the prefix-to-namespace map to be present and unambiguous at read time. A CSV file is a standalone artifact — it may be opened months later, sent to another team, or imported by a tool that has no knowledge of the original prefix declarations. Full URIs make each CSV self-contained: the namespace authority, the table name, and the serial are all recoverable from the value itself without external context.

The config file's prefix field is an optional display alias used by inspection commands to shorten output. It is never stored in the ledger.

The serial is a decimal integer internally. Decimal would be the simplest choice, but base36 was chosen for URI compactness. A model with tens of thousands of records would produce 5-digit decimal suffixes; the same range in base36 fits in 3 characters. Compact URIs matter in serialisation-heavy use cases (payloads, QR codes, logs).

Hexadecimal (base16) was rejected because it is less compact than base36 and gains nothing beyond familiarity.

Base62 (0-9A-Za-z) and base64 (0-9A-Za-z+/=) are more compact than base36 for the same integer range. They were rejected because:

• Case ambiguity: base62 uses both uppercase and lowercase letters. URIs are technically case-sensitive, but in practice URLs are routinely lowercased by proxies, logs, and developers. A URI like .../revisions/1K and .../revisions/1k would decode to different serials — a silent data corruption hazard.
• No stdlib decode: Python has no built-in base62 decoder. int(s, 36) is part of the language; base62 requires a third-party library or hand-rolled code.
• URL safety: base64 uses +, /, and =, which require percent-encoding in URIs. Base64url replaces them with - and _, but introduces yet another non-standard alphabet.

Base36 uses only 0-9a-z — all characters that are unambiguous in URLs, universally lowercased, and directly supported by Python's int(s, 36).

ModL does not parse model files directly. A language-specific adapter produces a diff report in a simple JSON format, which ModL then processes. This separation exists because:

• The identity ledger is valuable across modeling languages (vspec, GraphQL SDL, JSON Schema, etc.). The four-table structure and URI semantics are language-agnostic; only the diff production is language-specific.
• Migrations and imports between modeling languages should preserve identity: if a concept previously defined in vspec is migrated to another language, its URI should not change. A shared IR makes this possible.
• The adapter is a thin, replaceable component. ModL's validation, minting, and audit logic does not need to change when a new modeling language is supported.

• Git-friendly: CSV produces line-level diffs in git diff. A change to a single record is visible as a single changed line. Binary formats (SQLite, Parquet) produce opaque binary diffs.
• Human-readable: CSV files can be opened directly in a spreadsheet or text editor. They are suitable as release artifacts that non-technical stakeholders can inspect.
• No tooling dependency: reading a CSV requires no database engine, no schema migration, no driver. Any language or environment with a standard library can parse it.
• Easy manipulation: pandas, polars, and the Python csv module all handle CSV natively.

SQLite may be offered as an optional release artifact in the future to support consumers who prefer to run SQL queries over the ledger.

The ledger is designed for transparent governance, traceability, and provenance in data modeling projects. Deleting or modifying a record would:

• Break any downstream system that holds a reference to the deleted URI
• Make it impossible to reconstruct the state of the model at a past point in time without relying solely on git history
• Undermine the audit trail needed to answer questions like "what did this field mean at the time this data was produced?"

Records that are no longer current are marked SUPERSEDED or REMOVED. The full history remains readable. The git history provides point-in-time reproducibility at the repository level; the ledger tables provide it at the record level without requiring a git checkout.

An alternative is a separate rename-history table (e.g., concept_label_history.csv) with one row per rename event. That would be more normalised and queryable. The list column was chosen for simplicity: label history is rarely queried independently, and the added table would require its own schema validation, FK constraints, and serial management. A flat list in the concepts table is sufficient for the primary use case — knowing what a concept used to be called — without adding a fifth table to the ledger.

If richer label history (timestamps, attribution) becomes necessary, a dedicated table is the natural upgrade path.

Each model release produces a snapshot. A diff between two snapshots produces a diff report. That diff report is passed directly to ModL to update the ledger. Keeping the ledger in the same repository means:

• Every model release tag also tags the corresponding ledger state; consumers can check out any release and find a consistent pair
• The ledger is a self-contained artifact: it does not require references to an external repository to be meaningful
• CI/CD pipelines operate on a single repository checkout

A separate ledger repository would require coordinated releases across two repositories, introduce the risk of the ledger falling out of sync with the model, and require consumers to know about and access a second repository.