Your Data Model Outlives Its Toolchain

For most of a decade, a data coordinating center in the Synapse world did not exactly have a data model — it had a schematic data model. The CSV the curation team maintained was written for schematic to compile. The JSON-LD graph it produced was shaped for schematic to traverse. The validation rules were expressed in schematic's vocabulary, the contributor manifests came out of schematic's generator, and the Data Curator App put a face on all of it. The model and the toolchain were one artifact, and that was fine — right up until April 2026, when the toolchain's repository was archived with a deprecation notice naming the end of the year.

The replacement path is public and specific. The Data Curator App is being replaced by Synapse-native Curator. Validation moves to JSON Schemas registered with the platform itself and bound to entities. And the instruction to every schematic-based DCC reduces to this: take the data model your toolchain understood and turn it into registered Synapse JSON Schemas — authored against the subset of draft-07 that the platform's schema object models — before the support cliff arrives.

A migration with no migrator

Read that instruction closely and three hard facts fall out of it.

The path is manual. Sage ships documentation — a guide for the Curator-era data model, a tutorial for authoring JSON Schemas — not a converter. Nothing takes what a schematic-based DCC has and emits the registered-schema documents it needs. The translation is a person's job, type by type, vocabulary by vocabulary.

The target is a subset, and the subset is silent. A registered Synapse schema is draft-07, but only the keywords the platform's JsonSchema REST object has fields for. There is no published inventory of what an arbitrary model loses crossing that line. A keyword outside the subset does not raise an error; it is simply not part of the registered schema, and the first sign is usually a value validating that should not have.

The identity is strict. A registered schema is addressed by an identifier composed of an organization, a name, and a semantic version, hyphen-delimited — the organization pre-created and unique, the version a plain major.minor.patch, and the platform refusing to re-register a version that already exists. On the manual path, every one of those rules is discovered at registration time, which is the worst possible moment.

Multiply by every type in the model, every controlled vocabulary, and every release for the rest of the consortium's life, and the shape of the problem is clear: this is not a one-off conversion task. It is the adoption of a new canonical home for the model — under deadline, with no fidelity report.

Bring the model in the shape it already compiles to

The practical entry point is easier than the deadline makes it feel, because schematic-era pipelines already compile toward JSON Schema — it is the shape the platform's own tutorial teaches and the shape validation ultimately consumed. So the migration route in CoreModels starts there, through one of two doors.

The first door is the ordinary jsonschema import: bring the model as the JSON Schema your existing pipeline compiles to, and it lands in a governed project — types, elements, controlled vocabularies, inheritance, descriptions, required-ness, held once, with roles and review. The second door is the linkml import, for teams whose modeling is heading where serious DCC modeling is heading; the same governed project receives it, and the rest of the route is identical. Either way, the governed model — not any single output file — is what replaces the schematic CSV as the canonical home. That matters beyond this migration: the next toolchain transition, whenever it comes, starts from a governed model instead of from another excavation.

The Synapse-facing artifact becomes a projection. Export in the synapse format, supplying the organization, name, and version for the registered-schema identifier. The export composes the identifier from those segments — each sanitized into a legal part, with an explicit ledger note instead of a malformed URI when a version is not plain semver — declares the draft-07 dialect, renames $defs to definitions and rewrites every internal pointer to match, and keeps exactly the keywords the platform's documented field set can carry.

And the platform's own strictness turns from a landmine into the release discipline. Synapse refuses to re-register an existing version, so every real change must bump — and because the export is deterministic, an unchanged model produces an unchanged document. Re-export, diff, and the question "does this deserve a new version?" arises exactly when something changed, answered by a reviewer reading the diff rather than by a registration failure at an inconvenient hour.

The ledger is the migration's fidelity report

Here is the deliverable the manual path never produces. Every construct the subset cannot carry comes back from the export as a typed record with a path and a plain-English explanation. A stripped numeric-step or exclusive-bound constraint is reported as a relaxation — the registered schema now enforces less than the model says, at exactly this path. A dropped annotation is reported as a structural drop. A narrowed type is reported as a narrowing. A term hierarchy flattened into draft-07's flat enum is reported, with a pointer to the artifact where the hierarchy survives.

The ledger is also honest about the boundary of its own knowledge. Where the platform's public record does not settle a behavior — whether a nullable field can be represented as a null-union, whether format on a date-time string is enforced or annotational, how non-string enums are modeled, how references to other registered schemas resolve — the export chooses the conservative representation and records the uncertainty as a loss pending a real platform fixture, rather than guessing wire behavior.

For a migration, that itemized list — what will not be enforced, what was approximated, what remains unconfirmed — is precisely the document a review board should read before anything is registered. It converts "we moved the model and hope nothing important fell out" into "here is everything that changed, classified, with paths." The manual path has no equivalent; the losses just happen, silently, one hand-translated keyword at a time.

The curators are half the migration

A schematic-based DCC is not migrating a schema; it is migrating a curation practice. The contributor-facing surface — the entry grid, the column dictionary, the controlled vocabularies — was the toolchain's other output, and it needs a successor too.

From the same governed model, the manifest generator cuts two CSVs per type: the blank entry grid, one column per element in model order with inherited elements leading, and the dictionary listing each column's type, description, required flag, and driving value set — followed by a value-set section with one row per vocabulary term, carrying its label and its parent. The hierarchy the flat enum had to discard survives there, visible to humans and tooling. Grid, dictionary, and registered schema are cut from the same definitions, so they cannot drift apart. They are templates for the Curator-era record-set world, faithful to the schema they accompany — though we make no claim about any particular tool's rendering behavior, because that contract is not publicly documented.

Run it as a release process, not a rescue

Because every piece of this is deterministic and stateless, the migration is also the standing pipeline. The same work runs over MCP for teams driving it from an assistant or an orchestration layer: transform_schema with the target format set to synapse and the three identity segments produces the registration-ready document and its ledger; generate_synapse_manifests produces the curation companions from the same source, down to a single type when a curator asks for just one sheet. Commit the schema, the ledger, and the manifests together; diff before bumping; register only what changed. The first run is the migration. Every run after that is an ordinary release.

What this is not

Honesty about scope, because a forced migration is exactly where overpromising hurts most.

The native schematic artifacts are not decoded directly: there is no CSV-data-model or JSON-LD-graph importer behind this profile. The route is "bring the model as JSON Schema or LinkML" — the shapes schematic-era pipelines compile to and modern modeling produces. Schematic-specific validation rules and cross-manifest dependencies do not translate; where they encoded real requirements, those requirements must be re-expressed in the governed model deliberately, by the people who own them. Nothing is registered to Synapse automatically: the export produces a document, and your engineers register it through Sage's own tooling, under your organization and your credentials. And the fidelity claim is bounded on purpose: the export targets the documented field set of the platform's schema object; everything the subset cannot carry is declared in the lossiness ledger; behaviors the public record leaves unconfirmed are recorded as losses pending fixtures, not guessed.

What survives all of those caveats is what the deadline actually demands: a canonical model that outlives this toolchain and the next one, a registered-schema projection with a legal identifier and an enforced version discipline, a curator surface that cannot drift from the schema — and, for the first time in this migration, a written account of everything the translation cost.

The import formats, the export options, and the manifest generation are covered end to end in the transform quickstart that ships with the CoreModels documentation.