Who Is Allowed to Change What Your Model Means?

Every organization has an answer, and in most of them the honest one is: whoever ran the last import. A tool ingested a document, wrote what it found, and a governed concept shifted meaning because a parser made a decision at three in the morning.

We built the JSON-LD path in CoreModels on the opposite premise. Translation is mechanical and belongs to software; meaning is a human act and belongs to a person with a role. Everything below is how that line is held — and JSON-LD tests it harder than most formats, because it is an open-world description entering a governed, closed-loop system.

The parser never invents

An RDF vocabulary tells you what exists. It never claims the list is complete. It says a Person has a name; it does not say a person must have one.

So when CoreModels decodes a JSON-LD document, it translates only what is asserted. Classes become Types. Properties become Elements, wired to their classes through schema:domainIncludes and typed through schema:rangeIncludes. Subclass statements become inheritance. Classes marked as subclasses of schema:Enumeration become Taxonomies, and their member nodes become terms.

And because the source is open-world, imported properties default to optional. The vocabulary never said "required," so we never write "required." That is a small rule with a large consequence: no obligation exists in your governed model unless a human imported it from an explicit assertion or added it deliberately. Tightening an open description into a closed contract is a meaning change, and meaning changes are not a parser's decision to make.

The same restraint governs what we keep. The @context prefix map is preserved, along with each property's original range identifier and each enumeration member's full IRI — the details a faithful re-emit needs. A property whose range points at a class the document never defines is still kept as a reference, because in an open world "not defined here" is not an error.

Import is additive, and it is role-gated

Nothing enters a governed project as a side effect of reading something. Importing a JSON-LD vocabulary is an explicit write requiring the Admin role; exporting the project — into JSON-LD or any other format — requires only Viewer. The stateless surfaces, including mapping a schema toward another and replaying a stored plan, write nothing at all.

That split is what makes broad access safe: analysts, downstream teams and AI assistants can read and project the governed model freely, while the set of people who can change what it says stays small, named and accountable.

Meaning changes pass through a human gate

The riskiest operation is not importing a new vocabulary alongside your model. It is aligning one onto the model you already govern — where an external document gets to redefine your terms.

CoreModels imposes a rhythm. The mapping call is inherently a dry run: it returns the mapped schema and the executed plan as a replayable artifact, and writes nothing. Replaying the same plan against the same source provably yields the same output; determinism is a tested property here, not an aspiration. Applying a mapping runs through a separate map-import path that is dry-run first by contract, so a human reads the summary of what would change before anything is written.

The plan pipeline is deliberately unforgiving about its inputs. An explicit, hand-authored mapping guide is validated hard — an unknown key is rejected with an error naming the offending path, because a silently ignored typo would execute a plan you did not intend. An AI-proposed mapping passes the identical validation gate as a human-authored one, with at most one repair attempt, and the model's self-reported confidence is advisory only: the gate never trusts it. The AI path is also honest about its blast radius: it sends schema content to an external model provider server-side and requires Editor or Admin membership rather than mere read access.

Machines may propose meaning. Only people accept it, and only through a path that leaves a record.

Lossiness is a ledger, not a footnote

A line in our transform documentation doubles as a design principle: success: true does not mean "nothing changed" — it means "it ran." Always read the lossiness.

Every transform response carries that ledger, each entry with a kind, a path and a plain-English explanation. There are four kinds: something had no home in the target and was left out; a type was represented by a close-but-not-exact neighbor; a rule could not be enforced and was relaxed; a meaning was narrowed or guessed.

A vocabulary imported cleanly can produce an empty ledger — and the ledger fills as soon as the model is projected somewhere with fewer expressive slots. Export an enumeration imported from a vocabulary to Postgres: the response reports a constraint relaxation, explaining that the vendor has no inline enum and the allowed-value constraint is therefore not enforced. That is the entry you want before the table ships, not after.

Publishing back out is honest in a quieter way. An RDFS-style vocabulary has no slot for required-ness or cardinality, so a JSON-LD export states what your types and properties are and what they mean — not what a record must contain. A consumer who needs enforcement should take ShEx or JSON Schema from the same governed model. We do not smuggle constraints into non-standard corners of the wire format to fake a fidelity the format does not offer. Likewise, a governed node that never had an IRI is exported under a plainly local placeholder namespace rather than dressed up in someone else's authoritative one.

Drift becomes evidence you can review

Vocabularies evolve: public ones on their own cadence, partner ones on release cycles you do not control. Ungoverned, that evolution is discovered late — in production, by whoever hits the renamed property first.

Governed, it is discovered on purpose. When a new release arrives, run it through the stateless mapping surface against your governed model. The returned plan and lossiness ledger are a concrete statement of the delta: what still aligns, what no longer does, what would be dropped or relaxed. Because decode-encode-decode is structurally stable, the differences you see are differences that exist, not tooling artifacts. The team reviews that evidence, decides, and only then deploys the change through the gated path.

That is the whole trust story in miniature: import additively, preserve what we cannot model, refuse to invent constraints, gate every meaning change behind a person, and write down — every single time — what the translation could not keep.

The transform section of the CoreModels docs describes the response envelope and the four lossiness kinds in full.