The Difference Between a Guess and a Record

There are two ways to handle the places where a platform's public documentation goes quiet. You can guess — pick the behavior that seems likely, emit it, and hope the wire agrees with you. Or you can record — pick the conservative representation, write down exactly what you could not confirm, and hand that note to the person making the decision.

Most conversion tools guess, because guessing looks like capability and recording looks like weakness. Our synapse export profile in CoreModels records, everywhere, on principle. That stance — plus two companions, additive import and human-gated meaning — is what governance actually consists of when you emit artifacts into a platform you do not operate.

Grounded in the documented, and nothing more

Sage Bionetworks' Synapse validates entities against registered JSON Schemas, and its public REST documentation defines a JsonSchema object with a specific set of fields. That field set is our authoritative subset. A keyword that appears as a field of that object may appear in our output. A keyword that does not is stripped — never kept on the theory that the platform will probably tolerate it.

Every strip is a typed record with a path. And the type matters, because not all strips are equal. A stripped keyword that carried a validation rule — a numeric step, an exclusive bound, a dependency between properties — is reported as a constraint relaxation: the schema you are about to register enforces less than the model it came from, and you should know precisely where. A stripped annotation or vendor extension — a comment, an example, an internal marker — is reported as a structural drop: information left behind, but no rule weakened. A reviewer skimming the ledger can triage in seconds: relaxations demand attention; drops usually get a nod.

The same discipline covers shapes, not just keywords. Synapse documents type as a single value, never an array. When an array arrives — say, a string-or-null union decoded out of a modern tool — we narrow it to its one non-null member and record the narrowing; when no single member can preserve the union, we drop the keyword and record the relaxation. Both outcomes are visible. Neither is a guess dressed as a feature.

Where the documentation is silent, so are our claims

Then there is the frontier: behaviors the public material simply does not settle. Does registration-time validation accept a null-union? Does Synapse assert format on a date-time string, or treat it as draft-07 does, as an annotation? How does the platform model an enum whose members are not strings? What happens to a reference that points at another registered schema rather than at a local definition?

We do not know, and we refuse to pretend otherwise. In each case the encoder picks the conservative representation — a nullable field goes unrepresented rather than encoded via an unverified convention, and a date-time is emitted as a string with its format annotation, each with an honest record saying the behavior is unconfirmed; only internal #/definitions/... references are produced by the structural encode. When a real observed behavior settles one of these questions, the record retires and the encoding improves. That is the structural difference between a record and a guess: a record is designed to be replaced by knowledge; a guess is designed to be forgotten.

The companion manifests live under the same rule. The curation grid and column dictionary we generate are templates for humans and curation teams — we do not claim they are a platform wire format, because the exact rendering contract of the curation tooling is not publicly documented. Where we cannot verify, we say "template," not "integration."

Import is additive, and directionality is honest

The profile is encode-only, and the refusal is part of the design. Ask the engine to decode with the synapse format and it declines — with the reason and the remedy: a Synapse schema is plain draft-07 JSON Schema, so you import it with the ordinary jsonschema format. No second decoder to maintain, no pretense of a capability that would duplicate one we already have.

That import path is additive. Writing a schema into a CoreModels project upserts types and elements against what is already there, through the same governed profile layer as every other write — it does not bulldoze the project to make room. Bringing a deployed registered schema back for comparison, or seeding a project from one, is a merge you can inspect, not a replacement you must trust.

Identity gets the same care. The registered-schema $id composes from an organization, a name, and a version, hyphen-delimited — so the segments you supply are sanitized into legal parts, a version that is not a plain major.minor.patch falls back to the default with an explicit record saying so, and the default organization is a placeholder precisely because the platform's own organization name is reserved and a real deployment must use its own. Nothing about the identifier is improvised at the moment of registration.

Meaning passes through a person

The last discipline is about who decides. Exporting a schema or generating manifests requires only read access to the project; anything that writes a governed model requires admin rights; and the mapping flows that reshape a schema onto a project are dry-run first — plan, result, and ledger on the table before any write. An AI-proposed mapping plan passes the identical validation gate as a hand-authored one, with at most one repair attempt and no credit for its own confidence score.

Synapse itself supplies the final gate: it rejects re-registering an existing version. We treat that as a feature to lean into, not friction to paper over. Because the export is deterministic, an unchanged model produces an unchanged artifact — so the question "does this deserve a new version?" arises exactly when something real changed, and it is answered by a person reading a diff and a ledger, not by a timestamp in a filename.

Small honesties, compounded

None of these decisions is dramatic on its own. A whitelist instead of a hope. A typed record instead of a silent strip. An "unconfirmed" instead of a plausible invention. A refusal that names the correct route. A merge instead of an overwrite. A human in front of every change of meaning.

Compounded, they produce the property governance actually needs: when the schema is registered and the manifests are in the curators' hands, everyone involved can say what the artifacts contain, what they no longer contain, and who decided that was acceptable — with the evidence in writing.

For the full response envelope and the lossiness kinds, see the schema transform documentation in the CoreModels docs.