hca-metadata-schema 0.2.0__tar.gz

hca_metadata_schema-0.2.0/.gitignore

@@ -0,0 +1,209 @@
+# MCP server config (machine-specific virtualenv paths)
+.mcp.json
+
+# Claude Code per-user settings (permissions, etc.)
+.claude/settings.local.json
+
+# Claude Code agent worktrees (isolated subagent working copies)
+.claude/worktrees/
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   Everything under packages/ is a published library, not a deployed app: nothing in the build
+#   or deploy path reads these locks (uv build resolves from pyproject.toml; the Docker images use
+#   the services' poetry.lock). Tracking them only invited drift, because release-please bumps
+#   pyproject.toml but not uv.lock (see #483). Scoped to packages/ so future uv-based *services*
+#   (apps) can still commit their locks.
+packages/*/uv.lock
+#   shared/ is the same shape: a library consumed only as a path dependency, never
+#   installed from its own lock (services build it through their poetry.lock; uv
+#   build/sync resolve from pyproject.toml). Nothing reads shared/uv.lock, so ignore it.
+shared/uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.env.make
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Lambda deployment packages and environments
+*.zip
+deployment/layers/
+deployment/test-lambda-env/
+deployment/entry-sheet-validator/output/
+response.json
+
+# macOS
+.DS_Store
+
+# Drafting space for outbound correspondence with atlas teams — notes to the
+# breast, gut, immune and pancreas teams while they are being written. These
+# are not code and do not belong in a tools repo, but they should not be one
+# `git clean` from gone either. Anything sent lands in hca-ingest-coordination.
+notes/

hca_metadata_schema-0.2.0/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+## [0.2.0](https://github.com/clevercanary/hca-validation-tools/compare/hca-schema-v0.1.0...hca-schema-v0.2.0) (2026-10-28)
+
+
+### Features
+
+* add 10th and 11th decade development stages ([#202](https://github.com/clevercanary/hca-validation-tools/issues/202)) ([775091e](https://github.com/clevercanary/hca-validation-tools/commit/775091ebff3033f526e5d434fd9da3f0cce5dc0c))
+* add musculoskeletal dataset schema ([#172](https://github.com/clevercanary/hca-validation-tools/issues/172)) ([#173](https://github.com/clevercanary/hca-validation-tools/issues/173)) ([4ff848b](https://github.com/clevercanary/hca-validation-tools/commit/4ff848b1b63db0da66558c852544e6ff96809fa1))
+* move ambient_count_correction and doublet_detection from uns to obs ([#349](https://github.com/clevercanary/hca-validation-tools/issues/349)) ([90b2b0b](https://github.com/clevercanary/hca-validation-tools/commit/90b2b0bea36500f7bb9a54961fd3dfc3f74c9cf9))
+* **schema:** give the LinkML schema its own version, bumped by release-please ([#537](https://github.com/clevercanary/hca-validation-tools/issues/537)) ([#803](https://github.com/clevercanary/hca-validation-tools/issues/803)) ([d016fa3](https://github.com/clevercanary/hca-validation-tools/commit/d016fa3a4e14abe9d99fadfe2d3c8164f7d85b96))
+
+
+### Bug Fixes
+
+* **schema:** make three obs columns visible to annDataLocation discovery ([#545](https://github.com/clevercanary/hca-validation-tools/issues/545)) ([2f4679b](https://github.com/clevercanary/hca-validation-tools/commit/2f4679b87424e3c2c6ea0c5f408106c466843b36))
+
+
+### Code Refactoring
+
+* update file structure to support multiple independent services ([#124](https://github.com/clevercanary/hca-validation-tools/issues/124)) ([ef1782a](https://github.com/clevercanary/hca-validation-tools/commit/ef1782a247af1fe9f562a12256b8ebc8e3ff657f))
+
+## 0.1.0 (unversioned baseline)
+
+`0.1.0` does not name one fixed schema. The schema was first given this version in
+August 2025 (#124) and changed many times afterwards without a bump, including the
+musculoskeletal bionetwork schema (December 2025) and the `Cell` class (#538). A file
+or report that says `0.1.0` was checked against some schema from that period, but which
+one cannot be told from the version alone.
+
+From 0.2.0 on, `core.yaml`'s `version:` is bumped by release-please according to
+`docs/schema-version-contract.md`, and every change is listed here (#537). The 0.2.0 entry
+also lists the earlier, unversioned changes, since no release marked where they ended.

hca_metadata_schema-0.2.0/Makefile

@@ -0,0 +1,55 @@
+# hca-metadata-schema Makefile
+# Schema validation and model generation. The data dictionary is built from shared/ (it needs shared's code).
+
+SCHEMA_DIR := src/hca_metadata_schema
+GENERATED := $(SCHEMA_DIR)/generated/core.py
+SCHEMAS := $(wildcard $(SCHEMA_DIR)/*.yaml)
+UV := uv run --group codegen
+SUPPRESS_WARNINGS := 2>/dev/null
+
+.PHONY: help
+help:
+	@echo "hca-metadata-schema tasks:"
+	@echo "  validate-schema - Validate all schema files"
+	@echo "  lint-schema     - Lint schema files"
+	@echo "  gen-schema      - Generate the Pydantic models from the LinkML schemas"
+	@echo "  test            - Run the package tests"
+
+# Schema validation
+.PHONY: validate-schema
+validate-schema:
+	@echo "Validating all schema files..."
+	@for schema in $(SCHEMAS); do \
+		echo "Validating $$(basename $$schema)..."; \
+		$(UV) gen-yaml $$schema > /dev/null $(SUPPRESS_WARNINGS) || exit 1; \
+		echo "✓ $$(basename $$schema) is valid"; \
+	done
+	@echo "All schema files are valid!"
+
+# Lint schema files
+.PHONY: lint-schema
+lint-schema:
+	@echo "Linting schema files..."
+	@$(UV) linkml lint $(SCHEMA_DIR) --validate
+
+# Lint schema files with only errors (no style warnings)
+.PHONY: lint-schema-errors
+lint-schema-errors:
+	@echo "Linting schema files (errors only)..."
+	@$(UV) linkml lint $(SCHEMA_DIR) --validate --ignore-warnings || (echo "❌ Schema has critical errors" && exit 1)
+	@echo "✓ No critical errors found in schema files"
+
+# Generate Python models from schemas
+.PHONY: gen-schema
+gen-schema:
+	@echo "Generating models..."
+	@# Generate to a temp file so a failed run leaves the committed model intact. sed marks the schema version line
+	@# so release-please bumps it with core.yaml (docs/schema-version-contract.md).
+	@$(UV) gen-pydantic $(SCHEMA_DIR)/core.yaml --meta AUTO > $(GENERATED).tmp
+	@sed -E 's/^(version = "[^"]*")$$/\1  # x-release-please-version/' $(GENERATED).tmp > $(GENERATED)
+	@rm $(GENERATED).tmp
+	@echo "Done"
+
+.PHONY: test
+test:
+	@uv run pytest tests/ -v

hca_metadata_schema-0.2.0/PKG-INFO

@@ -0,0 +1,54 @@
+Metadata-Version: 2.5
+Name: hca-metadata-schema
+Version: 0.2.0
+Summary: HCA metadata schema: LinkML definitions and the Pydantic models generated from them
+Project-URL: Homepage, https://github.com/clevercanary/hca-validation-tools
+Author-email: Clever Canary <dave@clevercanary.com>
+License-Expression: MIT
+Requires-Python: <4.0,>=3.10
+Requires-Dist: pydantic<3,>=2
+Description-Content-Type: text/markdown
+
+# hca-metadata-schema
+
+The HCA metadata schema: the LinkML YAML definitions and the Pydantic models generated from them.
+
+## Installation
+
+```bash
+pip install hca-metadata-schema
+```
+
+## Usage
+
+```python
+from hca_metadata_schema import CORE_SCHEMA_PATH, __version__
+from hca_metadata_schema.generated.core import Cell, Dataset, Donor, Sample
+
+# The Pydantic models validate a record against the schema
+Donor(...)
+
+# The LinkML source, for tools that read the schema itself (e.g. linkml-runtime's SchemaView)
+CORE_SCHEMA_PATH  # .../hca_metadata_schema/core.yaml
+```
+
+The package depends only on pydantic. Reading the YAML with `SchemaView` needs `linkml-runtime`, which
+you install yourself.
+
+## Versioning
+
+The schema has one version, in `core.yaml`, and the package version is the same number. What each bump
+means is set out in
+[`docs/schema-version-contract.md`](https://github.com/clevercanary/hca-validation-tools/blob/main/docs/schema-version-contract.md).
+
+## Development
+
+```bash
+make gen-schema       # regenerate generated/core.py from the YAML
+make validate-schema  # check every YAML file compiles
+uv run pytest tests/ -v
+```
+
+After editing the YAML, regenerate the models and the data dictionary (`make -C shared gen-schema
+generate-data-dictionary` from the repo root) and commit the result. CI's `generated-schema` job fails if either is
+stale, and the opt-in pre-commit hook `schema-generated` regenerates them when a schema YAML file is committed.

hca_metadata_schema-0.2.0/README.md

@@ -0,0 +1,43 @@
+# hca-metadata-schema
+
+The HCA metadata schema: the LinkML YAML definitions and the Pydantic models generated from them.
+
+## Installation
+
+```bash
+pip install hca-metadata-schema
+```
+
+## Usage
+
+```python
+from hca_metadata_schema import CORE_SCHEMA_PATH, __version__
+from hca_metadata_schema.generated.core import Cell, Dataset, Donor, Sample
+
+# The Pydantic models validate a record against the schema
+Donor(...)
+
+# The LinkML source, for tools that read the schema itself (e.g. linkml-runtime's SchemaView)
+CORE_SCHEMA_PATH  # .../hca_metadata_schema/core.yaml
+```
+
+The package depends only on pydantic. Reading the YAML with `SchemaView` needs `linkml-runtime`, which
+you install yourself.
+
+## Versioning
+
+The schema has one version, in `core.yaml`, and the package version is the same number. What each bump
+means is set out in
+[`docs/schema-version-contract.md`](https://github.com/clevercanary/hca-validation-tools/blob/main/docs/schema-version-contract.md).
+
+## Development
+
+```bash
+make gen-schema       # regenerate generated/core.py from the YAML
+make validate-schema  # check every YAML file compiles
+uv run pytest tests/ -v
+```
+
+After editing the YAML, regenerate the models and the data dictionary (`make -C shared gen-schema
+generate-data-dictionary` from the repo root) and commit the result. CI's `generated-schema` job fails if either is
+stale, and the opt-in pre-commit hook `schema-generated` regenerates them when a schema YAML file is committed.

hca_metadata_schema-0.2.0/pyproject.toml

@@ -0,0 +1,36 @@
+[project]
+name = "hca-metadata-schema"
+version = "0.2.0"
+description = "HCA metadata schema: LinkML definitions and the Pydantic models generated from them"
+authors = [{ name = "Clever Canary", email = "dave@clevercanary.com" }]
+license = "MIT"
+readme = "README.md"
+requires-python = ">=3.10,<4.0"
+# The generated models import only pydantic and the standard library. Keep it that way: this package
+# is what lets hca-anndata-tools use the schema without pulling in linkml.
+dependencies = [
+    "pydantic>=2,<3",
+]
+
+[project.urls]
+Homepage = "https://github.com/clevercanary/hca-validation-tools"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0,<9",
+    "pyyaml>=6.0,<7",
+]
+# gen-pydantic and gen-yaml for the Makefile's schema targets, kept out of `dev` so the tests (and CI)
+# do not install linkml. Same pin and linkml-runtime cap as shared/pyproject.toml, for the same reason.
+codegen = [
+    "linkml==1.9.2",
+    "linkml-runtime>=1.9.2,<1.10",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+# Ships every file under the package directory, which is how the LinkML YAML reaches the wheel.
+[tool.hatch.build.targets.wheel]
+packages = ["src/hca_metadata_schema"]

hca_metadata_schema-0.2.0/src/hca_metadata_schema/__init__.py

@@ -0,0 +1,11 @@
+"""The HCA metadata schema: LinkML YAML definitions and the Pydantic models generated from them.
+
+`CORE_SCHEMA_PATH` is the root schema; it imports every other YAML file shipped here. The models are in
+`hca_metadata_schema.generated.core`, regenerated from the YAML by `make gen-schema`.
+"""
+
+from pathlib import Path
+
+__version__ = "0.2.0"  # x-release-please-version
+
+CORE_SCHEMA_PATH = Path(__file__).parent / "core.yaml"

hca_metadata_schema-0.2.0/src/hca_metadata_schema/bionetwork/adipose.yaml

@@ -0,0 +1,32 @@
+id: https://github.com/clevercanary/hca-validation-tools/schema/bionetwork/adipose
+name: hca-validation-adipose
+title: Adipose BioNetwork Extensions
+description: Adipose network–specific refinements to the HCA dataset schema
+license: MIT
+
+prefixes:
+  linkml: https://w3id.org/linkml/
+  hca: https://github.com/clevercanary/hca-validation-tools/schema/
+
+default_prefix: hca
+default_range: string
+
+imports:
+  - linkml:types
+  - ../dataset
+  - ../slots
+  - ../enums
+
+classes:
+  AdiposeDataset:
+    is_a: Dataset
+    description: Dataset with Adipose BioNetwork–specific metadata requirements.
+    slots:
+      - ambient_count_correction
+      - doublet_detection
+    
+  AdiposeSample:
+    is_a: Sample
+    description: Sample with Adipose BioNetwork–specific metadata requirements.
+    slots:
+      - dissociation_protocol

hca_metadata_schema-0.2.0/src/hca_metadata_schema/bionetwork/gut.yaml

@@ -0,0 +1,35 @@
+id: https://github.com/clevercanary/hca-validation-tools/schema/bionetwork/gut
+name: hca-validation-gut
+title: Gut BioNetwork Extensions
+description: Gut network–specific refinements to the HCA dataset schema
+license: MIT
+
+prefixes:
+  linkml: https://w3id.org/linkml/
+  hca: https://github.com/clevercanary/hca-validation-tools/schema/
+
+default_prefix: hca
+default_range: string
+
+imports:
+  - linkml:types
+  - ../dataset
+  - ../slots
+  - ../enums
+classes:
+  GutDataset:
+    is_a: Dataset
+    description: Dataset with Gut BioNetwork–specific metadata requirements.
+    slots:
+      - ambient_count_correction
+      - doublet_detection
+    
+  GutSample:
+    is_a: Sample
+    description: Sample with Gut BioNetwork–specific metadata requirements.
+    slots:
+      - radial_tissue_term
+      - dissociation_protocol
+    
+
+  

hca_metadata_schema-0.2.0/src/hca_metadata_schema/bionetwork/musculoskeletal.yaml

@@ -0,0 +1,25 @@
+id: https://github.com/clevercanary/hca-validation-tools/schema/bionetwork/musculoskeletal
+name: hca-validation-musculoskeletal
+title: Musculoskeletal BioNetwork Extensions
+description: Musculoskeletal network–specific refinements to the HCA dataset schema
+license: MIT
+
+prefixes:
+  linkml: https://w3id.org/linkml/
+  hca: https://github.com/clevercanary/hca-validation-tools/schema/
+
+default_prefix: hca
+default_range: string
+
+imports:
+  - linkml:types
+  - ../dataset
+  - ../slots
+  - ../enums
+classes:
+  MusculoskeletalDataset:
+    is_a: Dataset
+    description: Dataset with Musculoskeletal BioNetwork–specific metadata requirements.
+    slots:
+      - ambient_count_correction
+      - doublet_detection

hca_metadata_schema-0.2.0/src/hca_metadata_schema/cell.yaml

@@ -0,0 +1,69 @@
+id: https://github.com/clevercanary/hca-validation-tools/schema/cell
+name: hca-validation-cell
+title: HCA Validation Cell Schema
+description: Schema for validating Human Cell Atlas (HCA) cell metadata
+license: MIT
+
+prefixes:
+  linkml: https://w3id.org/linkml/
+  hca: https://github.com/clevercanary/hca-validation-tools/schema/
+
+default_prefix: hca
+default_range: string
+
+imports:
+  - linkml:types
+
+classes:
+  Cell:
+    description: >-
+      A single cell derived from a sample
+    slots:
+      - author_cell_type
+      - cell_type_ontology_term_id
+
+slots:
+  author_cell_type:
+    title: Author Cell Type
+    description: Encoding of author intuition of cellular annotation in the dataset.
+    examples:
+      - value: Goblet cell; microglia
+    annotations:
+      annDataLocation: obs
+      tier: Tier 1
+    range: string
+    required: false
+    multivalued: false
+    comments:
+      - Encoding of author intuition of cellular annotation in their dataset.
+      - >-
+        Retained alongside the ontology term so the author's original naming is not lost
+        when terms are mapped to CL.
+
+  cell_type_ontology_term_id:
+    title: Cell Type Ontology Term ID
+    description: Cell Ontology (CL) term.
+    examples:
+      - value: CL:0001204
+    annotations:
+      annDataLocation: obs
+      tier: Tier 1
+      cxg: cell_type_ontology_term_id
+    range: string
+    required: false
+    multivalued: false
+    notes:
+      - |
+        This must be a Cell Ontology (CL) term (http://www.ebi.ac.uk/ols4/ontologies/cl).
+
+        If no appropriate high-level term can be found or the cell type is unknown, then it is strongly recommended to use 'unknown'.
+
+        The following terms must not be used: "CL:0000255" for eukaryotic cell; "CL:0000257" for Eumycetozoan cell; "CL:0000548" for animal cell.
+      - >-
+        ZFA, FBbt, and WBbt terms are allowed depending on the organism, and "na" is
+        allowed if tissue_type is "cell line" — per the h5ad validator's curie_constraints.
+    comments:
+      - Encoding of cell type to help alignment with other datasets.
+      - >-
+        Unrecoverable once dropped — populate_labels derives cell_type from this column,
+        not the reverse. Optional here to match the h5ad validator's requirement_level.

hca_metadata_schema-0.2.0/src/hca_metadata_schema/core.yaml

@@ -0,0 +1,23 @@
+id: https://github.com/clevercanary/hca-validation-tools/schema/core
+name: hca-validation-core
+title: HCA Validation Core Schema
+description: Core schema for validating Human Cell Atlas (HCA) data
+license: MIT
+version: 0.2.0  # x-release-please-version
+
+prefixes:
+  linkml: https://w3id.org/linkml/
+  hca: https://github.com/clevercanary/hca-validation-tools/schema/
+
+default_prefix: hca
+default_range: string
+
+imports:
+  - linkml:types
+  - dataset
+  - bionetwork/adipose
+  - bionetwork/gut
+  - bionetwork/musculoskeletal
+  - donor
+  - sample
+  - cell