After the Import: The Requests That Stop Being Projects

The clearest sign that a vocabulary has been properly adopted is not a diagram. It is a category of request that stops requiring a meeting.

"Can we get the partner vocabulary as a JSON Schema so the API can validate against it?" "Can the warehouse get tables for this?" "Can we publish our own model as linked data for the catalog?" In most estates each of those is a small project with a named owner and a delivery date. Once a JSON-LD vocabulary lives in a governed CoreModels project, they are calls — made by whoever needs the answer, without waiting for the person who understands the source document.

Here is what that after-state actually looks like.

One import, and the vocabulary becomes a model

Adoption starts with a single, deliberate, role-gated write: a project Admin posts the document to the schema import endpoint with the format key jsonld. Nothing is imported by side effect and nothing else in the estate needs to change first.

What lands is a model rather than a stored file. Classes are Types, with rdfs:subClassOf preserved as inheritance. Properties are Elements, attached through schema:domainIncludes to every class that declares them, and typed through schema:rangeIncludes — XSD and schema.org datatypes become primitives, a range naming another class becomes a real reference between Types, and a class marked as a subclass of schema:Enumeration becomes a Taxonomy whose members become terms.

Every node also keeps its passport. Each @id is an IRI, and the import lifts it into a mapsTo identity annotation on the node it creates. From that moment, the project can answer a question most estates cannot: which of our governed elements are, verifiably, the vocabulary's terms — not similarly named, but the same IRI.

Every consumer serves itself

This is where the before-and-after gap is widest.

Before: "give the API team a schema" meant someone re-derived it by hand, and the copy started drifting the day it was handed over. After: exporting is a Viewer-level call against the same governed model, so the people who need a projection can take one without holding write access to anything.

The API team exports JSON Schema — and the identity imported on day one rides along, surfacing as an x-maps-to annotation on the property, a behavior our test suite proves. The exported field is not merely called name; it still is https://schema.org/name. The warehouse team exports SQL DDL in the dialect they run — Postgres by default, MySQL or SQL Server on request — where the same identity comes back as a column comment. The streaming team exports Avro. The semantics team exports OWL, ShEx or LinkML. Same source, different projections, no re-derivation.

Each export returns its own lossiness report: a typed list of anything the target format could not hold exactly, each entry carrying a path and a plain-English explanation. That turns the historical failure mode — discovering months later that an enumeration became an unconstrained string — into a review checklist attached to the artifact that caused it.

Publishing back out stops being a special project

The reverse direction matters as much, and it is the same surface. Exporting a governed project with format jsonld produces a standard @context-plus-@graph document: Types as rdfs:Class nodes, inheritance as rdfs:subClassOf, Elements as rdf:Property nodes with their domains and ranges, Taxonomies as enumeration classes with their member nodes.

Two details make the output usable rather than merely valid. The emitted @context contains only the prefixes the document actually uses, so consumers get a clean, minimal header instead of an inherited pile of namespaces. And nodes whose mapsTo identities fall inside a known namespace come out under their compact prefixed names — what entered as schema.org vocabulary leaves as schema.org vocabulary, not as synthetic local identifiers. Decode, encode, decode again is structurally stable, and that round trip is asserted by test, so what you publish is what you imported plus what you deliberately changed.

The records follow the schema

Schemas are half of the job. The same transform surface moves instance data, and jsonld is one of the supported data formats alongside JSON, CSV, SQL inserts and Avro. Records can enter and leave the project in linked-data shape, guided by the project's own schema — and the guidance is honest: a record field the schema does not know is reported as a structural drop rather than failing the batch or slipping in unnoticed.

Teams that publish project data as JSON-LD in configured shapes get a second lever through the MCP server. An assistant or script lists a project's profiles with fetch_json_ld_import_profiles, then calls export_json_ld with the chosen profile id, selecting types, elements, taxonomies or data types. Graph-based export covers the project; tree-based export starts from exactly one root node. An optional space id narrows the scope.

Alignment instead of duplication

The most valuable outcome is the least visible one: what happens when the vocabulary's next version arrives, or when a partner's vocabulary has to be reconciled with the model you already govern.

That work runs through the mapping surface, and the mapping call is inherently a dry run — it writes nothing, whatever it computes. It returns the mapped schema and the executed plan as a replayable artifact, so the same plan against the same source provably produces the same output. The team reads the plan and the lossiness ledger as evidence, decides, and only then has an Admin apply it through the map-import path, which itself supports a dry run first.

The practical effect: adopting a new release of a vocabulary becomes a review with attachments, not an archaeology exercise.

Before and after, in one sentence

Before: one authoritative vocabulary nobody could execute, and a private, drifting translation of it inside every team that needed one. After: one governed import, and each team pulls its own projection — JSON Schema, SQL, Avro, OWL, ShEx, LinkML, or JSON-LD again — from a model that remembers, node by node, where every element came from.

The new capability is not just speed. It is that "do these two schemas mean the same thing?" has become a question with an answer, and "what did this conversion cost us?" has become a list you can read.

Ready-to-paste import and export requests are in the transform section of the CoreModels docs.