A Study Is Never Only a cBioPortal Study

Trace one clinical attribute backwards from a cBioPortal study and watch how many systems it passes through. It was captured in a form or an EDC instrument. It was cleaned somewhere. It was joined to a specimen table in a warehouse. Somebody transformed it into an analysis-ready model. Then it was written into four # header rows of a staging file, validated, and uploaded — and along the way it was named four different things by four different teams, each of whom was right within their own system.

cBioPortal is a specific and excellent place in that landscape: an open platform for exploring cancer genomics, with a file-bundle study format and a validator that enforces its rules. It is not, and was never designed to be, the only place your clinical concepts need to exist. So the question worth asking is not "how do we get everything into the portal?" It is: where does a governed study schema sit relative to everything around it?

The shape a study takes once it is imported

Inside CoreModels, a cBioPortal study does not import into a cBioPortal-shaped structure. It parses into the same vendor-neutral estate model every connector uses — datasets with fields, normalized checks, and lineage — and vendor-specific detail rides in metadata rather than in new top-level concepts.

So the patient and sample files become Types, their attributes become Elements, PATIENT_ID and SAMPLE_ID become identities, and the sample file's PATIENT_ID becomes a governed reference. None of those are cBioPortal concepts once they are in the graph. They are governed-model concepts that happen to have arrived from cBioPortal. The study's own identifiers are not thrown away — they ride along as vendor identity mappings, so a governed node can always tell you which cBioPortal object it came from and round-trip back to it.

Two consequences follow immediately, and they are the reason the neutral model earns its keep.

Consequence one: the meaning leaves in whatever shape the reader needs

Because export runs off the neutral model rather than off the staging file, a clinical attribute you imported from a cBioPortal study can leave as LinkML, JSON Schema, ShEx, JSON-LD, SQL DDL, Avro, Protobuf, an OWL ontology, or an ODCS data contract. The study's meaning stops being trapped in one serialization.

This matters more in multi-site research than almost anywhere else. A collaborating group that does not run cBioPortal still needs your patient schema. A validation service needs JSON Schema. A warehouse team needs DDL. Under the old arrangement, each of those is a person hand-translating a TSV header and introducing their own small misunderstanding. Under a governed model, each is an export — and every export carries its own lossiness ledger, so the recipient knows exactly what their target format could not hold.

To be precise about what we are claiming: we implement these specifications; we do not speak for the organizations that steward them. Our job is to read and write them faithfully, and to say in writing wherever a target cannot express something the source could.

Consequence two: the estates next door are peers, not conversions

The same neutral model is what the other connectors parse into — REDCap for study capture, dbt for transformation, Snowflake, BigQuery, Databricks, Microsoft Fabric and AWS Glue for warehouse and catalog estates, Airflow and Airbyte for orchestration and movement, Confluent Schema Registry for streaming contracts, Neo4j for graph, Salesforce for operational data.

That means a cBioPortal study and, say, a REDCap data dictionary are not two unrelated imports into two unrelated tools. They are two estates in one graph, described in the same vocabulary, each carrying its own vendor identity. You can govern the study alongside the systems that feed it and the systems that consume it, and ask questions across the boundary instead of at it.

The design point underneath is that no connector is the center. cBioPortal is a peer of dbt and REDCap in the graph, not a special case — the connector layer is deliberately built so that adding a vendor requires no privileged position for the vendors already there. A governance layer that quietly assumed the portal was the source of truth would be easy to build and useless the moment a concept needed to exist somewhere else.

Grounding in the vocabularies the field already shares

Cancer research has public ontologies for exactly the reason this article exists: so one group's data can mean the same thing as another's. A governed clinical attribute is the natural place to anchor them.

CoreModels can consult the public EMBL-EBI Ontology Lookup Service for candidate terms for a schema node — ranked matches from ontologies such as EFO, MONDO, or HP — and, when a human picks one, bind it as a first-class mapping on the node. The suggestion step is advisory and writes nothing; the binding is an explicit, human-directed act. What makes it more than a label is the carrier: a bound term rides on the same mapping the rest of the stack reads, so it travels through every format export you produce. An attribute that arrived as a column header stops being a local string and becomes a node carrying an IRI other tools recognize.

Deliberately beside the portal, not on top of it

Neutrality also defines what we do not do.

CoreModels is not a replacement for cBioPortal and does not sit between you and your instance. It never holds portal credentials — the live-connection capability is declared but deferred, on purpose. And it models only the clinical staging files, because those are schema; the mutation, copy-number, and expression files are data, not schema, and we leave them alone. You still curate your study. You still upload it. Nothing about your relationship with the portal changes.

Why the split is the right one

There is a clean division of labour here worth naming: the portal is where a study is explored; the governed model is where its schema is defined, versioned, connected, and exported. Each does the thing it is good at. Keeping those roles distinct is what lets a study stop being an island without asking cBioPortal to become something it was never meant to be — and what lets the meaning of a clinical attribute outlive any single tool that happened to hold it.

The cBioPortal quickstart in the CoreModels integration docs covers the import and generate paths for a study; the integration guide beside it covers the other estates a study can sit next to.