Where a Schema Goes After You Export It

Follow the artifact. A JSON Schema document leaves your modeling environment, gets registered with a schema service under an organization and a version, gets bound to entities on a data platform, and from then on every annotation set on those entities is validated against it. In parallel, a tabular manifest derived from the same definitions lands in front of contributors, who fill it in row by row; their uploads succeed or fail against the schema the platform holds. That is the life of a schema in the Synapse world — and understanding that world is the best way to understand where CoreModels does and does not sit in it.

The platform side, briefly and carefully

Synapse is Sage Bionetworks' collaborative platform for scientific data. Among its services is a native JSON Schema facility: an organization registers schemas — draft-07 documents, constrained to the field set of the platform's documented JsonSchema REST object — and binds them to entities, after which the platform validates entity annotations against them. Registered schemas are addressable by a composed identifier: organization, schema name, and semantic version.

Around that core sits a curation practice. Research communities and data coordination teams gather contributions through tabular manifests — an entry grid whose columns mirror a schema's fields, plus a dictionary describing each column and its controlled vocabulary. Open-source tools in this space generate and render such manifests; contributors work in spreadsheets, and validation happens against the registered schema when data arrives. That practice is mid-transition: the long-standing schematic toolchain was archived in April 2026 with an end-of-year deprecation notice, its Data Curator front end is giving way to Synapse-native Curator, and JSON-Schema-based curation — the registered schema doing the validating — is the designated road forward. The architecture remains pragmatic throughout: the schema is the contract, the manifest is the human interface, and the platform is the enforcement point.

One thing to say plainly: CoreModels is built by ARAMAI. We are not affiliated with, endorsed by, or connected to Sage Bionetworks. Our synapse export profile is grounded in Synapse's public REST documentation and in publicly registered example schemas — the same materials available to anyone — and where those materials are silent, our output says so rather than improvising.

The upstream position

CoreModels sits one step before all of that: it is where the model is governed. Types, elements, controlled vocabularies, inheritance, descriptions, required-ness — maintained once, in one project, with roles and review. The synapse format is a projection of that model: the draft-07 subset the platform's schema object can carry, with the registered-schema identifier composed from the organization, name, and version you supply, and every construct the subset cannot hold itemized in a lossiness report. Alongside it, the manifest generator cuts the entry grid and the column dictionary — including a value-set section that preserves each vocabulary term's label and parent — from the identical definitions.

The point of the upstream position is that Synapse is rarely the only consumer. The same research data team usually also has a warehouse that wants SQL DDL, an ontology group that wants OWL, a pipeline team that wants Avro or Protobuf, an interoperability effort that wants LinkML, and neighbors who want plain JSON Schema, ShEx, JSON-LD, or a data contract. In CoreModels those are all projections of one governed model. The Synapse-facing artifacts stop being a separately maintained fork of the truth and become one output among many, regenerated rather than reconciled.

The LinkML lane, specifically

One of those neighbors deserves more than a mention. LinkML is where serious DCC data modeling is heading — a schema language with classes, slots, inheritance, enumerations, and semantic mappings, institutionally mature and increasingly the choice of consortia that treat their data dictionary as a long-lived scientific artifact. And yet no supported LinkML-to-Synapse toolchain exists. The one flagship consortium dictionary that is authored in LinkML and registered on Synapse today gets there through a pipeline its own team built and maintains: compile the LinkML source toward JSON Schema, coax the output into the platform's draft-07 subset, compose the registered identifiers, and keep all of it working as both ends evolve. It works — for that team. Every other group that wants the same result is invited to rebuild the machinery alone and rediscover the subset's quirks empirically.

Our linkml import followed by the synapse export is that pipeline, generalized. The LinkML model decodes into the governed model like any other format; the Synapse encode targets the documented field set of the platform's schema object, composes the registered identifier from the organization, name, and version you supply, and itemizes in the lossiness ledger everything the subset could not carry — including the behaviors the public record leaves unconfirmed, which are recorded as losses pending real platform fixtures rather than guessed at. The bespoke pipeline's hard-won knowledge, as a supported path with a receipt.

Directionality follows the artifact

A detail of the profile's design says something about how we think tools should behave in an ecosystem: synapse is encode-only, and that is not a gap — it is an acknowledgment of what the artifact is.

A registered Synapse schema is plain draft-07 JSON Schema. It needs no special reader; our ordinary jsonschema import decodes it, and asking the synapse format to decode returns a refusal that names that route. The mirror case exists elsewhere in the catalog: the MACH ODM format decodes only, because ODM entities are authored documentation and generating prose back out of a model would be an invention. Direction, in both cases, follows the nature of the artifact rather than the symmetry of a feature matrix. A format list where every entry claims both directions regardless is telling you about its marketing, not its engineering.

Edges we drew on purpose

It is worth being explicit about what the profile does not do, because restraint is part of fitting into someone else's ecosystem responsibly.

We do not register schemas with Synapse. The export produces the document; registration happens with your own Synapse organization, your credentials, your governance. We default the organization segment to a placeholder — the platform's own organization name is reserved, and a real deployment must use an organization it has actually created. We do not claim the curation tooling's rendering behavior: the manifest CSVs are templates for humans and curation teams, faithful to the schema they accompany, but we make no promise about how any particular grid tool will render them, because that contract is not publicly documented. And where the platform's validation behavior is unconfirmed — null-unions, format enforcement, non-string enums — we emit conservatively and record the open question instead of asserting an answer.

The result is a clean seam. On one side, a governed model and deterministic projections with an honest change ledger. On the other, a platform that owns registration, binding, and enforcement. Nothing in between pretends to be the other side.

Choosing a neighborhood, not a walled garden

Teams working in and around Synapse tend to live in several standards at once — JSON Schema for the platform, LinkML for exchange, OWL for ontology work, SQL for the warehouse, tabular manifests for the humans. The realistic goal is not to replace any of that. It is to stop hand-maintaining the crosswalks between them.

That is the ecosystem argument for the synapse profile in one sentence: govern the model where governance belongs, and let each community's format be a projection with a receipt. The platform keeps doing what it does well — registration, binding, validation at scale. The curators keep their spreadsheets. The warehouse keeps its DDL. And the thing they all describe stays one thing.

For the full list of import and export formats and their options, see the schema transform documentation in the CoreModels docs.