Virtual Study JSON Schema

Use this payload when calling
POST /api/public_virtual_studies/{custom_id}
with a publisher API key to create and publish a virtual study.

A virtual study is either:

Static: fixed sample set (requires studies[*].samples)
Dynamic: sample set recomputed from filters (dynamic: true; studies[*].samples may be omitted)

studies (array) is always required.

1. Virtual Study Data Fields

Field	Type	Required	Description
`name`	string	yes	Title shown on the study page and in search results.
`description`	string	no	Free-text description.
`studies`	array of objects	yes	Declares which studies participate in the virtual study. Each entry: `{ id: <studyId>, samples: [...] }`. Sample list required for static studies; optional for dynamic ones.
`dynamic`	boolean	no	If `true`, sample membership is recomputed from `studyViewFilter` on each load. If `false` or omitted, the study is static and must include explicit sample lists.
`studyViewFilter`	object	required for dynamic studies	Study View–style filter block describing cohort selection. Used for dynamic recomputation and for documenting static cohorts.
`typeOfCancerId`	string	no	Cancer type classification. Must match an existing cancer type.
`pmid`	string	no	PubMed ID linked to the study.

2. `studies[]` Structure

Field	Type	Required	Description
`id`	string	yes	Study stable ID included in this virtual study.
`samples`	array of strings	static: yes dynamic: no	Sample stable IDs belonging to this study. Required for static virtual studies; optional for dynamic ones (filters determine membership).

3. `studyViewFilter` Structure

Entry-point selectors

Field	Type	Required	Notes
`sampleIdentifiers`	array of `{studyId, sampleId}`	yes	Explicit sample list.
`studyIds`	array of strings	yes	Apply filters across entire studies.

Common filter blocks (all optional)

Filter Block	Purpose	Shape
`clinicalDataFilters`	Clinical attribute filtering	`{ attributeId, values: [{value}] }` or numeric ranges (`{start,end}`). Do not mix value and range in same object.
`customDataFilters`	Custom categorical filters	Same shape as clinical filters.
`namespaceDataFilters`	Namespaced categorical filters	Same shape as clinical filters.
`geneFilters` / `mutationDataFilters` / `structuralVariantFilters`	Gene-based molecular selection	Must include `molecularProfileIds`. Uses `geneQueries` and `values`.
`genomicDataFilters` / `genericAssayDataFilters` / `genomicProfiles`	Expression, assay, or other profile filters	Profiles must exist in the referenced studies.
`clinicalEventFilters`	Event timeline filters	Same contract as Study View API.
Treatment filters (`sampleTreatmentFilters`, etc.)	Treatment-based sample or patient selection	Same structure as clinical categorical filters.
`caseLists`	Intersect predefined case lists	Array of arrays of case list IDs.

4. Examples

Static Virtual Study

{
  "name": "BRCA ER+ samples",
  "description": "Explicit sample list across two studies",
  "studies": [
    { "id": "brca_tcga", "samples": ["TCGA-AR-A1AI-01", "TCGA-AR-A1AJ-01"] },
    { "id": "brca_igr",  "samples": ["P-0000010-T01-IM6"] }
  ],
  "typeOfCancerId": "brca",
  "pmid": "12345678"
}

Dynamic Virtual Study

{
  "name": "MSI-high colorectal (dynamic)",
  "description": "Rebuilt from filters on each load",
  "dynamic": true,
  "studies": [
    { "id": "coadread_tcga" }
  ],
  "studyViewFilter": {
    "studyIds": ["coadread_tcga"],
    "clinicalDataFilters": [
      { "attributeId": "MUTATION_SIGNAT_MSI_STATUS", "values": [{ "value": "MSI-H" }] }
    ]
  },
  "typeOfCancerId": "coadread"
}

Exploring the Full Filter Structure

The studyViewFilter object supports a wide range of filter types used throughout the Study View interface—clinical, molecular, genomic, treatment, event-based, and many others. Because these filters mirror the full Study View filtering capabilities, the structure can be extensive and is not exhaustively documented here.

Easiest Way to Discover Supported Filters

The most reliable and user-friendly way to explore the complete filter schema is:

Create a virtual study using the cBioPortal UI (Study View → Create Virtual Study).
Save it, then retrieve the generated filter definition via the link: https://<cbioportal-host>/api/session/virtual_study/<virtual-study-id>
Inspect the data field of the returned JSON.

The data.studyViewFilter value shows the exact filter structure produced by the UI.
This includes all nested blocks, attribute IDs, molecular profile IDs, treatment filters, genomic filters, etc., exactly as the server expects them.

This UI-to-API round-trip is the most accurate way to discover:

Which filter blocks are supported on your specific cBioPortal instance
The exact shape of each filter object
Correct field names and attribute IDs used by your data installation
How combined filters are structured (e.g., gene + clinical + case lists)

Because filter capabilities may vary between portal installations or data versions, using the UI-generated filter as a reference ensures your studyViewFilter is valid and reproducible.