Skip to content
BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

9 Commits
.github
.github
 
 
examples
examples
 
 
json-schema
json-schema
 
 
.gitignore
.gitignore
 
 
CHANGELOG.md
CHANGELOG.md
 
 
LICENSE
LICENSE
 
 
README.md
README.md
 
 
package-lock.json
package-lock.json
 
 
package.json
package.json
 
 

Repository files navigation

Health Extension Specification

This document explains the Health Extension to the SpatioTemporal Asset Catalog (STAC) specification.

It adds domain metadata for geospatial public-health and epidemic-intelligence datasets: disease outcomes and surveillance snapshots, environmental and socio-demographic determinants (covariates), and model outputs such as risk maps. It is not a clinical EHR, imaging, or FHIR profile.

Design principles:

  1. Thin required core — only health:data_type is always required on Items; further fields are conditionally required.
  2. Reuse before reinvention — citation, grids, tables, CRS, ML models, file checksums, and geometry anonymization stay in existing extensions (see Reused extensions). Examples demonstrate a subset; apply additional extensions when the asset type needs them.
  3. Privacy fields are first-class — GDPR/access and statistical disclosure-control fields are defined in-schema. They are not always required: national open aggregates may honestly use minimum_cell_size: 1 with suppression_method: none. Use a real suppression method (and cell size ≥ your rule) when small-area cells are protected — see the suppressed fixture example.
  4. Surveillance is versioned — provisional counts are revised; vintage fields and byte-pinned assets make nowcasts reproducible.

Fields

The fields in the table below can be used in these parts of STAC documents:

  • Catalogs
  • Collections
  • Item Properties (incl. Summaries in Collections)
  • Assets (for both Collections and Items, incl. Item Asset Definitions in Collections)
  • Links
Field Name Type Description
health:data_type Data Type REQUIRED (Item). Semantic class of the record.
health:disease_codes [string] ICD-10/11 (or equivalent) disease/condition codes. Conditionally required for non-covariate Items unless pathogen_taxon_ids is set (model outputs may omit both when the target is declared elsewhere).
health:pathogen_taxon_ids [string] NCBI Taxonomy IDs (or CURIE form). Alternative or complement to disease codes.
health:spatial_unit string Spatial reporting unit (e.g. NUTS3, NUTS2, LAU, MSOA, grid_1km, national).
health:spatial_unit_version string Classification vintage of spatial_unit (e.g. NUTS2021, NUTS2024, LAU2023).
health:reference_date_type Reference Date Type Which event the temporal properties refer to.
health:reporting_lag_days Reporting Lag Object Days between the reference event and data availability.
health:temporal_resolution Temporal Resolution Reporting cadence.
health:week_system Week System REQUIRED when temporal_resolution is weekly.
health:spatial_coverage [string] ISO 3166-1 alpha-3 country codes (typically Collection-level).
health:access_level Access Level How the data may be obtained.
health:gdpr_status GDPR Status Privacy / identifiability class of the payload.
health:minimum_cell_size integer (≥ 1) REQUIRED when gdpr_status is aggregated_published or anonymised. Threshold used for statistical disclosure control — see minimum cell size.
health:suppression_method Suppression Method REQUIRED when gdpr_status is aggregated_published or anonymised.
health:population_denominator Population Denominator Object REQUIRED when data_type is incidence_rate or mortality_rate.
health:vector_species [string] GBIF or NCBI taxon IDs for vector species (vector-borne use cases).
health:sex_disaggregated boolean Whether sex-disaggregated values are present.
health:age_bands_available [string] Age-band labels present in the data.
health:completeness_score number Fraction of expected records present (0–1).
health:surveillance_type Surveillance Type How cases are ascertained.
health:case_definition_url string (URI) Case-definition document.
health:data_source_system string Surveillance system or registry (e.g. ecdc_tessy, ukhsa, gbif).
health:ascertainment_note string Known under-reporting or ascertainment bias.
health:data_use_agreement_url string (URI) DUA / licence process for controlled data.
health:data_controller string Data controller (and optionally DPO contact).
health:countermeasures_period boolean Whether NPIs or vaccination campaigns were active in the period.
health:outbreak_phase Outbreak Phase Epidemic phase label for the period.
health:data_version string Publisher version / release tag for this snapshot.
health:data_as_of string (RFC 3339) Vintage datetime when this snapshot was current at the source.
health:revision_status Revision Status provisional / revised / final.
health:uncertainty_type Uncertainty Type How uncertainty is represented for model_output assets.
health:bias_evaluation_url string (URI) Bias evaluation (e.g. sex, age, geography) for health AI outputs.

Collection placement: health:spatial_coverage, health:access_level, health:data_use_agreement_url, and health:data_controller are typically set on the Collection as catalogue defaults. STAC does not inherit Collection properties onto Items — repeat or override fields on each Item (and use Collection summaries for discovery). Summaries SHOULD list the health:data_type and health:disease_codes (or pathogen) values present in member Items.

Additional Field Information

health:data_type

Discriminates outcome, determinant, and prediction assets so one extension can cover all three without separate namespaces. Covariate Items SHOULD use only light health tagging (data_type plus optional disease/pathogen keywords for discoverability); grid structure belongs in Datacube / Raster / Projection.

health:disease_codes and health:pathogen_taxon_ids

Prefer stable vocabularies (ICD-10/11, NCBI Taxonomy). At least one of these arrays is required for Items whose data_type is not covariate, except model_output Items that declare their target via linked training labels or Collection summaries.

health:spatial_unit and health:spatial_unit_version

Administrative units change. A multi-year TESSy series can span several NUTS revisions; omitting the vintage silently breaks joins.

health:week_system

ISO weeks, ECDC epi weeks, and CDC MMWR weeks can disagree by up to a week at year boundaries. Required whenever temporal_resolution is weekly.

Privacy and disclosure control

health:gdpr_status describes the payload, not only the licence. Labels are GDPR-oriented (common for EU/EHDS catalogues) but the field is usable as a general privacy/identifiability class elsewhere. When data are aggregated or anonymised for release, health:minimum_cell_size and health:suppression_method are required so disclosure control is explicit. For coarse geometries, also consider the Anonymized Location extension (anon:size, anon:warning).

health:minimum_cell_size

The smallest count (or count-equivalent cell) the publisher allows to appear in the released table or map. It is the threshold used by statistical disclosure control, not a description of the geographic unit size.

  • Unit: dimensionless integer count of observations/cases (or the same quantity the cells store). It is not kilometres, hectares, or population. Geographic coarseness belongs in health:spatial_unit / geometry / anon:.
  • Semantics with health:suppression_method:
    • primary_only / complementary / k_anonymity: cells whose raw count is strictly below this value are suppressed, rounded away, or otherwise protected according to the method.
    • rounding: often the rounding base or banding width expressed as a count (document the exact rule in description if it is not “round to multiples of n”).
    • none: no disclosure control was applied. Use minimum_cell_size: 1 to mean “every positive count may be published,” which is typical for coarse national aggregates.
  • Required when: gdpr_status is aggregated_published or anonymised (schema conditional). Omit both this field and suppression_method when those statuses are not used.
  • Examples in this repo: ECDC national daily CSV uses 1 + none (no small-cell rule). The illustrative NUTS-3 fixture uses 5 + primary_only (counts below 5 replaced with NA).

Surveillance vintage

health:data_version, health:data_as_of, and health:revision_status make each ingested snapshot reproducible. Prefer byte-pinned assets (file:checksum, commit-pinned or repository-hosted snapshots) over mutable portal URLs for provisional vintages. Prefer STAC link relation predecessor-version when an Item supersedes an earlier snapshot, and derived_from from model-output Items back to the surveillance or observation Items used as labels.

Model outputs and embeddings

Describe the model with the Machine Learning Model (MLM) extension and scientific citations with Scientific. This extension only adds health-specific prediction metadata: health:uncertainty_type and health:bias_evaluation_url (set the latter when a bias/fairness evaluation is published).

Geospatial foundation-model embedding tensors (dimensions, chip layout, inference runtime, quantization, emb:source-data / emb:model links) are out of scope for health:. Use the community Embedding extension (emb: prefix; Proposal) together with MLM for the encoder. A health catalogue Item that uses embeddings as features still declares health:data_type (covariate or model_output as appropriate) and links to the embedding Items/Collections.

Data Type

Value Meaning
case_reports Case counts or line-list aggregates
incidence_rate Incidence rates (requires population denominator)
mortality Death counts
mortality_rate Mortality rates (requires population denominator)
hospitalisation Hospital admission / occupancy metrics
seroprevalence Serological prevalence
syndromic_surveillance Syndromic indicators
environmental_sampling Pathogen detection in environment
vector_occurrence Vector presence / abundance
covariate Environmental or socio-demographic determinant
model_output Predicted risk, nowcast, or similar product

Reference Date Type

Which event the Item’s temporal properties (datetime / start_datetime–end_datetime) refer to.

Value Meaning
symptom_onset Date of first symptoms (or equivalent clinical onset)
diagnosis Date of clinical or laboratory diagnosis
notification Date the case was notified to the surveillance system
death Date of death
specimen_collection Date the specimen / sample was collected
other Another reference event; explain in description or health:ascertainment_note

Temporal Resolution

Reporting or aggregation cadence of the values in the asset.

Value Meaning
event Individual events or irregular timestamps (not a fixed calendar bin)
daily One value (or row set) per calendar day
weekly One value per epidemiological or calendar week (see health:week_system)
monthly One value per calendar month
quarterly One value per calendar quarter
annual One value per calendar year
multi_year Values aggregated or labelled over a span longer than one year
other Another cadence; explain in description

Week System

Week-numbering convention when health:temporal_resolution is weekly.

Value Meaning
iso_8601 ISO 8601 weeks (Monday start; week 1 contains the year’s first Thursday)
ecdc ECDC / TESSy epidemiological weeks (aligned with ISO 8601 in current ECDC practice; declare explicitly for clarity)
mmwr US CDC MMWR weeks (Sunday start; week 1 rules differ from ISO)

Access Level

How a consumer may obtain the asset (independent of privacy class).

Value Meaning
open Freely downloadable without registration
registered Requires account / registration, but no further approval gate
controlled_access Requires application, DUA, or equivalent approval before download
consortium_only Restricted to a named project, consortium, or partnership

GDPR Status

Privacy / identifiability class of the payload (not only the licence). GDPR-oriented labels; usable as a general privacy class outside the EU.

Value Meaning
open_data Non-personal or otherwise published as open data with no residual identifiability concern under the publisher’s assessment
aggregated_published Aggregated statistics released publicly (may still need disclosure control — see suppression fields)
anonymised Treated as anonymised for release under the publisher’s assessment (irreversible under that assessment)
pseudonymised Identifiers replaced or coded; re-identification possible with additional information held separately
restricted_identifiable Contains personal data or is otherwise not safe for open release

Suppression Method

Statistical disclosure control applied to counts (or equivalent cells) when gdpr_status is aggregated_published or anonymised.

Value Meaning
none No cell suppression or other disclosure control applied
primary_only Small cells below minimum_cell_size are suppressed (e.g. set to NA); no further complementary steps
complementary Primary suppression plus secondary/complementary suppression to prevent differencing
rounding Values are rounded (or banded) to reduce disclosure risk
k_anonymity Release satisfies a stated k-anonymity (or similar) threshold; document k in description if not obvious

Surveillance Type

How cases or observations enter the reporting system.

Value Meaning
universal_mandatory Legal or regulatory duty to report all qualifying cases in the covered population
sentinel Selected sites / providers report; not designed as complete population coverage
voluntary Reporting is voluntary (no mandate)
passive Relies on routine notifications without active case-finding
active Includes active case-finding, outreach, or stimulated reporting
other Another ascertainment design; explain in description or health:ascertainment_note

passive / active may combine with the others (e.g. mandatory + passive). Prefer the primary organisational design in this field and put nuance in health:ascertainment_note.

Outbreak Phase

Epidemic context for the period covered by the Item (publisher judgement).

Value Meaning
endemic_baseline Transmission at expected endemic / baseline levels
emerging Early growth or first detection relative to baseline
epidemic_peak Around the peak of an epidemic wave
declining Clear decline from a recent peak
unknown Phase not assessed or not applicable

Revision Status

Lifecycle of this catalogue snapshot relative to the source series.

Value Meaning
provisional Subject to change; counts or extents may be revised
revised Updated after an earlier provisional (or prior revised) release
final Publisher treats this snapshot as final for the stated period

Uncertainty Type

How uncertainty is represented on model_output (or similar prediction) assets.

Value Meaning
none Point estimate / single surface only; no uncertainty layer in this Item
prediction_interval Frequentist-style prediction or confidence intervals (or equivalent interval rasters/tables)
posterior_variance Bayesian posterior variance / credible intervals (or equivalent)
ensemble_spread Spread across ensemble members (e.g. SD, range, quantiles of members)

Reporting Lag Object

Field Name Type Description
min number REQUIRED. Minimum lag in days.
max number REQUIRED. Maximum lag in days (max MUST be ≥ min).

Population Denominator Object

Field Name Type Description
source string REQUIRED. Population dataset or statistic (e.g. eurostat, worldpop).
vintage_year integer REQUIRED. Reference year of the population figures.
value number Optional scalar denominator when a single value applies.

Relation types

Use STAC-native link relations rather than custom health relation types:

Type Description
predecessor-version Prior surveillance snapshot superseded by this Item
successor-version Newer revision of this snapshot
derived_from Model-output or processed Item derived from this Item
cite-as Canonical citation landing page (with sci: fields)

Reused extensions

Concern Extension Notes
Citation / DOI scientific sci:doi, sci:citation, sci:publications
Class labels classification Risk categories, outbreak-phase codings in rasters
Tabular / GeoParquet schema table Column names and dtypes
Multi-dimensional arrays datacube cube:dimensions / variables
CRS / grid projection proj:code, shape, transform
File size / checksum file file:checksum, size
Processing lineage processing Processing graph / facility
Auth to assets authentication Controlled-access download flows
Coarse geometry anonymized-location anon:size, anon:warning
ML model cards / runtime mlm Model identity, artifacts, training refs
Geospatial embeddings emb (Embedding) FM embedding products (emb:dimensions, chip layout, inference provenance); do not fold into health:

HealthDCAT-AP / EHDS

Catalogues that also publish HealthDCAT-AP / EHDS secondary-use records can map from these fields (and core STAC) in a companion profile. That crosswalk is not part of this JSON Schema. Pin the HealthDCAT-AP version used by any catalogue export in the deploying project's documentation.

Contributing

All contributions are subject to the STAC Specification Code of Conduct. For contributions, please follow the STAC specification contributing guide. Instructions for running tests are copied here for convenience.

Running tests

The same checks that run as checks on PR's are part of the repository and can be run locally to verify that changes are valid. To run tests locally, you'll need npm, which is a standard part of any node.js installation.

First you'll need to install everything with npm once. Just navigate to the root of this repository and on your command line run:

npm ci

Then to check markdown formatting and test the examples against the JSON schema, you can run:

npm test

This will spit out the same texts that you see online, and you can then go and fix your markdown or examples.

If the tests reveal formatting problems with the examples, you can fix them with:

npm run format-examples

About

STAC Health Extension — metadata for geospatial public-health and epidemic-intelligence datasets (surveillance, covariates, model outputs), with privacy and vintage fields. Proposal.

Topics

epidemiologygeospatialjson-schemametadatapublic-healthstacstac-extension

Resources

Readme
Apache-2.0 license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Generated from stac-extensions/template