Three Artifacts by Five O'Clock, None of Them Typed

By the end of the afternoon there are three things on the branch that did not exist at lunchtime: a registered-schema document ready to hand to Synapse, a blank curation grid, and a column dictionary listing every value set with its terms. Nobody typed any of them. They were projected from one governed model, in two calls, by a person whose actual work that afternoon was deciding whether the change deserved a minor or a patch bump.

This article is about that after-state — what a team can do once the synapse export profile is part of how it works, and what specifically stops being anybody's job.

The change that used to cost a day

Take an ordinary modification: a specimen field gains a tighter pattern, and a controlled vocabulary gains a term.

In the arrangement most teams start with, that fans out. The canonical model is edited. Then somebody produces the Synapse-facing schema by hand, applying a keyword subset they hold in their head. Then somebody opens the manifest workbook and re-does the entry grid and the dictionary so the curators' surface still matches. Three artifacts, two of them hand-maintained, all three expected to agree — with nothing but diligence keeping them aligned.

The cost is rarely one dramatic incident. It is the standing tax: every change implemented three times, reviewed three times, and out of sync somewhere until a person happens to notice.

What the export hands you

After adoption, the first call is a schema export in the synapse format against the project. What comes back is the draft-07 subset the Synapse JsonSchema object models: the dialect declared as draft-07, a $id built from the organization, name, and version segments you supplied, definitions where a modern authoring tool would have written $defs, every internal reference rewritten to point at them, and string enumerations carrying type: string alongside their members. Inheritance arrives as a combinator referencing a definition rather than as a flattened copy. Keywords the subset does not model are gone — and each one is itemized in the response rather than silently absent.

You did not curate the subset. You did not rewrite the pointers. You did not hand-compose the identifier — you passed an organization, a name, and a version, and the profile sanitized them into legal segments for you. If the version you passed was not a plain major.minor.patch, you got the default and an explicit note saying so, instead of a malformed identifier.

What the manifests hand you

The second call generates the curation manifests, and this is the deliverable teams consistently underestimate.

From the same governed model you get two CSVs per non-inline type. The first is {name}.manifest.csv: the blank entry grid, header row only, one column per element in the model's own order, with inherited elements included ahead of the type's own — loadable directly as a curation record set. The second is {name}.dictionary.csv: a row per column carrying Column, Type, Description, Required, Value Set, followed by a value-set section listing each controlled-vocabulary term with Value Set, Value, Label, Parent.

That parent column matters. A registered schema's enum is a flat list of members; the hierarchy in your taxonomy has nowhere to go inside draft-07. In the dictionary it survives — each term keeps its label and its parent, so a broader/narrower relationship that the JSON Schema cannot express is still visible to the humans and the tooling working from the sheet.

The grid and the schema agree because they were cut from the same cloth: the enum members in the schema and the value rows in the dictionary come from one governed taxonomy; the required columns and the schema's required array come from one set of governed elements. There is no reconciliation step because there is nothing left to reconcile.

The version bump becomes a decision instead of a chore

Synapse refuses to re-register a version that already exists. In the before-state that rule is a landmine — you discover it at registration time. In the after-state it is a prompt.

Because the export is deterministic, the emitted schema is worth committing next to the model. Same model, same bytes, no diff, no bump. When the model does change, the diff shows you precisely what will change on the platform, and the version segment becomes something a reviewer sets deliberately in the same motion that produces the artifact. The thing you register is the thing your reviewers looked at.

What the team can now do that it could not before

The speed is not the interesting part. These are:

Produce both deliverables on demand, for one type or for all of them. Manifest generation takes an optional type selector, so a curator asking for "just the sample sheet" gets exactly that, without a schema release.

Review the losses before registering, not after. The response carries an itemized ledger: constraints the subset cannot enforce, annotations that have no field, types approximated, meanings narrowed. It is a checklist, and an empty one is a clean conversion.

Change the model without touching the Synapse artifacts. Adding a term, tightening a pattern, renaming a label — all of it is one edit followed by regeneration. The curation sheet cannot drift from the schema, because neither one is authored.

Serve the neighbors from the same source. Synapse is one projection among many. The group that needs LinkML, or SQL DDL, or an OWL ontology, or a data contract from the identical model gets it from the identical model, with no second canonical copy anybody has to keep honest.

Keep the round trip open. The output is plain draft-07 JSON Schema. If you ever need to bring a registered schema back — to compare it against the governed model, or to seed a new project from something already deployed — you import it with the ordinary jsonschema format. Nothing is trapped in a profile-specific dialect.

What "done" feels like now

The measure of the after-state is how boring it is. The vocabulary term is added once, to the governed taxonomy. The schema is exported with the version bumped. The manifests are generated in the same sitting. The lossiness list is read and cleared. The registered schema goes to Synapse; the grid and the dictionary go to the curators. Nothing was transcribed, nothing needs reconciling, and the reviewer spent their attention on the one question that actually needed a human: does this change deserve a new version?

If your Synapse schema and your curation workbook have started to disagree, the transform quickstart in the CoreModels documentation shows the export and the manifest generation side by side.