omh-shim 1.0.2__tar.gz

omh_shim-1.0.2/AUTHORS.md

@@ -0,0 +1,7 @@
+# Authors
+
+**Primary maintainer:** JupyterHealth Exchange team
+
+**`omh_shim/sources/oura_raw/`** — converter mapping logic ported with permission from
+[dicristea/oura-clinical-workbench/data_syn](https://github.com/dicristea/oura-clinical-workbench/tree/main/data_syn).
+Each `oura_raw` source file carries an attribution comment.

omh_shim-1.0.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JupyterHealth Exchange contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

omh_shim-1.0.2/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: omh-shim
+Version: 1.0.2
+Summary: Convert wearable health data from vendor schemas to Open mHealth schemas
+Author: JupyterHealth Exchange contributors
+License: MIT
+Project-URL: Repository, https://github.com/jupyterhealth/omh-shim
+Project-URL: Issues, https://github.com/jupyterhealth/omh-shim/issues
+Keywords: health,open-mhealth,wearables,fhir,schema-conversion
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Healthcare Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: AUTHORS.md
+Requires-Dist: jsonschema<5.0,>=4.18
+Requires-Dist: referencing>=0.30
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Dynamic: license-file
+
+# omh-shim
+
+Convert wearable health data from vendor schemas to [Open mHealth](https://www.openmhealth.org/) schemas.
+
+## Status
+
+v1.0 — initial public release. Public API is stable; converter coverage will continue to expand.
+
+## Install
+
+```bash
+pip install git+https://github.com/jupyterhealth/omh-shim.git@v1.0.1
+```
+
+## Usage
+
+Timestamp-based data types (one reading at a known instant):
+
+```python
+from omh_shim import convert
+
+omh_record = convert(
+    source="ow_normalized",
+    data_type="heart_rate",
+    sample={
+        "timestamp": "2026-04-09T08:30:00+00:00",
+        "type": "heart_rate",
+        "value": 72,
+        "unit": "bpm",
+        "source": {"source_name": "Oura Ring", "device_model": "Oura Gen 3"},
+    },
+)
+```
+
+Daily data types (``step_count``, ``physical_activity``, ``sleep_duration``)
+aggregate over a calendar day, so they REQUIRE an explicit timezone so the day
+boundaries reflect the user's local day rather than silently assuming UTC:
+
+```python
+from datetime import UTC
+from zoneinfo import ZoneInfo
+
+# UTC-anchored upstream data
+convert(
+    source="oura_raw",
+    data_type="step_count",
+    sample={"day": "2026-04-09", "steps": 8432},
+    tz=UTC,
+)
+
+# User's local timezone
+convert(
+    source="oura_raw",
+    data_type="step_count",
+    sample={"day": "2026-04-09", "steps": 8432},
+    tz=ZoneInfo("America/Los_Angeles"),
+)
+```
+
+Pass `header=True` to get the full IEEE 1752.1 data-point envelope with
+UUID, schema_id components, creation timestamp, modality, and optional
+`external_datasheets`:
+
+```python
+convert(
+    source="oura_raw",
+    data_type="heart_rate",
+    sample={"bpm": 72, "timestamp": "2026-04-09T08:00:00Z"},
+    header=True,
+    external_datasheets=[
+        {"datasheet_type": "manufacturer", "datasheet_reference": "Oura"},
+    ],
+)
+# Returns:
+# {
+#   "header": {
+#     "uuid": "...",
+#     "schema_id": {"namespace": "omh", "name": "heart-rate", "version": "2.0"},
+#     "source_creation_date_time": "...",
+#     "modality": "sensed",
+#     "external_datasheets": [{"datasheet_type": "manufacturer", "datasheet_reference": "Oura"}]
+#   },
+#   "body": {
+#     "heart_rate": {"value": 72.0, "unit": "beats/min"},
+#     "effective_time_frame": {"date_time": "2026-04-09T08:00:00Z"}
+#   }
+# }
+```
+
+`convert` raises `ConversionError` for unknown `(source, data_type)` pairs,
+invalid sample shapes, naive (timezone-less) datetimes, or a missing ``tz``
+for daily data types. It raises `ValidationError` if the converter output
+fails schema validation.
+
+## Supported sources and data types (v1.0)
+
+| `source` | `data_type` values |
+|---|---|
+| `ow_normalized` | `heart_rate`, `heart_rate_variability`, `step_count`, `sleep_duration`, `sleep_episode`, `physical_activity` |
+| `oura_raw` | `heart_rate`, `heart_rate_variability`, `step_count`, `sleep_duration`, `sleep_episode`, `physical_activity` |
+
+Note: `heart_rate_variability` targets the local placeholder schema
+`local:heart-rate-variability:1.0` (Open mHealth has not published a canonical
+HRV schema as of 2026-04). The `local:` namespace is deliberate — downstream
+consumers should not assume OMH-standard interoperability for HRV records.
+
+## Mapping references
+
+- [`docs/mappings/oura_raw.md`](docs/mappings/oura_raw.md) — Oura Ring v2 API → OMH (body fields)
+- [`docs/mappings/ow_normalized.md`](docs/mappings/ow_normalized.md) — Open Wearables normalized API → OMH (body fields)
+- [`docs/mappings/ieee-1752-header.md`](docs/mappings/ieee-1752-header.md) — IEEE 1752.1 data-point header envelope
+
+## Credits
+
+`omh_shim/sources/oura_raw.py` ports converter mapping logic with permission
+from [dicristea/oura-clinical-workbench](https://github.com/dicristea/oura-clinical-workbench/tree/main/data_syn).
+See [AUTHORS.md](AUTHORS.md).
+
+## License
+
+MIT. See [LICENSE](LICENSE).

omh_shim-1.0.2/README.md

@@ -0,0 +1,121 @@
+# omh-shim
+
+Convert wearable health data from vendor schemas to [Open mHealth](https://www.openmhealth.org/) schemas.
+
+## Status
+
+v1.0 — initial public release. Public API is stable; converter coverage will continue to expand.
+
+## Install
+
+```bash
+pip install git+https://github.com/jupyterhealth/omh-shim.git@v1.0.1
+```
+
+## Usage
+
+Timestamp-based data types (one reading at a known instant):
+
+```python
+from omh_shim import convert
+
+omh_record = convert(
+    source="ow_normalized",
+    data_type="heart_rate",
+    sample={
+        "timestamp": "2026-04-09T08:30:00+00:00",
+        "type": "heart_rate",
+        "value": 72,
+        "unit": "bpm",
+        "source": {"source_name": "Oura Ring", "device_model": "Oura Gen 3"},
+    },
+)
+```
+
+Daily data types (``step_count``, ``physical_activity``, ``sleep_duration``)
+aggregate over a calendar day, so they REQUIRE an explicit timezone so the day
+boundaries reflect the user's local day rather than silently assuming UTC:
+
+```python
+from datetime import UTC
+from zoneinfo import ZoneInfo
+
+# UTC-anchored upstream data
+convert(
+    source="oura_raw",
+    data_type="step_count",
+    sample={"day": "2026-04-09", "steps": 8432},
+    tz=UTC,
+)
+
+# User's local timezone
+convert(
+    source="oura_raw",
+    data_type="step_count",
+    sample={"day": "2026-04-09", "steps": 8432},
+    tz=ZoneInfo("America/Los_Angeles"),
+)
+```
+
+Pass `header=True` to get the full IEEE 1752.1 data-point envelope with
+UUID, schema_id components, creation timestamp, modality, and optional
+`external_datasheets`:
+
+```python
+convert(
+    source="oura_raw",
+    data_type="heart_rate",
+    sample={"bpm": 72, "timestamp": "2026-04-09T08:00:00Z"},
+    header=True,
+    external_datasheets=[
+        {"datasheet_type": "manufacturer", "datasheet_reference": "Oura"},
+    ],
+)
+# Returns:
+# {
+#   "header": {
+#     "uuid": "...",
+#     "schema_id": {"namespace": "omh", "name": "heart-rate", "version": "2.0"},
+#     "source_creation_date_time": "...",
+#     "modality": "sensed",
+#     "external_datasheets": [{"datasheet_type": "manufacturer", "datasheet_reference": "Oura"}]
+#   },
+#   "body": {
+#     "heart_rate": {"value": 72.0, "unit": "beats/min"},
+#     "effective_time_frame": {"date_time": "2026-04-09T08:00:00Z"}
+#   }
+# }
+```
+
+`convert` raises `ConversionError` for unknown `(source, data_type)` pairs,
+invalid sample shapes, naive (timezone-less) datetimes, or a missing ``tz``
+for daily data types. It raises `ValidationError` if the converter output
+fails schema validation.
+
+## Supported sources and data types (v1.0)
+
+| `source` | `data_type` values |
+|---|---|
+| `ow_normalized` | `heart_rate`, `heart_rate_variability`, `step_count`, `sleep_duration`, `sleep_episode`, `physical_activity` |
+| `oura_raw` | `heart_rate`, `heart_rate_variability`, `step_count`, `sleep_duration`, `sleep_episode`, `physical_activity` |
+
+Note: `heart_rate_variability` targets the local placeholder schema
+`local:heart-rate-variability:1.0` (Open mHealth has not published a canonical
+HRV schema as of 2026-04). The `local:` namespace is deliberate — downstream
+consumers should not assume OMH-standard interoperability for HRV records.
+
+## Mapping references
+
+- [`docs/mappings/oura_raw.md`](docs/mappings/oura_raw.md) — Oura Ring v2 API → OMH (body fields)
+- [`docs/mappings/ow_normalized.md`](docs/mappings/ow_normalized.md) — Open Wearables normalized API → OMH (body fields)
+- [`docs/mappings/ieee-1752-header.md`](docs/mappings/ieee-1752-header.md) — IEEE 1752.1 data-point header envelope
+
+## Credits
+
+`omh_shim/sources/oura_raw.py` ports converter mapping logic with permission
+from [dicristea/oura-clinical-workbench](https://github.com/dicristea/oura-clinical-workbench/tree/main/data_syn).
+See [AUTHORS.md](AUTHORS.md).
+
+## License
+
+MIT. See [LICENSE](LICENSE).

omh_shim-1.0.2/omh_shim/__init__.py

@@ -0,0 +1,111 @@
+"""omh-shim: convert wearable health data to Open mHealth schemas."""
+
+from collections.abc import Mapping
+from datetime import tzinfo
+from types import MappingProxyType
+from typing import Any
+
+from omh_shim import _dispatch, _schema_loader, _validate
+from omh_shim._helpers import build_header
+from omh_shim.errors import ConversionError, ValidationError
+
+__all__ = ["convert", "ConversionError", "ValidationError", "SCHEMA_IDS"]
+__version__ = "1.0.2"
+
+SCHEMA_IDS: Mapping[str, str] = MappingProxyType({
+    "heart_rate": "omh:heart-rate:2.0",
+    "heart_rate_variability": "local:heart-rate-variability:1.0",
+    "step_count": "omh:step-count:3.0",
+    "sleep_duration": "omh:sleep-duration:2.0",
+    "sleep_episode": "omh:sleep-episode:1.1",
+    "physical_activity": "omh:physical-activity:1.2",
+    "oxygen_saturation": "omh:oxygen-saturation:2.0",
+})
+"""Read-only mapping of data_type -> schema id. ``heart_rate_variability``
+uses a ``local:`` namespace placeholder (OMH has no canonical HRV schema)."""
+
+# Fail fast if someone adds a converter without a schema id (or vice versa),
+# or a schema id without a loader filename entry. Uses raise (not assert)
+# so it survives python -O.
+_registered = {dt for (_, dt) in _dispatch.REGISTRY}
+if _registered != SCHEMA_IDS.keys():
+    raise RuntimeError(f"REGISTRY/SCHEMA_IDS drift: {_registered ^ SCHEMA_IDS.keys()}")
+if set(SCHEMA_IDS.values()) != _schema_loader.known_ids():
+    raise RuntimeError(
+        f"SCHEMA_IDS/loader drift: {set(SCHEMA_IDS.values()) ^ _schema_loader.known_ids()}"
+    )
+del _registered
+
+
+_SOURCE_DEVICE_MAP: Mapping[str, str] = MappingProxyType({
+    "oura_raw": "Oura Ring",
+})
+
+
+def _extract_datasheets(
+    sample: Mapping[str, Any], *, source: str | None = None,
+) -> list[dict[str, str]] | None:
+    """Extract external_datasheets from the sample's source metadata.
+
+    OW normalized samples include ``source.provider`` and ``source.device``
+    as a nested dict; that more-specific metadata wins when present. Raw
+    samples (e.g. ``oura_raw``) don't carry a source field — for those, the
+    device is implicit from the ``source`` parameter and resolved via
+    ``_SOURCE_DEVICE_MAP``.
+    """
+    source_meta = sample.get("source") if isinstance(sample, Mapping) else None
+    if isinstance(source_meta, Mapping):
+        device = source_meta.get("device") or source_meta.get("device_model")
+        provider = source_meta.get("provider") or source_meta.get("source_name")
+        ref = device or provider
+        if ref:
+            return [{"datasheet_type": "manufacturer", "datasheet_reference": str(ref)}]
+    if source and source in _SOURCE_DEVICE_MAP:
+        return [{
+            "datasheet_type": "manufacturer",
+            "datasheet_reference": _SOURCE_DEVICE_MAP[source],
+        }]
+    return None
+
+
+def convert(
+    source: str,
+    data_type: str,
+    sample: Mapping[str, Any],
+    *,
+    tz: tzinfo | None = None,
+    validate: bool = True,
+) -> dict[str, Any]:
+    """Convert one source sample to one Open mHealth data-point.
+
+    Always returns the full IEEE 1752.1 data-point envelope::
+
+        {"header": {...}, "body": {...}}
+
+    The header includes ``uuid``, ``schema_id``, ``source_creation_date_time``,
+    ``modality``, and ``external_datasheets`` (auto-populated from the sample's
+    source metadata when available).
+
+    ``tz`` is required for daily data types (step_count, physical_activity,
+    sleep_duration) — pass ``datetime.UTC`` or a ``ZoneInfo``.
+
+    Raises ``ConversionError`` on invalid input, ``ValidationError`` on
+    schema mismatch (when ``validate=True``).
+    """
+    converter = _dispatch.lookup(source, data_type)
+    try:
+        body = converter(sample, tz=tz)
+    except (KeyError, ValueError, TypeError) as e:
+        raise ConversionError(
+            f"{source}/{data_type}: {type(e).__name__}: {e}"
+        ) from e
+    schema_id = SCHEMA_IDS[data_type]
+    if validate:
+        _validate.validate_output(body, schema_id)
+    return {
+        "header": build_header(
+            schema_id,
+            external_datasheets=_extract_datasheets(sample, source=source),
+        ),
+        "body": body,
+    }

omh_shim-1.0.2/omh_shim/_dispatch.py

@@ -0,0 +1,42 @@
+"""(source, data_type) -> converter function lookup."""
+
+from collections.abc import Mapping
+from datetime import tzinfo
+from types import MappingProxyType
+from typing import Any, Protocol
+
+from omh_shim.errors import ConversionError
+from omh_shim.sources import oura_raw, ow_normalized
+
+
+class _Converter(Protocol):
+    def __call__(
+        self, sample: Mapping[str, Any], *, tz: tzinfo | None
+    ) -> dict[str, Any]: ...
+
+
+REGISTRY: Mapping[tuple[str, str], _Converter] = MappingProxyType({
+    ("oura_raw", "heart_rate"):              oura_raw.heart_rate,
+    ("oura_raw", "heart_rate_variability"):  oura_raw.heart_rate_variability,
+    ("oura_raw", "step_count"):              oura_raw.step_count,
+    ("oura_raw", "sleep_duration"):          oura_raw.sleep_duration,
+    ("oura_raw", "sleep_episode"):           oura_raw.sleep_episode,
+    ("oura_raw", "physical_activity"):       oura_raw.physical_activity,
+    ("ow_normalized", "heart_rate"):             ow_normalized.heart_rate,
+    ("ow_normalized", "heart_rate_variability"): ow_normalized.heart_rate_variability,
+    ("ow_normalized", "step_count"):             ow_normalized.step_count,
+    ("ow_normalized", "sleep_duration"):         ow_normalized.sleep_duration,
+    ("ow_normalized", "sleep_episode"):          ow_normalized.sleep_episode,
+    ("ow_normalized", "physical_activity"):      ow_normalized.physical_activity,
+    ("ow_normalized", "oxygen_saturation"):      ow_normalized.oxygen_saturation,
+})
+
+
+def lookup(source: str, data_type: str) -> _Converter:
+    """Return the registered converter, or raise ``ConversionError``."""
+    try:
+        return REGISTRY[(source, data_type)]
+    except KeyError as e:
+        raise ConversionError(
+            f"No converter for source={source!r} data_type={data_type!r}"
+        ) from e

omh_shim-1.0.2/omh_shim/_helpers.py

@@ -0,0 +1,123 @@
+"""Shared helpers for source converters."""
+
+import uuid
+from collections.abc import Callable, Mapping
+from datetime import UTC, datetime, timedelta, tzinfo
+from typing import Any
+
+from omh_shim.errors import ConversionError
+
+
+def parse_datetime(value: Any) -> datetime:
+    """Parse an ISO-8601 string into a timezone-aware datetime.
+
+    Rejects naive datetimes — silent UTC coercion is a clinical-data footgun.
+    """
+    if isinstance(value, datetime):
+        dt = value
+    elif isinstance(value, str):
+        s = value.strip()
+        if s.endswith("Z"):
+            s = s[:-1] + "+00:00"
+        try:
+            dt = datetime.fromisoformat(s)
+        except ValueError as e:
+            raise ConversionError(f"invalid ISO-8601 datetime: {value!r}") from e
+    else:
+        raise ConversionError(
+            f"expected ISO-8601 datetime string, got {type(value).__name__}"
+        )
+    if dt.tzinfo is None:
+        raise ConversionError(
+            f"datetime {value!r} has no timezone; omh-shim requires explicit "
+            "timezone offsets to avoid silently misaligning clinical data"
+        )
+    return dt
+
+
+def isoformat(dt: datetime) -> str:
+    """ISO-8601 with ``Z`` suffix when the offset is UTC."""
+    return dt.isoformat().replace("+00:00", "Z")
+
+
+def day_interval(date_str: str, *, tz: tzinfo | None) -> dict[str, Any]:
+    """OMH time_interval covering one calendar day in ``tz``. Raises if
+    ``tz`` is None — a "day" in Tokyo is not a "day" in UTC."""
+    if tz is None:
+        raise ConversionError(
+            "this data type requires an explicit timezone — pass tz=... to "
+            "convert() so day boundaries reflect the user's local calendar day"
+        )
+    start = datetime.fromisoformat(date_str).replace(tzinfo=tz)
+    end = start + timedelta(days=1)
+    return {"start_date_time": isoformat(start), "end_date_time": isoformat(end)}
+
+
+def interval_from_bounds(start: str, end: str) -> dict[str, Any]:
+    """OMH time_interval from explicit start/end ISO-8601 strings."""
+    return {
+        "start_date_time": isoformat(parse_datetime(start)),
+        "end_date_time": isoformat(parse_datetime(end)),
+    }
+
+
+def date_time_frame(timestamp: Any) -> dict[str, Any]:
+    """OMH effective_time_frame with a single date_time."""
+    return {"date_time": isoformat(parse_datetime(timestamp))}
+
+
+def unit_value(
+    value: Any,
+    unit: str,
+    cast: Callable[[Any], Any] = float,
+) -> dict[str, Any]:
+    """OMH unit_value: ``{"value": cast(value), "unit": unit}``."""
+    return {"value": cast(value), "unit": unit}
+
+
+def build_header(
+    schema_id: str,
+    *,
+    external_datasheets: list[dict[str, str]] | None = None,
+) -> dict[str, Any]:
+    """Build an IEEE 1752.1 data-point header per ``header-1.0.json``.
+
+    Properties conform to the IEEE 1752.1 header schema:
+    ``uuid``, ``schema_id``, ``source_creation_date_time`` (required);
+    ``modality``, ``external_datasheets`` (optional).
+
+    ``acquisition_provenance`` is NOT included — it belongs to the older
+    OMH data-point schema, not the IEEE 1752.1 standard.
+    """
+    namespace, name, version = schema_id.split(":", 2)
+    header: dict[str, Any] = {
+        "uuid": str(uuid.uuid4()),
+        "schema_id": {
+            "namespace": namespace,
+            "name": name,
+            "version": version,
+        },
+        "source_creation_date_time": isoformat(datetime.now(UTC)),
+        "modality": "sensed",
+    }
+    if external_datasheets:
+        header["external_datasheets"] = external_datasheets
+    return header
+
+
+def set_optional(
+    out: dict[str, Any],
+    out_key: str,
+    sample: Mapping[str, Any],
+    field: str,
+    *,
+    unit: str,
+    cast: Callable[[Any], Any] = float,
+    scale: float = 1,
+) -> None:
+    """Set ``out[out_key]`` to a unit_value if ``sample[field]`` is present
+    and not None. Scale is applied before cast (so 32.5 min * 60 -> 1950 sec)."""
+    v = sample.get(field)
+    if v is None:
+        return
+    out[out_key] = {"value": cast(v * scale), "unit": unit}

omh_shim-1.0.2/omh_shim/_schema_loader.py

@@ -0,0 +1,36 @@
+"""Load vendored OMH JSON schemas by schema id.
+
+Uses an explicit lookup table instead of string substitution to avoid
+filename collisions (``omh:a.b:1.0`` and ``omh:a-b:1.0`` would collide
+under ``:``->``_``, ``.``->``-`` encoding).
+"""
+
+import importlib.resources
+import json
+from functools import cache
+from typing import Any
+
+_FILENAMES: dict[str, str] = {
+    "omh:heart-rate:2.0": "omh_heart-rate_2-0.json",
+    "local:heart-rate-variability:1.0": "local_heart-rate-variability_1-0.json",
+    "omh:step-count:3.0": "omh_step-count_3-0.json",
+    "omh:sleep-duration:2.0": "omh_sleep-duration_2-0.json",
+    "omh:sleep-episode:1.1": "omh_sleep-episode_1-1.json",
+    "omh:physical-activity:1.2": "omh_physical-activity_1-2.json",
+    "omh:oxygen-saturation:2.0": "omh_oxygen-saturation_2-0.json",
+}
+
+
+def known_ids() -> frozenset[str]:
+    """Schema ids this loader has filename entries for."""
+    return frozenset(_FILENAMES)
+
+
+@cache
+def load(schema_id: str) -> dict[str, Any]:
+    """Load a vendored JSON schema by id. Raises KeyError if unknown."""
+    filename = _FILENAMES[schema_id]
+    resource = importlib.resources.files("omh_shim.schemas").joinpath(filename)
+    with resource.open("r", encoding="utf-8") as f:
+        loaded: dict[str, Any] = json.load(f)
+    return loaded

omh_shim-1.0.2/omh_shim/_validate.py

@@ -0,0 +1,64 @@
+"""Validate converter outputs against vendored OMH schemas.
+
+OMH schemas use ``$ref`` to reference other schemas by relative filename
+(e.g. ``"unit-value-1.x.json"``). All transitively-referenced schemas are
+vendored alongside the top-level OMH schemas in ``omh_shim/schemas/`` so
+ref resolution can be served from local files without network access.
+"""
+
+import importlib.resources
+import json
+from functools import lru_cache
+from typing import Any
+
+from jsonschema import Draft7Validator
+from referencing import Registry, Resource
+from referencing.jsonschema import DRAFT7
+
+from omh_shim._schema_loader import load as load_schema
+from omh_shim.errors import ValidationError
+
+
+# maxsize is bounded to a small constant: there are currently 6 top-level
+# schema ids (see omh_shim.SCHEMA_IDS). 16 leaves room for future types
+# without making the cache unbounded.
+@lru_cache(maxsize=16)
+def _validator(schema_id: str) -> Draft7Validator:
+    """Cached Draft7Validator per schema id. Built once, reused across calls."""
+    return Draft7Validator(load_schema(schema_id), registry=_registry())
+
+
+@lru_cache(maxsize=1)
+def _registry() -> Registry:
+    """Build a referencing.Registry that serves every vendored schema by filename."""
+    schemas_pkg = importlib.resources.files("omh_shim.schemas")
+    resources = []
+    for entry in schemas_pkg.iterdir():
+        name = entry.name
+        if not name.endswith(".json"):
+            continue
+        with entry.open("r", encoding="utf-8") as f:
+            doc = json.load(f)
+        resources.append((name, Resource.from_contents(doc, default_specification=DRAFT7)))
+    return Registry().with_resources(resources)
+
+
+def validate_output(output: dict[str, Any], schema_id: str) -> None:
+    """Validate ``output`` against the OMH schema identified by ``schema_id``.
+
+    Raises ``ValidationError`` with a human-readable message listing all
+    violations. Returns ``None`` on success.
+    """
+    errors = sorted(
+        _validator(schema_id).iter_errors(output),
+        key=lambda e: list(e.absolute_path),
+    )
+    if not errors:
+        return
+    pieces = []
+    for e in errors:
+        path = "/".join(str(p) for p in e.absolute_path) or "<root>"
+        pieces.append(f"{path}: {e.message}")
+    raise ValidationError(
+        f"Output does not conform to {schema_id}: " + "; ".join(pieces)
+    )