Metadata-Version: 2.4
Name: sdchealthdcatap
Version: 4.1.0
Summary: Describe published Semantic Data Charter models' governed data records in a HealthDCAT-AP (Release 8) catalog.
Author: Axius SDC, Inc.
License: Apache-2.0
Project-URL: Homepage, https://github.com/SemanticDataCharter/sdc_healthdcat_ap
Keywords: healthdcat-ap,dcat-ap,ehds,healthdata-eu,sdc,fair,mcp
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: sdcreader<5,>=4.2
Requires-Dist: lxml>=5.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rdflib>=7.0
Provides-Extra: fetch
Requires-Dist: sdcreader<5,>=4.2; extra == "fetch"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: requests>=2.31; extra == "dev"
Requires-Dist: pyshacl>=0.26; extra == "dev"
Dynamic: license-file

# sdc_healthdcat_ap

<!-- mcp-name: io.github.SemanticDataCharter/sdchealthdcatap -->

One Semantic Data Charter model, described in HealthDCAT-AP.

`sdchealthdcatap` reads a published SDC model's package and writes the `dcat:Dataset` description that HealthDCAT-AP,
the health extension of DCAT-AP for the secondary use of health data under the European Health Data Space, asks a
data holder to publish into the HealthData@EU catalogue: one Dataset per model at a declared access level, its variables as a CSVW
table group built from the record's leaves, its coding systems from the model's bindings, and the holder's facts from
declared input. One rdflib graph, serialized as Turtle and as JSON-LD. The output is checked with the HealthData@EU
validator's own shape set for the level, at a pinned commit of the specification's repository.

## 1. What this is, and where it came from

The sample, `samples/nhanes-participant/catalog.ttl` (and `catalog.jsonld`, the same graph), is one Dataset at the
`NON_PUBLIC` access level, with no catalogue wrapper, as the release's own examples are (part 4 says why): the records of **NHANES Participant** (`dm-xy8upneajsb8vdcmnve01g6g`) from
the FAIR Data Demo, a demographic, examination and laboratory record of the National Health and Nutrition
Examination Survey (CDC), 9,254 records, one per participant. The model is public:

- the catalog record: https://sdcstudio.axius-sdc.com/api/v1/catalog/dm/xy8upneajsb8vdcmnve01g6g/
- the schema the records conform to: https://sdcstudio.axius-sdc.com/dmlib/dm-xy8upneajsb8vdcmnve01g6g.xsd
- the Semantic Data Charter: https://semanticdatacharter.com

```
pip install -e ".[fetch]"
sdchealthdcatap write --package samples/nhanes-participant --out catalog.ttl --jsonld catalog.jsonld
sdchealthdcatap write --ct-id xy8upneajsb8vdcmnve01g6g --save-package pkg/ --out catalog.ttl     # any published model, from the public catalog
sdchealthdcatap write --package DIR --catalog my-catalog.yaml --out catalog.ttl                  # a data holder's own declared input
```

**Two kinds of input, kept apart.** From the model's package (its JSON-LD, its schema, the public catalog record and
the published schema versions; no account needed; a model without a package is refused): title, description,
identifier, creator, dates, licence, the schema's URL and SHA-256, **every leaf of the record** for the variables,
**every concept system the model binds to** for the coding systems, and the model's own Dublin Core when the
modeler wrote it. From the data holder, declared in `catalog.yaml` because the profile asks for facts only a holder
has and for values from the DG SANTE and EU vocabularies: the access level, the health data access body, the
applicable legislation, the health category and theme, the dataset type, the distribution that is the access
route, the counts of records and individuals, typical ages, population coverage, personal-data categories, legal
basis, purpose, the publisher's type, the contact point. The package ships the sample's file
(`src/sdchealthdcatap/data/catalog.yaml`); a holder supplies its own.

**The data dictionary is a slot here.** `healthdcatap:hasVariables` takes a `csvw:TableGroup`; the writer builds one
table with one `csvw:Column` per leaf of the record, 153 for NHANES Participant: `csvw:name` the leaf's path in the
record, `csvw:title` its label, `csvw:datatype` its XSD type, `dct:description` its definition, `csvw:propertyUrl`
its library slot (the identifier that says what the variable means wherever it is reused), `dct:identifier` its
element name. `healthdcatap:hasStructuredData` is `true`. `healthdcatap:hasCodingSystem` carries SNOMED CT, LOINC
and NCIT from the Coding System NAL, derived from the model's `skos:exactMatch` bindings by IRI prefix.

What else the Dataset carries:

| | |
|---|---|
| `dct:title`, `dct:description`, `dct:identifier`, `adms:identifier`, `dcat:keyword`, `dcat:landingPage`, `dct:issued`, `dct:modified`, `dct:language`, `dct:license`, `dct:provenance`, `dcat:version` | as the DCAT-AP writer does, from the package |
| `dct:accessRights` | `NON_PUBLIC` from the Access Rights NAL (declared; it selects the validator's shape set) |
| `dcatap:applicableLegislation` | the EHDS Regulation's ELI, `http://data.europa.eu/eli/reg/2025/327/oj`, on the Catalog, the Dataset and the Distribution (declared) |
| `healthdcatap:hdab`, `geodcatap:custodian` | the publisher, a `foaf:Agent` with a `cv:ContactPoint` and a type from the Health Publisher Types NAL (declared; see part 3) |
| `healthdcatap:healthCategory`, `healthdcatap:healthTheme`, `dct:type`, `dcat:theme` | `RQSH` (research cohorts, questionnaires and surveys), noncommunicable diseases, `STATISTICAL`, `HEAL` (declared) |
| `dcat:distribution` | the access route: title, description, `dcat:accessURL`, availability, the legislation, the licence, and `dct:conformsTo` the schema as a `dct:Standard` by its pinned URL |
| `foaf:page` | the schema at its stable URL, described as the data dictionary |
| `healthdcatap:numberOfRecords`, `numberOfUniqueIndividuals`, `minTypicalAge`, `maxTypicalAge`, `populationCoverage` | 9,254; 9,254; 0; 80; the NHANES population (declared) |
| `dpv:hasPersonalData`, `dpv:hasLegalBasis`, `dpv:hasPurpose` | age, gender and health record from the DPV personal-data taxonomy; the basis and purpose as text (declared) |
| `dqv:hasQualityAnnotation` | a `dqv:QualityCertificate` whose body is the schema: every record is validated against it before it exists |

Every NAL concept the graph uses states its scheme (`skos:inScheme`), and every scheme is typed and titled, because
the validator's codelist shapes check membership that way. Every agent is typed and named, with a contact point.

## 2. How to verify it

The tests run the HealthData@EU validator's own configuration from `data/healthdcat-ap-r8-cd7841f/validator/`
(`build/snapshot_healthdcat_ap.py` verifies the pin first): `config.properties` names the shape files per access
level, and the tests load exactly those for the declared level, plus SEMIC's DCAT-AP 3.0.1 shapes as the release
ships them, plus the thirteen vocabularies the codelist shapes name, which the validator preloads as background:

```
pip install -e ".[dev]"
python -m pytest tests -q
```

Result at the pin, `NON_PUBLIC`, in Turtle and in JSON-LD: **0 violations, 10 warnings**, the recommended
properties the package does not carry (analytics, retention period, frequency, `dct:conformsTo` on the Dataset,
references, relations, source, temporal coverage and resolution, a sample). The committed samples are asserted
isomorphic to a fresh run. The release's own ARCA example, run the same way at `PUBLIC`, passes except where the
background we carry stops (part 4).

Second witness, the Interoperability Test Bed, which the specification's validation section names as where the
shape and import files "can be loaded": its generic SHACL validator (https://www.itb.ec.europa.eu/shacl/any/upload,
REST API `/shacl/any/api/validate`) given the release's non-public shape files as external rules, 9 October 2026:
**no violation on any node of the document, 14 warnings** (the ten above, plus `dct:format` on the distribution,
`dct:spatial`, and `dct:type` on the creator agent and the licence document). The 22 violations it also reports fall
on nodes the Test Bed carries itself, six ADMS concept schemes without a title and five unnamed blank agents, each
twice, the same an empty catalog receives on its DCAT-AP domain. The network-marked test asserts the first part;
CI skips it. The HealthData@EU platform's own validator page was not reachable: both the production and the
acceptance platforms answer 404 at the validator path, and the platform's public pages do not link one.

## 3. What the projection could not say

Declared rather than read from the package, and said so here:
- **The health data access body is the publisher.** The field is mandatory at every level and no EU body holds
  this dataset. The sample names Axius SDC, Inc., with its contact point, as the body that grants access, which is
  true of the FAIR Data Demo and would be replaced by the real body for a dataset inside the EHDS.
- **The applicable legislation is the EHDS Regulation**, as the profile's usage note recommends, for a dataset the
  Regulation does not govern. It is the profile's required way of saying "described for the EHDS framework."
- **The counts, ages, population, personal-data categories, legal basis and purpose** are the holder's statements
  about the FAIR Data Demo's generation run and the NHANES source, not facts the package carries.
- **The distribution is a route, not a file.** The records are not published; the access route is the contact
  page. A holder with a download or a data service replaces it.

Left out: retention period, analytics distribution, sample distribution, frequency, temporal coverage, relations.
The package does not carry them, and the profile recommends rather than requires them.

In the other direction, what the record carries that the catalog entry only points at:
- **The governance envelope is data in every record**, an audit event, a PROV activity and a PROV agent, validated
  with the rest. The columns for them are in the table group, so a reader can see they exist; the values are in the
  records.
- **The schema is bound to each record**, and cited here on the distribution and the page by URL and SHA-256.
- **The reason a value is missing is typed in the record.** The table group's description says every column may
  carry one of sixteen exceptional values; which one applies, and where, is in the record.

## 4. What we learned about HealthDCAT-AP Release 8 and its validator

Implementer's notes from building this against `healthdataeu/healthdcat-ap` at cd7841f on 9 October 2026. They
describe how the artifacts behave, so the next implementer spends the day on their own catalog rather than on these.

- **The document is the Dataset, not a Catalogue.** The release's examples are dataset-only, and the reason shows
  under validation: with DCAT loaded as background (`dcat:Catalog` is a subclass of `dcat:Dataset`), a validator
  reads a `dcat:Catalog` node as a Dataset and holds it to the Dataset's mandatory list, eleven violations on the
  wrapper alone (contact point, distribution, keyword, theme, access rights, identifier, provenance, type, health
  category, access body, the structured-data flag). The writer emits no Catalogue; the HealthData@EU catalogue is
  the catalogue.
- **The validator ships with the release, configured.** `html/shacl/HealthDCAT-AP_validator/config/rdf-validator/ehds/`
  holds `config.properties`, which names the shape files per access level, and the vocabularies and ontologies the
  validator preloads. Running that file set with pySHACL is running the validator's logic; the hosted instance adds
  background knowledge and a web interface.
- **Membership in a vocabulary is checked through `skos:inScheme`.** Every codelist restriction asks the concept for
  `skos:inScheme <the scheme>`, several also ask the scheme to be a typed `skos:ConceptScheme`, and SEMIC's base
  shapes then ask every scheme in the graph for a `dct:title`. The hosted validator preloads the vocabularies, which
  supply the `inScheme`; offline, either load them or state them. The writer states them for every concept it uses,
  and the tests load the thirteen vocabularies anyway, which is why the release's ARCA example passes offline
  except for its language (the Languages NAL is 14 MB and stays out) and its licence type (the ADMS scheme is not
  among the preloads).
- **`dct:conformsTo` on a Dataset is closed to the Technical Standard NAL** (FHIR, OMOP-CDM, openEHR, DICOM, CDISC
  SDTM and about twenty more), at violation level. A schema of one's own cannot go there; the writer cites it on
  the distribution, which has no such restriction, and on `foaf:page`.
- **A health publisher is an agent with exactly one `cv:ContactPoint`** (Core Public Service vocabulary, not vCard)
  and a type from the Health Publisher Types NAL; the Dataset's contact point is a `vcard:Kind` with an e-mail or a
  URL. Two contact-point vocabularies in one document, each where its shape asks.
- **Coding systems must be `dct:Standard`s as well as concepts.** The range shapes ask `healthdcatap:hasCodingSystem`
  for `dct:Standard`; the codelist shapes ask for `skos:inScheme` the Coding System NAL. Both at once.
- **Three path-less property shapes** (a `vcard:Kind`'s "e-mail or URL", a `cv:ContactPoint`'s "e-mail or page",
  written as `sh:or` without `sh:path`) stop pySHACL; the tests drop them and assert both by hand. The range file
  references property shapes it does not define, as DCAT-AP's does.
- **pySHACL reports nested results.** A failed `sh:node` yields the outer result at the property's severity and the
  inner results under `sh:detail` at their own; a Jena-based validator reports the outer one. The tests fold the
  nested ones into their parent, so a warning on the Catalog's publisher stays a warning.
- **The Catalog's publisher is checked twice, against two vocabularies.** DCAT-AP's codelist shape wants the
  Catalog's publisher type from the ADMS publisher-type scheme (a warning); HealthDCAT-AP's wants the Dataset's
  publisher type from the Health Publisher Types NAL (a violation). One agent in both roles satisfies the second and
  warns on the first.
- **`csvw:column` is used as a plain repeated property** in the release's examples and shapes, not as the
  `rdf:List` the CSVW specification defines; column names need to be unique in the table, so a component composed
  three times (the blood pressure readings) gets three columns named by path.
- **Release 8's `CHANGELOG.md` and root `shacl/` are DCAT-AP 3.0.1's**, unchanged; the HealthDCAT-AP shapes live
  only under the validator configuration path.

## MCP server

`sdchealthdcatap` is also an MCP server, registered as `io.github.SemanticDataCharter/sdchealthdcatap`, so an assistant that can read a
published model with `sdcreader` can ask for its HealthDCAT-AP description. One tool, `write_catalog`, over the same
function the CLI calls; stdio; read-only apart from the document it returns; no account; no tool takes a URL (the
catalog host is fixed at start with `--host`). The protocol scaffold is `sdcreader.mcp`, shared by every SDC
projection server.

```
uvx sdchealthdcatap mcp            # or: sdchealthdcatap-mcp, or sdchealthdcatap mcp
```

## Layout

- The model's package is read with [`sdcreader`](https://github.com/SemanticDataCharter/sdcreader) (`load_package`,
  `fetch_package`, `read_model`): the record tree, its leaves, the enumerated values with their codes, the model's
  Dublin Core with SDCStudio's defaults as unset. The package format is documented there, once.
- `src/sdchealthdcatap/`: `dcatap.py` (the DCAT-AP graph builder, reused from `sdc_dcat3_ap`), `healthdcatap.py` (the
  health layer and the table group), `validate.py` (the validator's shape set with pySHACL), `cli.py`, `data/catalog.yaml`
  (the declared input for the sample).
- `data/healthdcat-ap-r8-cd7841f/`: the release's shapes, context, validator configuration with the vocabularies the
  shapes name, and examples, at the pin.
- `samples/nhanes-participant/`: the model's package as fetched and the catalog written from it, in Turtle and JSON-LD.
- `build/snapshot_healthdcat_ap.py`: re-creates `data/` from a read-only clone at the pinned commit.

## Licences

Apache-2.0 (see `LICENSE`, `NOTICE`). The HealthDCAT-AP artifacts in `data/` are CC BY 4.0 and keep that licence here.
