Climate Data Hub Metadata Standard

This repository defines the Climate Data Hub metadata standard, input schema, and authoring templates. Records are validated against the schema and mapped to STAC or OGC API Records.

[!WARNING] This standard is still a draft. Breaking changes are expected while it is being tested and refined.

Start Here

• Authoring guide - how to fill out metadata.
• Templates - fillable YAML starting points for common record types.
• Full template - the complete metadata input structure.
• Core schema - validates the YAML structure and controlled values.
• Standard - formal field definitions and validation expectations.
• Extending & adopting - add your own extension, build a profile, or adopt the core standard outside the Hub.

Mappings

• Crosswalk - CDH fields mapped to STAC and OGC API Records.
• STAC mapping
• OGC API Records mapping

Vocabularies

Controlled vocabularies live in vocab/:

• domain.json
• resource_type.json
• commodity.json

Vocabulary files are validated against spec/schemas/vocab/vocabulary.schema.json.

After editing a vocabulary, regenerate the schema fragments:

npm run gen-schemas

Versioning

The standard, schemas, vocabularies, and extensions share one v<MAJOR>.<MINOR>.<PATCH> git tag (see spec/standard.md section 2 for the model).

To cut a release, bump the version and let the tooling propagate it:

npm version --no-git-tag-version <NEW>   # bump package.json; the `version` hook
                                         # (scripts/sync-version.js) rewrites v<PREV> ->
                                         # v<NEW> across every tracked file (schema $ids,
                                         # extension URLs, cdh_schema_version, docs),
                                         # regenerates the vocab schemas, re-bundles the
                                         # profile, and runs the test suite

Then update CHANGELOG.md by hand (the hook leaves it alone): move [Unreleased] to [<NEW>] - <date> and add a fresh empty [Unreleased]. Commit, then publish a GitHub release tagged v<NEW> — that triggers the publish workflow, which re-checks the tag matches package.json, validates, and deploys the schemas so the /v<NEW>/ URLs resolve.

Validation

All validation runs through npm:

npm install        # one-time, installs dev tooling
npm test           # formatting + markdown lint + schema/vocab/yaml validation
npm run check      # schemas + vocabs + compile + bundle + yaml + negative fixtures

Individual targets: check-schemas, check-vocabs, compile-schemas, check-yaml, check-invalid, bundle-profile, gen-schemas, lint-md.

Records under tests/invalid/ are negative fixtures - each MUST fail validation. They catch schema or rule changes that accidentally loosen validation.

Acknowledgements

The npm-based validation pipeline and schema-publishing workflow are adapted from/inspired by the stac-extensions/template project.