Deprecating NMDC Schema elements
By deprecating, rather than deleting, schema elements in the NMDC model, we ensure backward compatibility, extend user trust, and provide a valuable historical record, aiding in the understanding of the model's evolution. Therefore, 'deleting' a schema element in NMDC is instead, a two-step (and two-release) deprecation process.
First release cycle:
- Add deprecation annotations to the element's definition
| Annotation | Value |
|---|---|
| One of: deprecated_element_has_exact_replacement OR deprecated_element_has_possible_replacement * | uriorcurie value required |
| deprecated | A string explaining the reason for deprecation along with a link to the corresponding issue. |
| last_updated_on | |
| modified_by | With an ORCID value |
| Deprecation Date | Conforms to iso8601/international dates (e.g., # doi_awards deprecated on 2023-11-12 in a class's usage). |
* note: If a replacement is not warranted, then using only the deprecated metadata tag with an explanation
string and issue link is fine.
Second release cycle:
- Move the deprecated element to the "deprecated.yaml" schema file. We do this so that the deprecated elements can still be found in the documentation and via reference from stable unique identifiers (w3ids), but do not appear in the main schema file nor participate in the validation of data.
- Remove the element itself from the original schema YAML file (e.g. core.yaml, annotation.yaml, etc.).
- Remove any references to the deprecated element from the original schema YAML file. **
** note: For a deprecated class, references could be in the is_a or mixin elements of another class,
or in the domain or range elements of an existing slot. For deprecated slots, check all classes that reference that slot, etc.
- Check whether anything outside the schema source still names the element, and deal with it in the same
pull request or in a linked issue. Mapping files and committed reports under
assets/are the usual place this shows up.
Elements named outside the schema source
The steps above cover the schema YAML. They do not cover the mapping files, committed reports, and example
changesheets under assets/, which keep naming an element long after the schema stops exposing it. Run:
make report-asset-usage
The report lists which assets name an element defined in deprecated.yaml. For each one there are three
outcomes, and all three are fine as long as the choice is recorded in the pull request:
| Situation | What to do |
|---|---|
| Nothing in the repo or the organization reads the file | Delete it. See Retiring a file from assets/. |
| A Makefile target regenerates it | Regenerate it, and check that the target is a prerequisite of something, so it does not go stale again. |
| It is read by something that still needs the old name | Leave it, and say in the pull request why. |
Worked example: Finalize Deprecation of collection_date_inc
deprecated collection_date_inc, and an automated review flagged that assets/misc/neon_nmdc_term_mapping.tsv still
mapped incubationLength to it. Nothing read that file, so it was deleted separately rather than remapped.
That question, "remove or remap?", was taken to the 2026-08-26 NMDC Schema and Metadata meeting because the
guide had no answer for it. This section is the answer.
Consumer repositories
The steps above cover this repository. Other repositories import specific elements by name and can break the moment a named element disappears from here, whether or not they still use it.
submission-schema is the known case. Its config/nmdc_schema_import.yaml and
src/nmdc_submission_schema/schema/nmdc_submission_schema_base.yaml list individual slots to pull in,
and its build (make schema-build) fails outright, with ValueError: Slot '<name>' not found in source
schema, the moment a listed slot is removed here. Before finalizing a deprecation (the second release
cycle), check whether the element is named in submission-schema's import config, and either:
- get a submission-schema PR removing it merged first, or in the same release window, or
- say so explicitly on the nmdc-schema PR, so submission-schema does not repin to a release containing the removal until its own PR is ready.
Worked example: building submission-schema against
Finalize Deprecation of collection_date_inc's
branch reproduces ValueError: Slot 'collection_date_inc' not found in source schema. immediately,
because submission-schema still imports it (config/nmdc_schema_import.yaml lines 864 and 891, checked
2026-09-16).
Other repositories may depend on an element too, without going through this import mechanism.
report_asset_usage.py above only sees this repository, so search the rest of the microbiomedata
organization for the element's name before finalizing a deprecation:
gh search code --owner microbiomedata "<element name>" --limit 100 \
--json repository,path \
--jq '.[] | select(.repository.nameWithOwner != "microbiomedata/nmdc-schema") | "\(.repository.nameWithOwner) \(.path)"'
For each hit, remove or update the reference in that repository, or open an issue there and link it from the nmdc-schema pull request. GitHub code search only covers each repository's default branch and does not index all code, so an empty result does not prove that nothing uses the element.