sdcreader 4.0.0__tar.gz

sdcreader-4.0.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

sdcreader-4.0.0/NOTICE

@@ -0,0 +1,9 @@
+sdcreader
+Copyright 2026 Axius SDC, Inc.
+
+Licensed under the Apache License, Version 2.0.
+
+The test fixture under samples/nhanes-participant/ is the published package of the NHANES Participant model of the
+FAIR Data Demo (https://github.com/SemanticDataCharter/FAIR_Data_Demo), fetched from SDCStudio's public catalog, a
+Semantic Data Charter model of National Health and Nutrition Examination Survey (CDC) variables; it is used as
+evidence, unchanged.

sdcreader-4.0.0/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: sdcreader
+Version: 4.0.0
+Summary: Read a published Semantic Data Charter model's package for projection into other standards (CDIF, DCAT-US, DCAT-AP, HealthDCAT-AP).
+Author: Axius SDC, Inc.
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/SemanticDataCharter/sdcreader
+Project-URL: Changelog, https://github.com/SemanticDataCharter/sdcreader/blob/main/CHANGELOG.md
+Keywords: sdc,semantic data charter,governed data record,cdif,dcat,dcat-ap,healthdcat-ap,fair
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: lxml>=5.0
+Provides-Extra: fetch
+Requires-Dist: requests>=2.31; extra == "fetch"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: requests>=2.31; extra == "dev"
+Dynamic: license-file
+
+# sdcreader
+
+Read a published Semantic Data Charter model's package for projection into other standards.
+
+A projection describes a model's governed data records in another standard's terms: CDIF, DCAT-US 3.0, DCAT-AP
+3.0.1, HealthDCAT-AP, and whatever comes next. What every projection describes is the same evidence, the model's
+package, and reads it into the same shape. `sdcreader` is that evidence and that shape, once, with nothing about
+any projection in it. The four projection writers (`sdc_cdif`, `sdc_dcat3_us`, `sdc_dcat3_ap`, `sdc_healthdcat_ap`)
+carried it as identical copies until this package.
+
+```
+pip install sdcreader            # or, until the PyPI release: pip install "sdcreader @ git+https://github.com/SemanticDataCharter/sdcreader@v4.0.0"
+pip install "sdcreader[fetch]"   # with HTTP, to fetch a package from the public catalog
+```
+
+```python
+from sdcreader import fetch_package, load_package, read_model
+
+pkg = load_package("samples/nhanes-participant")          # a package on disk
+pkg = fetch_package("xy8upneajsb8vdcmnve01g6g", save_to="pkg/")   # or from SDCStudio's public catalog, no account
+model = read_model(pkg)
+
+pkg.schema_url_pinned        # https://sdcstudio.axius-sdc.com/dmlib/dm-xy8u...xsd?sha256=0df4...   the exact bytes the records are validated against
+model.title, model.leaves    # 'NHANES Participant', 153 leaves in document order, each with its path of clusters
+model.codes[ct_id]           # the enumerated values of a component with the IRI, definition and code the schema annotates them with
+model.dc("publisher")        # what the modeler wrote, None where SDCStudio's default sits
+```
+
+## What a package is
+
+SDCStudio generates a package for every published model and serves it publicly for models in public projects:
+
+| | |
+|---|---|
+| `GET /api/v1/catalog/dm/<ct>/` | the catalog record: title, description, project, the artifact list (`catalog.json`) |
+| `GET /api/v1/catalog/dm/<ct>/<artifact>/` | a storage pointer, `{"download_url": ..., "filename": ..., "storage": "gcs"}`, for `jsonld`, `xsd` and the rest; the reader follows it |
+| `dm-<ct>.jsonld` | the model and its components: type, label, description, cardinality, constraints (enumerations, units, ranges, patterns), semantic links (`dcterms:identifier` the library slot, `dcterms:source`, `dcterms:publisher`, `skos:exactMatch`, `rdfs:seeAlso`, `prov:wasRevisionOf`), `contains` |
+| `GET /dmlib/dm-<ct>.xsd` | the schema bytes: the Dublin Core header for the model, and for each enumerated value its definition and the code it is defined by (`dm-<ct>.xsd`) |
+| `GET /dmlib/dm-<ct>.versions.json` | every published version of the schema by SHA-256, with the current one (`versions.json`) |
+
+A package directory holds those four files. The reader refuses a directory without the JSON-LD and the schema, a
+JSON-LD whose identifier is not the directory's model, and a schema whose bytes are not the published current
+version: a projection cites the schema by URL and SHA-256, so the bytes have to be the ones that URL serves.
+
+Two gaps in the package are on SDCStudio's issue tracker: the JSON-LD metadata drops fields the schema header
+carries (#748), and the header omits `dc:source` (#749). The reader takes the model's Dublin Core from the header,
+which is complete.
+
+## What the reader gives
+
+- **`ModelPackage`**: the four files, the SHA-256, the schema URL and its pinned form (`?sha256=`), the public
+  catalog URL, and `check()`.
+- **`Model`**: `title`, `description`, `root` (the governed record's cluster), `components` by identifier, `leaves`
+  in document order (each a `Leaf` with its `component`, its `path` of clusters and a `slug` of that path, unique in
+  the record), `codes` (the enumerated values per component as `Code`: value, IRI, definition, the code it is
+  defined by), `metadata` (the JSON-LD's) and `header` (the schema's Dublin Core).
+- **`Model.dc(name)`**: what the modeler wrote, the header first and the JSON-LD second, with SDCStudio's field
+  defaults as unset: "Universal" for coverage, "None" for relation, "SDC Data Model (DM)" for type, blanks. A
+  projection never publishes a default as a fact. `contributors`, `subjects` (the semicolon list), `rights_url` and
+  `rights_statement` derive from it.
+- **`Component`**: `sdc_type`, `label`, `description`, `data_type`, `constraints`, `links` by predicate (`link(p)` for
+  the first), `contains`, `iri`.
+- Constants: the leaf, numeric and quantified types; the predicate IRIs `IDENTIFIER`, `SOURCE`, `PUBLISHER`, `EXACT`,
+  `CLOSE`, `SEE_ALSO`, `HAS_UNIT`; `DC_DEFAULTS`.
+
+## Tests
+
+```
+pip install -e ".[dev]"
+python -m pytest tests -q                    # includes one fetch against production
+python -m pytest tests -q -m "not network"   # offline, as CI runs it
+```
+
+The fixture is the NHANES Participant package of the FAIR Data Demo, the record every projection is proven on.
+
+## Versioning
+
+The leading 4 is the SDC4 reference model, as with every Semantic Data Charter package. An addition to what the
+reader exposes is a minor version, a fix a patch; the major changes only when the reference model does.
+
+## Licence
+
+Apache-2.0 (see `LICENSE`, `NOTICE`).

sdcreader-4.0.0/README.md

@@ -0,0 +1,83 @@
+# sdcreader
+
+Read a published Semantic Data Charter model's package for projection into other standards.
+
+A projection describes a model's governed data records in another standard's terms: CDIF, DCAT-US 3.0, DCAT-AP
+3.0.1, HealthDCAT-AP, and whatever comes next. What every projection describes is the same evidence, the model's
+package, and reads it into the same shape. `sdcreader` is that evidence and that shape, once, with nothing about
+any projection in it. The four projection writers (`sdc_cdif`, `sdc_dcat3_us`, `sdc_dcat3_ap`, `sdc_healthdcat_ap`)
+carried it as identical copies until this package.
+
+```
+pip install sdcreader            # or, until the PyPI release: pip install "sdcreader @ git+https://github.com/SemanticDataCharter/sdcreader@v4.0.0"
+pip install "sdcreader[fetch]"   # with HTTP, to fetch a package from the public catalog
+```
+
+```python
+from sdcreader import fetch_package, load_package, read_model
+
+pkg = load_package("samples/nhanes-participant")          # a package on disk
+pkg = fetch_package("xy8upneajsb8vdcmnve01g6g", save_to="pkg/")   # or from SDCStudio's public catalog, no account
+model = read_model(pkg)
+
+pkg.schema_url_pinned        # https://sdcstudio.axius-sdc.com/dmlib/dm-xy8u...xsd?sha256=0df4...   the exact bytes the records are validated against
+model.title, model.leaves    # 'NHANES Participant', 153 leaves in document order, each with its path of clusters
+model.codes[ct_id]           # the enumerated values of a component with the IRI, definition and code the schema annotates them with
+model.dc("publisher")        # what the modeler wrote, None where SDCStudio's default sits
+```
+
+## What a package is
+
+SDCStudio generates a package for every published model and serves it publicly for models in public projects:
+
+| | |
+|---|---|
+| `GET /api/v1/catalog/dm/<ct>/` | the catalog record: title, description, project, the artifact list (`catalog.json`) |
+| `GET /api/v1/catalog/dm/<ct>/<artifact>/` | a storage pointer, `{"download_url": ..., "filename": ..., "storage": "gcs"}`, for `jsonld`, `xsd` and the rest; the reader follows it |
+| `dm-<ct>.jsonld` | the model and its components: type, label, description, cardinality, constraints (enumerations, units, ranges, patterns), semantic links (`dcterms:identifier` the library slot, `dcterms:source`, `dcterms:publisher`, `skos:exactMatch`, `rdfs:seeAlso`, `prov:wasRevisionOf`), `contains` |
+| `GET /dmlib/dm-<ct>.xsd` | the schema bytes: the Dublin Core header for the model, and for each enumerated value its definition and the code it is defined by (`dm-<ct>.xsd`) |
+| `GET /dmlib/dm-<ct>.versions.json` | every published version of the schema by SHA-256, with the current one (`versions.json`) |
+
+A package directory holds those four files. The reader refuses a directory without the JSON-LD and the schema, a
+JSON-LD whose identifier is not the directory's model, and a schema whose bytes are not the published current
+version: a projection cites the schema by URL and SHA-256, so the bytes have to be the ones that URL serves.
+
+Two gaps in the package are on SDCStudio's issue tracker: the JSON-LD metadata drops fields the schema header
+carries (#748), and the header omits `dc:source` (#749). The reader takes the model's Dublin Core from the header,
+which is complete.
+
+## What the reader gives
+
+- **`ModelPackage`**: the four files, the SHA-256, the schema URL and its pinned form (`?sha256=`), the public
+  catalog URL, and `check()`.
+- **`Model`**: `title`, `description`, `root` (the governed record's cluster), `components` by identifier, `leaves`
+  in document order (each a `Leaf` with its `component`, its `path` of clusters and a `slug` of that path, unique in
+  the record), `codes` (the enumerated values per component as `Code`: value, IRI, definition, the code it is
+  defined by), `metadata` (the JSON-LD's) and `header` (the schema's Dublin Core).
+- **`Model.dc(name)`**: what the modeler wrote, the header first and the JSON-LD second, with SDCStudio's field
+  defaults as unset: "Universal" for coverage, "None" for relation, "SDC Data Model (DM)" for type, blanks. A
+  projection never publishes a default as a fact. `contributors`, `subjects` (the semicolon list), `rights_url` and
+  `rights_statement` derive from it.
+- **`Component`**: `sdc_type`, `label`, `description`, `data_type`, `constraints`, `links` by predicate (`link(p)` for
+  the first), `contains`, `iri`.
+- Constants: the leaf, numeric and quantified types; the predicate IRIs `IDENTIFIER`, `SOURCE`, `PUBLISHER`, `EXACT`,
+  `CLOSE`, `SEE_ALSO`, `HAS_UNIT`; `DC_DEFAULTS`.
+
+## Tests
+
+```
+pip install -e ".[dev]"
+python -m pytest tests -q                    # includes one fetch against production
+python -m pytest tests -q -m "not network"   # offline, as CI runs it
+```
+
+The fixture is the NHANES Participant package of the FAIR Data Demo, the record every projection is proven on.
+
+## Versioning
+
+The leading 4 is the SDC4 reference model, as with every Semantic Data Charter package. An addition to what the
+reader exposes is a minor version, a fix a patch; the major changes only when the reference model does.
+
+## Licence
+
+Apache-2.0 (see `LICENSE`, `NOTICE`).

sdcreader-4.0.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sdcreader"
+version = "4.0.0"
+description = "Read a published Semantic Data Charter model's package for projection into other standards (CDIF, DCAT-US, DCAT-AP, HealthDCAT-AP)."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+authors = [{ name = "Axius SDC, Inc." }]
+keywords = ["sdc", "semantic data charter", "governed data record", "cdif", "dcat", "dcat-ap", "healthdcat-ap", "fair"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+]
+
+dependencies = [
+    # the schema is read for the enumeration definitions and codes and the model's Dublin Core header
+    "lxml>=5.0",
+]
+
+[project.optional-dependencies]
+# Fetching a package from SDCStudio's public catalog needs HTTP; a package already on disk does not.
+fetch = ["requests>=2.31"]
+dev = ["pytest>=8.0", "requests>=2.31"]
+
+[project.urls]
+Homepage = "https://github.com/SemanticDataCharter/sdcreader"
+Changelog = "https://github.com/SemanticDataCharter/sdcreader/blob/main/CHANGELOG.md"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+markers = ["network: reaches SDCStudio's public catalog over the network; CI skips it"]

sdcreader-4.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sdcreader-4.0.0/src/sdcreader/__init__.py

@@ -0,0 +1,18 @@
+"""sdcreader: read a published Semantic Data Charter model's package for projection into other standards.
+
+A projection (CDIF, DCAT-US, DCAT-AP, HealthDCAT-AP, ...) describes a model's governed data records in another
+standard's terms. What it describes is the model's package: the JSON-LD with the components and their semantic
+links, the immutable schema the records are validated against, the public catalog record, the published schema
+versions. This package loads or fetches that evidence and reads it into one shape every projection shares: the
+record tree, its leaves in document order, the enumerated values with the codes the schema annotates them with,
+and the model's own Dublin Core with SDCStudio's field defaults read as unset. It knows nothing about any
+projection.
+"""
+from .model import (CLOSE, DC_DEFAULTS, EXACT, HAS_UNIT, IDENTIFIER, LEAF_TYPES, NUMERIC_TYPES, PUBLISHER, QUANTIFIED_TYPES, SEE_ALSO,
+                    SOURCE, Code, Component, Leaf, Model, enumeration_iri, read_header, read_model)
+from .package import DEFAULT_HOST, ModelPackage, PackageError, fetch_package, load_package
+
+__version__ = "4.0.0"
+__all__ = ["ModelPackage", "PackageError", "DEFAULT_HOST", "load_package", "fetch_package", "read_model", "read_header", "enumeration_iri",
+           "Model", "Component", "Leaf", "Code", "LEAF_TYPES", "NUMERIC_TYPES", "QUANTIFIED_TYPES", "DC_DEFAULTS", "IDENTIFIER", "SOURCE",
+           "PUBLISHER", "EXACT", "CLOSE", "SEE_ALSO", "HAS_UNIT", "__version__"]

sdcreader-4.0.0/src/sdcreader/model.py

@@ -0,0 +1,233 @@
+"""Read a model package into the shape the CDIF emitter needs: the record tree, its leaves in document order with
+their path, the enumerations with the definitions and codes the schema carries, the units each quantity takes.
+
+The JSON-LD package carries every component once, with `contains` references; a component composed in several
+places (three blood pressure readings sharing one Blood Pressure cluster) is one component with several positions.
+The schema carries what the JSON-LD does not: the definition and the code behind each enumerated value.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from urllib.parse import unquote
+
+from lxml import etree
+
+from .package import ModelPackage
+
+XSD_NS = "http://www.w3.org/2001/XMLSchema"
+DC_NS = "http://purl.org/dc/elements/1.1/"
+RDFS_NS = "http://www.w3.org/2000/01/rdf-schema#"
+RDF_NS = "http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+SDC4 = "https://semanticdatacharter.com/ns/sdc4/"
+NS = {"xsd": XSD_NS, "rdfs": RDFS_NS, "rdf": RDF_NS}
+
+LEAF_TYPES = {"XdString", "XdToken", "XdBoolean", "XdLink", "XdFile", "XdOrdinal", "XdCount", "XdQuantity", "XdFloat", "XdDouble",
+              "XdTemporal", "XdInterval", "XdStringList", "XdTokenList", "XdDecimalList", "XdIntegerList"}
+NUMERIC_TYPES = {"XdCount", "XdQuantity", "XdFloat", "XdDouble", "XdOrdinal"}
+QUANTIFIED_TYPES = {"XdCount", "XdQuantity", "XdFloat", "XdDouble"}
+
+IDENTIFIER = "http://purl.org/dc/terms/identifier"
+SOURCE = "http://purl.org/dc/terms/source"
+PUBLISHER = "http://purl.org/dc/terms/publisher"
+EXACT = "http://www.w3.org/2004/02/skos/core#exactMatch"
+CLOSE = "http://www.w3.org/2004/02/skos/core#closeMatch"
+SEE_ALSO = "http://www.w3.org/2000/01/rdf-schema#seeAlso"
+HAS_UNIT = "https://semanticdatacharter.com/ontology/sdc4-meta/hasUnit"
+
+
+@dataclass
+class Code:
+    value: str
+    iri: str
+    definition: str = ""
+    defined_by: str = ""
+
+
+@dataclass
+class Component:
+    ct_id: str
+    sdc_type: str
+    label: str
+    description: str
+    data_type: str
+    constraints: dict
+    links: dict[str, list[str]]
+    contains: list[str] = field(default_factory=list)
+
+    @property
+    def iri(self) -> str:
+        return f"{SDC4}mc-{self.ct_id}"
+
+    def link(self, predicate: str) -> str | None:
+        v = self.links.get(predicate)
+        return v[0] if v else None
+
+
+@dataclass
+class Leaf:
+    component: Component
+    path: list[Component]          # the clusters above it, root first
+    position: int                  # document order, 0-based
+
+    @property
+    def slug(self) -> str:
+        return "/".join(_slug(c.label) for c in self.path[1:] + [self.component])
+
+
+#: SDCStudio's field defaults, present in every schema header whether or not the modeler wrote anything; treated as
+#: unset so a writer never publishes "Universal" as a geographic coverage or "None" as a relation.
+DC_DEFAULTS = {"coverage": {"Universal"}, "relation": {"None"}, "type": {"SDC Data Model (DM)"}}
+
+
+@dataclass
+class Model:
+    package: ModelPackage
+    title: str
+    description: str
+    metadata: dict          # the JSON-LD package's metadata (dc:title, dc:creator, dc:rights, dc:date, ...)
+    header: dict            # the schema header's Dublin Core, complete: dc:subject, dc:coverage, dc:publisher, dc:contributor, ...
+
+    def dc(self, name: str) -> str | None:
+        """A Dublin Core value the modeler wrote: the schema header first, the JSON-LD second, defaults and blanks as None."""
+        v = self.header.get(name)
+        if v is None:
+            v = self.metadata.get(f"dc:{name}")
+        if isinstance(v, list):
+            v = v[0] if v else None
+        v = (v or "").strip() if isinstance(v, str) else v
+        if not v or v in DC_DEFAULTS.get(name, set()):
+            return None
+        return v
+
+    @property
+    def contributors(self) -> list[str]:
+        v = self.header.get("contributor")
+        if v is None:
+            v = self.metadata.get("dc:contributor") or []
+        return [c.strip() for c in (v if isinstance(v, list) else [v]) if c and c.strip()]
+
+    @property
+    def subjects(self) -> list[str]:
+        """dc:subject as SDCStudio asks for it: a semicolon-separated list of keywords."""
+        v = self.dc("subject") or ""
+        return [w.strip() for w in v.split(";") if w.strip()]
+
+    @property
+    def rights_url(self) -> str:
+        m = re.search(r"https?://\S+", self.dc("rights") or "")
+        return m.group(0).rstrip(".,;") if m else ""
+
+    @property
+    def rights_statement(self) -> str:
+        """The rights text with its URL removed; empty when nothing but a label is left."""
+        text = re.sub(r"https?://\S+", "", self.dc("rights") or "").strip(" ,;:")
+        return text if len(text) > 12 else ""
+    root: Component
+    components: dict[str, Component]
+    leaves: list[Leaf]
+    codes: dict[str, list[Code]]   # component ct_id -> enumerated values with their definitions and codes
+
+    @property
+    def ct_id(self) -> str:
+        return self.package.ct_id
+
+
+def read_model(pkg: ModelPackage) -> Model:
+    d = pkg.jsonld
+    comps: dict[str, Component] = {}
+    for n in d["components"]:
+        ct = n["@id"].split("mc-", 1)[1]
+        links: dict[str, list[str]] = {}
+        for l in n.get("semanticLinks") or []:
+            links.setdefault(l["predicate"], []).append(l["object"])
+        comps[ct] = Component(ct_id=ct, sdc_type=n["@type"][:-4] if n["@type"].endswith("Type") else n["@type"], label=n["label"],
+                              description=n.get("description") or "", data_type=n.get("dataType") or "", constraints=n.get("constraints") or {},
+                              links=links, contains=[m["@id"].split("mc-", 1)[1] for m in n.get("contains") or []])
+    root = _root(comps)
+    leaves: list[Leaf] = []
+
+    def walk(c: Component, path: list[Component]):
+        for m in c.contains:
+            child = comps[m]
+            if child.sdc_type == "Cluster":
+                walk(child, path + [child])
+            elif child.sdc_type in LEAF_TYPES:
+                leaves.append(Leaf(component=child, path=path + [c] if c is not path[-1] else path, position=len(leaves)))
+
+    walk(root, [root])
+    return Model(package=pkg, title=d.get("label") or d["metadata"].get("dc:title", ""), description=d.get("description") or "",
+                 metadata=d.get("metadata") or {}, header=read_header(pkg.xsd_bytes), root=root, components=comps, leaves=leaves,
+                 codes=_codes(pkg.xsd_bytes))
+
+
+def read_header(xsd_bytes: bytes) -> dict:
+    """The Dublin Core the schema header carries for the model (the first rdf:Description with dc: children): every
+    field the modeler could fill, blanks included, contributors as a list."""
+    tree = etree.fromstring(xsd_bytes)
+    out: dict = {}
+    for desc in tree.iter(f"{{{RDF_NS}}}Description"):
+        dc = [el for el in desc if isinstance(el.tag, str) and el.tag.startswith(f"{{{DC_NS}}}")]
+        if not dc:
+            continue
+        for el in dc:
+            name = el.tag.split("}", 1)[1]
+            text = " ".join((el.text or "").split())
+            if name == "contributor":
+                out.setdefault("contributor", []).append(text)
+            else:
+                out[name] = text
+        break
+    return out
+
+
+def _root(comps: dict[str, Component]) -> Component:
+    contained = {m for c in comps.values() for m in c.contains}
+    roots = [c for c in comps.values() if c.sdc_type == "Cluster" and c.ct_id not in contained and c.contains]
+    # the governed record is the cluster that contains the others; a party or audit detail cluster also sits uncontained
+    roots.sort(key=lambda c: -_size(c, comps))
+    if not roots:
+        raise ValueError("no root cluster in the package")
+    return roots[0]
+
+
+def _size(c: Component, comps: dict[str, Component]) -> int:
+    return 1 + sum(_size(comps[m], comps) for m in c.contains)
+
+
+def _codes(xsd_bytes: bytes) -> dict[str, list[Code]]:
+    """The enumerated values of every component, with the definition and the code the schema annotates them with."""
+    tree = etree.fromstring(xsd_bytes)
+    out: dict[str, list[Code]] = {}
+    for ct in tree.iterfind(f"{{{XSD_NS}}}complexType"):
+        name = ct.get("name") or ""
+        if not name.startswith("mc-"):
+            continue
+        codes: list[Code] = []
+        for enum in ct.iterfind(f".//{{{XSD_NS}}}enumeration"):
+            value = enum.get("value")
+            doc = enum.find(f"{{{XSD_NS}}}annotation/{{{XSD_NS}}}documentation")
+            cls = enum.find(f"{{{XSD_NS}}}annotation/{{{XSD_NS}}}appinfo/{{{RDFS_NS}}}Class")
+            iri = cls.get(f"{{{RDF_NS}}}about") if cls is not None else ""
+            defined_by = ""
+            if cls is not None:
+                db = cls.find(f"{{{RDFS_NS}}}isDefinedBy")
+                if db is not None:
+                    defined_by = (db.get(f"{{{RDF_NS}}}resource") or (db.text or "")).strip()
+            codes.append(Code(value=value, iri=iri or "", definition=" ".join((doc.text or "").split()) if doc is not None else "", defined_by=defined_by))
+        if codes:
+            out[name[3:]] = codes
+    return out
+
+
+def _slug(label: str) -> str:
+    s = re.sub(r"[^a-z0-9]+", "-", label.lower()).strip("-")
+    return s or "x"
+
+
+def enumeration_iri(component: Component, codes: list[Code]) -> str:
+    """The IRI of a component's value set: the parent of the per-value class IRIs the schema declares."""
+    for c in codes:
+        if c.iri:
+            return c.iri.rsplit("/", 1)[0]
+    return f"{component.iri}/{component.sdc_type.lower()}-value"

sdcreader-4.0.0/src/sdcreader/package.py

@@ -0,0 +1,106 @@
+"""A published model's package: the files the writer reads, from a directory or from SDCStudio's public catalog.
+
+A package directory holds `dm-<ct>.jsonld` (the model and its components with their semantic links), `dm-<ct>.xsd`
+(the schema, read for the enumeration definitions and hashed for the citation), and optionally `catalog.json` (the
+public catalog record) and `versions.json` (the published schema versions). The writer refuses a model without a
+package: the JSON-LD and the schema are the evidence it describes.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+
+DEFAULT_HOST = "https://sdcstudio.axius-sdc.com"
+
+
+class PackageError(Exception):
+    pass
+
+
+@dataclass
+class ModelPackage:
+    ct_id: str
+    jsonld: dict
+    xsd_bytes: bytes
+    catalog: dict = field(default_factory=dict)
+    versions: dict = field(default_factory=dict)
+    host: str = DEFAULT_HOST
+
+    @property
+    def sha256(self) -> str:
+        return hashlib.sha256(self.xsd_bytes).hexdigest()
+
+    @property
+    def schema_url(self) -> str:
+        return f"{self.host}/dmlib/dm-{self.ct_id}.xsd"
+
+    @property
+    def schema_url_pinned(self) -> str:
+        return f"{self.schema_url}?sha256={self.sha256}"
+
+    @property
+    def catalog_url(self) -> str:
+        return f"{self.host}/api/v1/catalog/dm/{self.ct_id}/"
+
+    def check(self) -> None:
+        if self.jsonld.get("identifier") != self.ct_id:
+            raise PackageError(f"package JSON-LD identifier {self.jsonld.get('identifier')!r} is not {self.ct_id!r}")
+        if not self.jsonld.get("components"):
+            raise PackageError("package JSON-LD has no components")
+        if b"<xsd:schema" not in self.xsd_bytes[:4000] and b"<xs:schema" not in self.xsd_bytes[:4000]:
+            raise PackageError("package schema is not an XML Schema")
+        current = self.versions.get("current_sha256")
+        if current and current != self.sha256:
+            raise PackageError(f"schema on disk ({self.sha256[:12]}) is not the published current version ({current[:12]})")
+
+
+def load_package(directory: str | Path, ct_id: str | None = None, host: str = DEFAULT_HOST) -> ModelPackage:
+    d = Path(directory)
+    if ct_id is None:
+        xsds = sorted(d.glob("dm-*.xsd"))
+        if len(xsds) != 1:
+            raise PackageError(f"{d}: expected one dm-<ct>.xsd, found {len(xsds)}")
+        ct_id = xsds[0].stem[3:]
+    jsonld_path, xsd_path = d / f"dm-{ct_id}.jsonld", d / f"dm-{ct_id}.xsd"
+    for p in (jsonld_path, xsd_path):
+        if not p.exists():
+            raise PackageError(f"{p} is missing: the writer needs the model's package, not just its identifier")
+    pkg = ModelPackage(ct_id=ct_id, jsonld=json.loads(jsonld_path.read_text(encoding="utf-8")), xsd_bytes=xsd_path.read_bytes(),
+                       catalog=_optional_json(d / "catalog.json"), versions=_optional_json(d / "versions.json"), host=host)
+    pkg.check()
+    return pkg
+
+
+def fetch_package(ct_id: str, save_to: str | Path | None = None, host: str = DEFAULT_HOST, timeout: int = 60) -> ModelPackage:
+    """Fetch a published model's package from the public catalog (no account needed) and optionally save it."""
+    import requests  # optional dependency
+
+    def get(url, **kw):
+        r = requests.get(url, timeout=timeout, **kw)
+        if r.status_code != 200:
+            raise PackageError(f"{url}: HTTP {r.status_code}")
+        return r
+
+    catalog = get(f"{host}/api/v1/catalog/dm/{ct_id}/").json()
+    jsonld = get(f"{host}/api/v1/catalog/dm/{ct_id}/jsonld/").json()
+    if isinstance(jsonld, dict) and "download_url" in jsonld and "components" not in jsonld:
+        # a storage-backed artifact: the catalog answers with a pointer to the file, not the file
+        jsonld = get(jsonld["download_url"]).json()
+    xsd = get(f"{host}/dmlib/dm-{ct_id}.xsd").content
+    versions = get(f"{host}/dmlib/dm-{ct_id}.versions.json").json()
+    pkg = ModelPackage(ct_id=ct_id, jsonld=jsonld, xsd_bytes=xsd, catalog=catalog, versions=versions, host=host)
+    pkg.check()
+    if save_to is not None:
+        d = Path(save_to)
+        d.mkdir(parents=True, exist_ok=True)
+        (d / f"dm-{ct_id}.jsonld").write_text(json.dumps(jsonld, indent=1, ensure_ascii=False), encoding="utf-8")
+        (d / f"dm-{ct_id}.xsd").write_bytes(xsd)
+        (d / "catalog.json").write_text(json.dumps(catalog, indent=1, ensure_ascii=False), encoding="utf-8")
+        (d / "versions.json").write_text(json.dumps(versions, indent=1), encoding="utf-8")
+    return pkg
+
+
+def _optional_json(path: Path) -> dict:
+    return json.loads(path.read_text(encoding="utf-8")) if path.exists() else {}

sdcreader-4.0.0/src/sdcreader.egg-info/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: sdcreader
+Version: 4.0.0
+Summary: Read a published Semantic Data Charter model's package for projection into other standards (CDIF, DCAT-US, DCAT-AP, HealthDCAT-AP).
+Author: Axius SDC, Inc.
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/SemanticDataCharter/sdcreader
+Project-URL: Changelog, https://github.com/SemanticDataCharter/sdcreader/blob/main/CHANGELOG.md
+Keywords: sdc,semantic data charter,governed data record,cdif,dcat,dcat-ap,healthdcat-ap,fair
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: lxml>=5.0
+Provides-Extra: fetch
+Requires-Dist: requests>=2.31; extra == "fetch"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: requests>=2.31; extra == "dev"
+Dynamic: license-file
+
+# sdcreader
+
+Read a published Semantic Data Charter model's package for projection into other standards.
+
+A projection describes a model's governed data records in another standard's terms: CDIF, DCAT-US 3.0, DCAT-AP
+3.0.1, HealthDCAT-AP, and whatever comes next. What every projection describes is the same evidence, the model's
+package, and reads it into the same shape. `sdcreader` is that evidence and that shape, once, with nothing about
+any projection in it. The four projection writers (`sdc_cdif`, `sdc_dcat3_us`, `sdc_dcat3_ap`, `sdc_healthdcat_ap`)
+carried it as identical copies until this package.
+
+```
+pip install sdcreader            # or, until the PyPI release: pip install "sdcreader @ git+https://github.com/SemanticDataCharter/sdcreader@v4.0.0"
+pip install "sdcreader[fetch]"   # with HTTP, to fetch a package from the public catalog
+```
+
+```python
+from sdcreader import fetch_package, load_package, read_model
+
+pkg = load_package("samples/nhanes-participant")          # a package on disk
+pkg = fetch_package("xy8upneajsb8vdcmnve01g6g", save_to="pkg/")   # or from SDCStudio's public catalog, no account
+model = read_model(pkg)
+
+pkg.schema_url_pinned        # https://sdcstudio.axius-sdc.com/dmlib/dm-xy8u...xsd?sha256=0df4...   the exact bytes the records are validated against
+model.title, model.leaves    # 'NHANES Participant', 153 leaves in document order, each with its path of clusters
+model.codes[ct_id]           # the enumerated values of a component with the IRI, definition and code the schema annotates them with
+model.dc("publisher")        # what the modeler wrote, None where SDCStudio's default sits
+```
+
+## What a package is
+
+SDCStudio generates a package for every published model and serves it publicly for models in public projects:
+
+| | |
+|---|---|
+| `GET /api/v1/catalog/dm/<ct>/` | the catalog record: title, description, project, the artifact list (`catalog.json`) |
+| `GET /api/v1/catalog/dm/<ct>/<artifact>/` | a storage pointer, `{"download_url": ..., "filename": ..., "storage": "gcs"}`, for `jsonld`, `xsd` and the rest; the reader follows it |
+| `dm-<ct>.jsonld` | the model and its components: type, label, description, cardinality, constraints (enumerations, units, ranges, patterns), semantic links (`dcterms:identifier` the library slot, `dcterms:source`, `dcterms:publisher`, `skos:exactMatch`, `rdfs:seeAlso`, `prov:wasRevisionOf`), `contains` |
+| `GET /dmlib/dm-<ct>.xsd` | the schema bytes: the Dublin Core header for the model, and for each enumerated value its definition and the code it is defined by (`dm-<ct>.xsd`) |
+| `GET /dmlib/dm-<ct>.versions.json` | every published version of the schema by SHA-256, with the current one (`versions.json`) |
+
+A package directory holds those four files. The reader refuses a directory without the JSON-LD and the schema, a
+JSON-LD whose identifier is not the directory's model, and a schema whose bytes are not the published current
+version: a projection cites the schema by URL and SHA-256, so the bytes have to be the ones that URL serves.
+
+Two gaps in the package are on SDCStudio's issue tracker: the JSON-LD metadata drops fields the schema header
+carries (#748), and the header omits `dc:source` (#749). The reader takes the model's Dublin Core from the header,
+which is complete.
+
+## What the reader gives
+
+- **`ModelPackage`**: the four files, the SHA-256, the schema URL and its pinned form (`?sha256=`), the public
+  catalog URL, and `check()`.
+- **`Model`**: `title`, `description`, `root` (the governed record's cluster), `components` by identifier, `leaves`
+  in document order (each a `Leaf` with its `component`, its `path` of clusters and a `slug` of that path, unique in
+  the record), `codes` (the enumerated values per component as `Code`: value, IRI, definition, the code it is
+  defined by), `metadata` (the JSON-LD's) and `header` (the schema's Dublin Core).
+- **`Model.dc(name)`**: what the modeler wrote, the header first and the JSON-LD second, with SDCStudio's field
+  defaults as unset: "Universal" for coverage, "None" for relation, "SDC Data Model (DM)" for type, blanks. A
+  projection never publishes a default as a fact. `contributors`, `subjects` (the semicolon list), `rights_url` and
+  `rights_statement` derive from it.
+- **`Component`**: `sdc_type`, `label`, `description`, `data_type`, `constraints`, `links` by predicate (`link(p)` for
+  the first), `contains`, `iri`.
+- Constants: the leaf, numeric and quantified types; the predicate IRIs `IDENTIFIER`, `SOURCE`, `PUBLISHER`, `EXACT`,
+  `CLOSE`, `SEE_ALSO`, `HAS_UNIT`; `DC_DEFAULTS`.
+
+## Tests
+
+```
+pip install -e ".[dev]"
+python -m pytest tests -q                    # includes one fetch against production
+python -m pytest tests -q -m "not network"   # offline, as CI runs it
+```
+
+The fixture is the NHANES Participant package of the FAIR Data Demo, the record every projection is proven on.
+
+## Versioning
+
+The leading 4 is the SDC4 reference model, as with every Semantic Data Charter package. An addition to what the
+reader exposes is a minor version, a fix a patch; the major changes only when the reference model does.
+
+## Licence
+
+Apache-2.0 (see `LICENSE`, `NOTICE`).

sdcreader-4.0.0/src/sdcreader.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+NOTICE
+README.md
+pyproject.toml
+src/sdcreader/__init__.py
+src/sdcreader/model.py
+src/sdcreader/package.py
+src/sdcreader.egg-info/PKG-INFO
+src/sdcreader.egg-info/SOURCES.txt
+src/sdcreader.egg-info/dependency_links.txt
+src/sdcreader.egg-info/requires.txt
+src/sdcreader.egg-info/top_level.txt
+tests/test_reader.py

sdcreader-4.0.0/src/sdcreader.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

sdcreader-4.0.0/src/sdcreader.egg-info/requires.txt

@@ -0,0 +1,8 @@
+lxml>=5.0
+
+[dev]
+pytest>=8.0
+requests>=2.31
+
+[fetch]
+requests>=2.31

sdcreader-4.0.0/src/sdcreader.egg-info/top_level.txt

@@ -0,0 +1 @@
+sdcreader

sdcreader-4.0.0/tests/test_reader.py

@@ -0,0 +1,118 @@
+"""The reader on the NHANES Participant package: it loads and refuses as documented, proves the schema bytes are the
+published current version, reads the record tree and its leaves in document order, the enumerated values with their
+codes, the model's Dublin Core with SDCStudio's defaults as unset, and fetches a package from the public catalog
+following the storage pointer (through a fake transport offline; against production behind the network marker)."""
+import hashlib
+import json
+from pathlib import Path
+
+import pytest
+
+import sdcreader
+from sdcreader import Code, Leaf, Model, PackageError, enumeration_iri, fetch_package, load_package, read_header, read_model
+
+ROOT = Path(__file__).resolve().parents[1]
+PACKAGE = ROOT / "samples" / "nhanes-participant"
+CT = "xy8upneajsb8vdcmnve01g6g"
+
+
+@pytest.fixture(scope="module")
+def pkg():
+    return load_package(PACKAGE)
+
+
+@pytest.fixture(scope="module")
+def model(pkg):
+    return read_model(pkg)
+
+
+def test_the_version_carries_the_reference_model():
+    assert sdcreader.__version__.startswith("4.")
+
+
+def test_a_package_loads_and_proves_its_schema_is_the_published_current_version(pkg):
+    assert pkg.ct_id == CT
+    sha = hashlib.sha256((PACKAGE / f"dm-{CT}.xsd").read_bytes()).hexdigest()
+    assert pkg.sha256 == sha == pkg.versions["current_sha256"]
+    assert pkg.schema_url == f"https://sdcstudio.axius-sdc.com/dmlib/dm-{CT}.xsd"
+    assert pkg.schema_url_pinned == f"{pkg.schema_url}?sha256={sha}"
+    assert pkg.catalog_url == f"https://sdcstudio.axius-sdc.com/api/v1/catalog/dm/{CT}/"
+    assert pkg.catalog["project_name"] == "FAIR Data Demo"
+
+
+def test_the_reader_refuses_what_is_not_a_package(tmp_path):
+    (tmp_path / f"dm-{CT}.xsd").write_bytes(b"<xsd:schema/>")
+    with pytest.raises(PackageError, match="missing"):
+        load_package(tmp_path)
+    (tmp_path / f"dm-{CT}.jsonld").write_text(json.dumps({"identifier": "other", "components": [{}]}))
+    with pytest.raises(PackageError, match="identifier"):
+        load_package(tmp_path)
+    (tmp_path / f"dm-{CT}.jsonld").write_text(json.dumps({"identifier": CT, "components": [{}]}))
+    (tmp_path / "versions.json").write_text(json.dumps({"current_sha256": "0" * 64}))
+    with pytest.raises(PackageError, match="not the published current version"):
+        load_package(tmp_path)
+
+
+def test_the_record_tree_its_leaves_and_their_codes(model: Model):
+    assert model.title == "NHANES Participant" and model.root.label == "NHANES Participant Governed Record"
+    assert len(model.leaves) == 153
+    first, last = model.leaves[0], model.leaves[-1]
+    assert isinstance(first, Leaf) and first.position == 0 and last.position == 152
+    assert first.slug.startswith("audit-event/") and all(l.component.sdc_type in sdcreader.LEAF_TYPES for l in model.leaves)
+    slugs = [l.slug for l in model.leaves]
+    assert len(set(slugs)) == len(slugs)                                      # the path names each leaf once
+    assert len({l.component.ct_id for l in model.leaves}) < len(slugs)        # a component composed three times (the blood pressure readings) is three leaves
+    enumerated = {k: v for k, v in model.codes.items() if k in model.components}
+    assert len(enumerated) >= 60
+    marital = next(l.component for l in model.leaves if l.component.label == "Marital Status (DMDMARTL)")
+    codes = model.codes[marital.ct_id]
+    assert [c.value for c in codes][:2] == ["Married", "Widowed"]
+    assert all(isinstance(c, Code) and c.iri.startswith(marital.iri) for c in codes)
+    assert codes[0].defined_by == "http://purl.obolibrary.org/obo/NCIT_C51773"
+    assert enumeration_iri(marital, codes) == f"{marital.iri}/xdtoken-value"
+    sbp = next(l.component for l in model.leaves if l.component.label == "Systolic Blood Pressure")
+    assert sbp.sdc_type == "XdQuantity" and sbp.data_type == "xsd:decimal" and sbp.link(sdcreader.IDENTIFIER).startswith("https://axius-sdc.com/library/")
+
+
+def test_the_models_dublin_core_comes_from_the_schema_header_with_defaults_as_unset(model: Model, pkg):
+    header = read_header(pkg.xsd_bytes)
+    assert header["coverage"] == "Universal" and header["relation"] == "None" and header["publisher"] == ""
+    assert model.dc("coverage") is None and model.dc("relation") is None and model.dc("publisher") is None and model.dc("type") is None
+    assert model.dc("creator") == "Timothy Cook" and model.dc("date", ).startswith("2026-09-26")
+    assert model.subjects == [] and model.contributors == []
+    assert model.rights_url == "http://creativecommons.org/licenses/by/3.0/" and model.rights_statement == ""
+    authored = Model(**{**model.__dict__, "header": dict(header, subject="a; b;; c", contributor=["X"],
+                                                          rights="Public domain in the United States https://creativecommons.org/publicdomain/zero/1.0/ except where noted")})
+    assert authored.subjects == ["a", "b", "c"] and authored.contributors == ["X"]
+    assert authored.rights_url == "https://creativecommons.org/publicdomain/zero/1.0/" and authored.rights_statement.startswith("Public domain")
+
+
+def test_fetch_follows_the_catalogs_storage_pointer(monkeypatch, tmp_path):
+    """The artifact endpoint answers with {download_url, filename, storage} for a storage-backed file, not the file."""
+    import requests
+    files = {
+        f"https://sdcstudio.axius-sdc.com/api/v1/catalog/dm/{CT}/": (PACKAGE / "catalog.json").read_bytes(),
+        f"https://sdcstudio.axius-sdc.com/api/v1/catalog/dm/{CT}/jsonld/": json.dumps({"download_url": "https://storage.example/dm.jsonld", "filename": "x", "storage": "gcs"}).encode(),
+        "https://storage.example/dm.jsonld": (PACKAGE / f"dm-{CT}.jsonld").read_bytes(),
+        f"https://sdcstudio.axius-sdc.com/dmlib/dm-{CT}.xsd": (PACKAGE / f"dm-{CT}.xsd").read_bytes(),
+        f"https://sdcstudio.axius-sdc.com/dmlib/dm-{CT}.versions.json": (PACKAGE / "versions.json").read_bytes(),
+    }
+
+    class R:
+        def __init__(self, content):
+            self.status_code, self.content = 200, content
+
+        def json(self):
+            return json.loads(self.content)
+
+    monkeypatch.setattr(requests, "get", lambda url, **kw: R(files[url]))
+    pkg = fetch_package(CT, save_to=tmp_path)
+    assert pkg.sha256 == load_package(PACKAGE).sha256 and pkg.jsonld["identifier"] == CT
+    assert sorted(p.name for p in tmp_path.iterdir()) == ["catalog.json", f"dm-{CT}.jsonld", f"dm-{CT}.xsd", "versions.json"]
+    assert load_package(tmp_path).sha256 == pkg.sha256
+
+
+@pytest.mark.network
+def test_fetch_from_production_matches_the_fixture():
+    pkg = fetch_package(CT)
+    assert pkg.sha256 == load_package(PACKAGE).sha256