# cidc-schemas
This repository contains formal definitions of the CIDC metadata model using [json-schema](https://json-schema.org/) syntax and vocabulary.
### View documentation at https://nci-cidc.github.io/cidc-schemas/
## Installation
To install the latest released version, run:
```bash
pip install nci-cidc-schemas
```
## Development
### Project Structure
- **`cidc_schemas/`** - a python module for generating, validating, and reading manifest and assay templates.
- **`schemas/`** - json specifications defining the CIDC metadata model.
- `templates/` - schemas for generating and validating manifest and assay templates.
- `assays/` - schemas for defining assay data models.
- `artifacts/` - schemas for defining artifacts.
- **`docs/`** - the most recent build of the data model documentation, along with templates and scripts for re-generating the documentation.
- **`template_examples/`** - example populated Excel files for template specifications in `schemas/templates`, and `.csv`s auto-generated from those `.xlsx`s that allow to transparently keep track of changes in them.
- **`tests/`** - tests for the `cidc_schemas` module.
### Developer Setup
Install necessary dependencies.
```bash
pip install -r requirements.dev.txt
```
Install and configure pre-commit hooks.
```bash
pre-commit install
```
### Running tests
This repository has unit tests in the _tests_ folder. After installing dependencies
the tests can be run via the command
```bash
pytest tests
```
### Building documentation
Pre-commit hooks ensure documentation is automatically up-to date. To build the documentation manually, run the following commands:
```bash
python setup.py install # install helpers from the cidc_schemas library
python docs/generate_docs.py
```
This will output the generated html documents in `docs/docs`. If the updated docs are pushed up and merged into master, they will be viewable at https://nci-cidc.github.io/cidc-schemas/.
## Using the Command-Line Interface
This project comes with a command-line interface for validating schemas and generating/validating assay and manifest templates.
### Install the CLI
Clone the repository and cd into it
```bash
git clone git@github.com:NCI-CIDC/cidc-schemas.git
cd cidc-schemas
```
Install the `cidc_schemas` package (this adds the `cidc_schemas` CLI to your console)
```bash
python setup.py install
```
Run `cidc_schemas --help` to see available options.
If you're making changes to the module and want those changes to be reflected in the CLI without reinstalling the `cidc_schemas` module every time, run
```bash
python3 -m cidc_schemas.cli [args]
```
### Creating a new assay or analysis type ###
In order to create a new assay type, your best bet is to just search for an existing assay and copy it.
Preferably, look at visium and copy exactly what it does. Make changes in the assay schema and template for your
particular assay and/or analysis schema.
There are a lot of gotchas and hidden parsing going on behind the scenes. Listing them all would be hard, so this is the best
practical advice.
Be sure to regenerate the docs after creating your schema, so the new schema is added to the reference docs.
### Generate templates
Create a template for a given template configuration.
```bash
cidc_schemas generate_template -m templates/manifests/pbmc_template.json -o pbmc.xlsx
```
### Validate filled-out templates
Check that a populated template file is valid with respect to a template specification.
```bash
cidc_schemas validate_template -m templates/manifests/pbmc_template.json -x template_examples/pbmc_template.xlsx
```
### Validate JSON schemas
Check that a JSON schema conforms to the JSON Schema specifications.
```bash
cidc_schemas validate_schema -f shipping_core.json
```
Raw data
{
"_id": null,
"home_page": "https://github.com/NCI-CIDC/cidc-schemas",
"name": "nci-cidc-schemas",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.14,>=3.13",
"maintainer_email": null,
"keywords": "cidc_schemas",
"author": "NCI",
"author_email": "nci-cidc-tools-admin@mail.nih.gov",
"download_url": "https://files.pythonhosted.org/packages/f3/7d/6445649f453deb5d424994a25d3b86d3bddbe5c7182039713c5b6878b2ca/nci_cidc_schemas-0.28.3.tar.gz",
"platform": null,
"description": "# cidc-schemas\n\nThis repository contains formal definitions of the CIDC metadata model using [json-schema](https://json-schema.org/) syntax and vocabulary.\n\n### View documentation at https://nci-cidc.github.io/cidc-schemas/\n\n## Installation\n\nTo install the latest released version, run:\n\n```bash\npip install nci-cidc-schemas\n```\n\n## Development\n\n### Project Structure\n\n- **`cidc_schemas/`** - a python module for generating, validating, and reading manifest and assay templates.\n - **`schemas/`** - json specifications defining the CIDC metadata model.\n - `templates/` - schemas for generating and validating manifest and assay templates.\n - `assays/` - schemas for defining assay data models.\n - `artifacts/` - schemas for defining artifacts.\n- **`docs/`** - the most recent build of the data model documentation, along with templates and scripts for re-generating the documentation.\n- **`template_examples/`** - example populated Excel files for template specifications in `schemas/templates`, and `.csv`s auto-generated from those `.xlsx`s that allow to transparently keep track of changes in them.\n- **`tests/`** - tests for the `cidc_schemas` module.\n\n### Developer Setup\n\nInstall necessary dependencies.\n\n```bash\npip install -r requirements.dev.txt\n```\n\nInstall and configure pre-commit hooks.\n\n```bash\npre-commit install\n```\n\n### Running tests\n\nThis repository has unit tests in the _tests_ folder. After installing dependencies\nthe tests can be run via the command\n\n```bash\npytest tests\n```\n\n### Building documentation\n\nPre-commit hooks ensure documentation is automatically up-to date. To build the documentation manually, run the following commands:\n\n```bash\npython setup.py install # install helpers from the cidc_schemas library\npython docs/generate_docs.py\n```\n\nThis will output the generated html documents in `docs/docs`. If the updated docs are pushed up and merged into master, they will be viewable at https://nci-cidc.github.io/cidc-schemas/.\n\n## Using the Command-Line Interface\n\nThis project comes with a command-line interface for validating schemas and generating/validating assay and manifest templates.\n\n### Install the CLI\n\nClone the repository and cd into it\n\n```bash\ngit clone git@github.com:NCI-CIDC/cidc-schemas.git\ncd cidc-schemas\n```\n\nInstall the `cidc_schemas` package (this adds the `cidc_schemas` CLI to your console)\n\n```bash\npython setup.py install\n```\n\nRun `cidc_schemas --help` to see available options.\n\nIf you're making changes to the module and want those changes to be reflected in the CLI without reinstalling the `cidc_schemas` module every time, run\n\n```bash\npython3 -m cidc_schemas.cli [args]\n```\n\n### Creating a new assay or analysis type ###\n\nIn order to create a new assay type, your best bet is to just search for an existing assay and copy it.\n\nPreferably, look at visium and copy exactly what it does. Make changes in the assay schema and template for your\nparticular assay and/or analysis schema.\n\nThere are a lot of gotchas and hidden parsing going on behind the scenes. Listing them all would be hard, so this is the best\npractical advice.\n\nBe sure to regenerate the docs after creating your schema, so the new schema is added to the reference docs.\n\n### Generate templates\n\nCreate a template for a given template configuration.\n\n```bash\ncidc_schemas generate_template -m templates/manifests/pbmc_template.json -o pbmc.xlsx\n```\n\n### Validate filled-out templates\n\nCheck that a populated template file is valid with respect to a template specification.\n\n```bash\ncidc_schemas validate_template -m templates/manifests/pbmc_template.json -x template_examples/pbmc_template.xlsx\n```\n\n### Validate JSON schemas\n\nCheck that a JSON schema conforms to the JSON Schema specifications.\n\n```bash\ncidc_schemas validate_schema -f shipping_core.json\n```\n",
"bugtrack_url": null,
"license": "MIT license",
"summary": "The CIDC data model and tools for working with it.",
"version": "0.28.3",
"project_urls": {
"Homepage": "https://github.com/NCI-CIDC/cidc-schemas"
},
"split_keywords": [
"cidc_schemas"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "489359d75c314e67263004f0a7d102954ba869ecd9ad28ede4caaf216938b145",
"md5": "f0f2333b77b0458c3684c572ea57e92e",
"sha256": "6e7379d0d4164caed825eea01e45074a9cd59c64a7278a41878c2139e6abc087"
},
"downloads": -1,
"filename": "nci_cidc_schemas-0.28.3-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "f0f2333b77b0458c3684c572ea57e92e",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": "<3.14,>=3.13",
"size": 2563572,
"upload_time": "2025-09-08T16:26:11",
"upload_time_iso_8601": "2025-09-08T16:26:11.964344Z",
"url": "https://files.pythonhosted.org/packages/48/93/59d75c314e67263004f0a7d102954ba869ecd9ad28ede4caaf216938b145/nci_cidc_schemas-0.28.3-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f37d6445649f453deb5d424994a25d3b86d3bddbe5c7182039713c5b6878b2ca",
"md5": "fe09ebb252858ada32bc36b2c97e497f",
"sha256": "462ed5f8f37e0de05fe67b20625db16c52e35db89935ea0eaebfa2c289b20c90"
},
"downloads": -1,
"filename": "nci_cidc_schemas-0.28.3.tar.gz",
"has_sig": false,
"md5_digest": "fe09ebb252858ada32bc36b2c97e497f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.14,>=3.13",
"size": 2723151,
"upload_time": "2025-09-08T16:26:13",
"upload_time_iso_8601": "2025-09-08T16:26:13.991796Z",
"url": "https://files.pythonhosted.org/packages/f3/7d/6445649f453deb5d424994a25d3b86d3bddbe5c7182039713c5b6878b2ca/nci_cidc_schemas-0.28.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-08 16:26:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "NCI-CIDC",
"github_project": "cidc-schemas",
"github_not_found": true,
"lcname": "nci-cidc-schemas"
}
JSON
