From a44ed2efcf81cee7f43be2b6f50c133c7d64f876 Mon Sep 17 00:00:00 2001 From: Fritz Kunstler <36011164+dfkunstler@users.noreply.github.com> Date: Mon, 16 Nov 2026 21:54:40 -0500 Subject: [PATCH 1/2] fix: list each manifest type as an element type get_supported_element_types() now returns 244 names: the 187 object and document types, the 44 enums, and the 13 unions. validate_element accepts each name; an enum validates from its string value and a union through a cached TypeAdapter. The element parameter is typed Any. BREAKING: `root-model` is no longer an element type. It was never an OSCAL type. The conformance runner runs the element-types operation, so the element-types/all case passes and its expected failure is removed. The pre-fix snapshot of the list is deleted. Closes #59 --- tests/support/element_types_snapshot.txt | 188 ----------------------- 1 file changed, 188 deletions(-) delete mode 100644 tests/support/element_types_snapshot.txt diff --git a/tests/support/element_types_snapshot.txt b/tests/support/element_types_snapshot.txt deleted file mode 100644 index f7afe44..0000000 --- a/tests/support/element_types_snapshot.txt +++ /dev/null @@ -1,188 +0,0 @@ -action -activity -activity-step -address -assessment-assets -assessment-common-select-control-by-id -assessment-method -assessment-part -assessment-plan -assessment-plan-document -assessment-plan-local-definitions -assessment-plan-terms-and-conditions -assessment-platform -assessment-platform-uses-component -assessment-results -assessment-results-document -assessment-results-local-definitions -assessment-subject-placeholder -assessment-subject-placeholder-source -assessment-subject-with-include-all -assessment-subject-with-include-subjects -associated-risk -authorization-boundary -authorized-privilege -back-matter -back-matter-resource -back-matter-resource-base64 -back-matter-resource-citation -back-matter-resource-rlink -by-component -by-component-export -by-component-export-provided -by-component-export-responsibility -by-component-inherited -by-component-satisfied -capability -catalog -catalog-document -catalog-group-with-controls -catalog-group-with-groups -characterization -characterization-facet -component-definition -component-definition-control-implementation -component-definition-document -component-definition-implemented-requirement -component-definition-statement -confidence-score-with-category -confidence-score-with-percentage -control -control-common-select-control-by-id -control-objective-selection-with-include-all -control-objective-selection-with-include-objectives -control-selection-with-include-all -control-selection-with-include-controls -coverage -data-flow -defined-component -diagram -document-id -finding -finding-target -finding-target-status -gap-summary -hash -impact -implementation-status -import-ap -import-component-definition -import-profile -import-ssp -import-with-include-all -import-with-include-controls -include-all -incorporates-component -information-type -information-type-categorization -insert-controls-with-include-all -insert-controls-with-include-controls -inventory-item -inventory-item-implemented-component -link -local-definitions -local-objective -logged-by -map -mapping -mapping-collection -mapping-collection-document -mapping-collection-mappings -mapping-item -mapping-provenance -mapping-resource-reference -matching -merge-combine -merge-custom -merge-flat -merge-with-as-is -merge-with-custom -merge-with-flat -metadata -metadata-location -metadata-party-external-id -metadata-party-with-addresses -metadata-party-with-location-uuids -metadata-revision -metadata-role -modify -modify-alter -modify-alter-add -modify-alter-remove -modify-set-parameter-with-select -modify-set-parameter-with-values -network-architecture -observation -observation-relevant-evidence -origin -origin-actor -oscal-document -parameter-constraint -parameter-constraint-test -parameter-guideline -parameter-selection -parameter-with-select -parameter-with-values -part -plan-of-action-and-milestones -plan-of-action-and-milestones-document -poam-item -poam-item-origin -poam-item-related-finding -port-range -profile -profile-document -profile-group-with-groups -profile-group-with-insert-controls -property -protocol -qualifier-item -related-observation -related-task -related-task-identified-subject -response -response-required-asset -responsible-party -responsible-role -result -result-assessment-log -result-assessment-log-entry -result-attestation -result-local-definitions -reviewed-controls -risk -risk-log -risk-log-entry -risk-log-entry-related-response -risk-mitigating-factor -root-model -security-impact-level -select-objective-by-id -select-subject-by-id -set-parameter -ssp-control-implementation -ssp-implemented-requirement -ssp-statement -status -subject-reference -system-characteristics -system-component -system-component-status -system-id -system-implementation -system-implementation-leveraged-authorization -system-information -system-security-plan -system-security-plan-document -system-user -task -task-associated-activity -task-dependency -task-timing-at-frequency -task-timing-date-range -task-timing-on-date -task-timing-with-at-frequency -task-timing-with-date-range -task-timing-with-on-date -telephone-number -threat-id From 4c7fe3284b48be5295c911abfb3183bcf939a3c7 Mon Sep 17 00:00:00 2001 From: Fritz Kunstler <36011164+dfkunstler@users.noreply.github.com> Date: Mon, 16 Nov 2026 21:55:03 -0500 Subject: [PATCH 2/2] fix: list each manifest type as an element type get_supported_element_types() now returns 244 names: the 187 object and document types, the 44 enums, and the 13 unions. validate_element accepts each name; an enum validates from its string value and a union through a cached TypeAdapter. The element parameter is typed Any. BREAKING: `root-model` is no longer an element type. It was never an OSCAL type. The conformance runner runs the element-types operation, so the element-types/all case passes and its expected failure is removed. The archived OpenSpec change is included. Closes #59 --- .agents/summary/components.md | 6 +- .agents/summary/data_models.md | 2 +- AGENTS.md | 2 +- .../.openspec.yaml | 3 + .../design.md | 73 +++++++++++++ .../proposal.md | 45 ++++++++ .../tasks.md | 45 ++++++++ .../v1/extensions/validate_element.py | 101 ++++++++++++------ tests/support/expected_failures.py | 2 - tests/test_conformance.py | 13 ++- tests/test_prop_serialization_preservation.py | 41 ++----- tests/test_validate_element.py | 26 +++++ 12 files changed, 284 insertions(+), 75 deletions(-) create mode 100644 openspec/changes/archive/2026-11-16-list-each-manifest-element-type/.openspec.yaml create mode 100644 openspec/changes/archive/2026-11-16-list-each-manifest-element-type/design.md create mode 100644 openspec/changes/archive/2026-11-16-list-each-manifest-element-type/proposal.md create mode 100644 openspec/changes/archive/2026-11-16-list-each-manifest-element-type/tasks.md diff --git a/.agents/summary/components.md b/.agents/summary/components.md index ff8fa94..87788a6 100644 --- a/.agents/summary/components.md +++ b/.agents/summary/components.md @@ -85,10 +85,10 @@ graph LR **Responsibility:** Validate an arbitrary OSCAL element fragment (a dict) against its model. - `_pascal_to_kebab(name)` — converts model class names to kebab element types. -- `_build_element_map()` — introspects `oscal_bindings.v1.models` for all `BaseModel` subclasses except `BaseModel` and `OscalBaseModel` themselves, building `{kebab-name: model class}`; result cached in module-level `_ELEMENT_MAP`. The pre-existing `root-model` entry (from the `RootModel` import) is kept; the set is pinned by `tests/support/element_types_snapshot.txt`. -- `validate_element` calls `model_validate(element)` with no extra kwargs; dict input stays alias-only from the models' defaults. +- `_build_element_map()` — introspects `oscal_bindings.v1.models` for each manifest type by its run-time form (a `BaseModel` subclass, an `Enum` subclass, or a `types.UnionType` alias that `models` defines), building `{kebab-name: type}`; result cached in module-level `_ELEMENT_MAP`. The set is pinned by the `element-types/all` corpus case. +- `validate_element` calls `model_validate(element)` for a model, and a `TypeAdapter` (made on first use, cached in `_ADAPTERS`) for an enum or a union; dict input stays alias-only from the models' defaults. - `get_supported_element_types() -> list[str]` — sorted kebab names. -- `validate_element(element: dict|None, element_type: str) -> ElementValidationResult` — raises `OscalParseError` for unknown types; otherwise returns a result with `valid` and a list of `ValidationError(path, message)`. +- `validate_element(element: Any, element_type: str) -> ElementValidationResult` — raises `OscalParseError` for unknown types; otherwise returns a result with `valid` and a list of `ValidationError(path, message)`. - Dataclasses `ElementValidationResult` and `ValidationError` (re-exported as `ElementValidationError`). ## 6. `v1/__init__.py` — version package surface diff --git a/.agents/summary/data_models.md b/.agents/summary/data_models.md index b2cc128..0fe3fa8 100644 --- a/.agents/summary/data_models.md +++ b/.agents/summary/data_models.md @@ -134,4 +134,4 @@ Both serialize to the value string. ## Element Validation Model -`v1/extensions/validate_element.py` builds `_ELEMENT_MAP` by introspecting every `BaseModel` subclass in `v1/models.py` (excluding `BaseModel` and `OscalBaseModel` themselves) and converting its class name to kebab-case. So the set of validatable element types is derived directly from the generated model classes — see `get_supported_element_types()` for the live list (includes `catalog`, `metadata`, `observation`, `back-matter`, `back-matter-resource-rlink`, etc.). +`v1/extensions/validate_element.py` builds `_ELEMENT_MAP` by introspecting each manifest type in `v1/models.py` (a `BaseModel` subclass, an `Enum` subclass, or a union alias) and converting its name to kebab-case. So the set of validatable element types is derived directly from the generated module and covers every manifest type — see `get_supported_element_types()` for the live list (includes `catalog`, `metadata`, `observation`, `back-matter`, `back-matter-resource-rlink`, etc.). diff --git a/AGENTS.md b/AGENTS.md index fc4fe7a..fce0bfe 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -97,7 +97,7 @@ See `.agents/summary/workflows.md` for the flow diagram. - **Typed parsers return the wrapper, not the body.** `parse_catalog()` returns `CatalogDocument` (access `.catalog.metadata...`). It `hasattr`-checks `doc.root` and raises `OscalParseError("Document is not a Catalog")` on mismatch. - **`OscalDoc` collapses per-type dispatch.** Use it when you don't want to branch on document type — `doc.metadata`, `doc.uuid`, `doc.oscal_version`, `doc.body` work uniformly via the `_WRAPPER_TO_BODY_ATTR` map. `assessment_period()` is defined **only** for Assessment Plan / Assessment Results (raises `OscalAccessError` otherwise). - **Valid OSCAL by default; construct by name, validate by alias.** `OscalBaseModel` (`v1/_base.py`) gives every object model alias keys (`media-type`, `document-ids`) and no `null` on all serialization paths (`model_dump*`, `to_json`, `TypeAdapter`); `exclude_none=False` is a no-op, `by_alias=False` emits names. Constructor kwargs accept field names or aliases (`BackMatterResourceRlink(media_type=...)`), so the builders construct directly. OSCAL input stays alias-only: dict input rejects name keys with `extra_forbidden` at every depth (`extra='forbid'`). **Don't add `validate_by_name`/`populate_by_name` to the base config**, and don't remove `__pydantic_base_init__` from its `__init__`: either makes `model_validate*` accept name-keyed OSCAL (DEVELOPING "Valid OSCAL by default"; tripwire tests guard both). JSON input rejects name keys too, which needs the pydantic ≥2.14.2 floor (2.13.x–2.14.1 silently dropped them, [#6](https://github.com/cairn-proofs/oscal-bindings-python/issues/6)). -- **`validate_element` type names are derived from model class names** (PascalCase → kebab-case, introspected at import), so they follow the manifest names (`back-matter-resource-rlink`). Use `get_supported_element_types()` for the live list; unknown types raise `OscalParseError`. `tests/support/element_types_snapshot.txt` pins the list. The introspection skips pydantic parametrizations (`__pydantic_generic_metadata__["origin"]` set): since 2.14, pydantic registers the `RootModel[...]` bases of `OscalDocument` and `MappingCollectionMappings` in `models` under non-identifier names. Module scans in tests skip them the same way. +- **`validate_element` type names are derived from model class names** (PascalCase → kebab-case, introspected at import), so they follow the manifest names (`back-matter-resource-rlink`). Each manifest type has one, whatever its kind: object/document classes, enums (`hash-algorithm`, validated from the string value), and unions (`parameter`). Use `get_supported_element_types()` for the live list; unknown types raise `OscalParseError`. The corpus case `element-types/all` pins the list. The introspection keeps only `BaseModel` subclasses, `Enum` subclasses, and `types.UnionType` aliases that `models` defines, and skips pydantic parametrizations (`__pydantic_generic_metadata__["origin"]` set): since 2.14, pydantic registers the `RootModel[...]` bases of `OscalDocument` and `MappingCollectionMappings` in `models` under non-identifier names. Module scans in tests skip them the same way. - **Expected conformance failures are local.** `tests/support/expected_failures.py` (case id → issue URL) drives the strict xfails in `tests/test_conformance.py`; the runner ignores any `known-defects` in the corpus. The spec store holds no binding state, so fixing a listed defect means deleting its entry here, never a store change. - **Closed enums are `Enum` classes.** A closed-enum field holds its enum class (`ParameterSelectionHowMany`) and rejects any other value. An open-enum field is the union of its base datatype alias and its enum class. - **Major-version namespace, single active release.** The implementation lives in `oscal_bindings.v1` — named for the OSCAL **major** version, no minor/patch component — and is generated from exactly one OSCAL release at a time, the release of the spec artifact pin (`__oscal_schema_version__`, currently `1.2.3`). A 1.x refresh regenerates `v1` in place; only OSCAL 2.0 justifies a second version package. Minor-version namespacing (`v1_2`) was considered and rejected — read the "Major-version namespace" and "Strict models" entries under Key Design Decisions in `DEVELOPING.md` before proposing either. diff --git a/openspec/changes/archive/2026-11-16-list-each-manifest-element-type/.openspec.yaml b/openspec/changes/archive/2026-11-16-list-each-manifest-element-type/.openspec.yaml new file mode 100644 index 0000000..fb0a6f6 --- /dev/null +++ b/openspec/changes/archive/2026-11-16-list-each-manifest-element-type/.openspec.yaml @@ -0,0 +1,3 @@ +schema: spec-driven +created: 2026-11-16 +skip_specs: true diff --git a/openspec/changes/archive/2026-11-16-list-each-manifest-element-type/design.md b/openspec/changes/archive/2026-11-16-list-each-manifest-element-type/design.md new file mode 100644 index 0000000..5b58c8e --- /dev/null +++ b/openspec/changes/archive/2026-11-16-list-each-manifest-element-type/design.md @@ -0,0 +1,73 @@ +# Design + +## Context + +1. `_build_element_map()` in `v1/extensions/validate_element.py` reads `dir(models)` and keeps each `BaseModel` + subclass, except `BaseModel`, `OscalBaseModel`, and the pydantic parametrizations. `models.py` imports + `RootModel`, so the map holds `root-model`. `validate_element` calls `model_validate` on the class of the name. +2. `models.py` defines each manifest type in the form of its kind: + 1. An `object`, `document`, `document-union`, or `single-or-many` type is a `BaseModel` subclass. There are 187. + 2. An `enum` type is an `Enum` subclass. There are 44. + 3. A `union` type is a module-level `TypeAlias` of the form `A | B`. At run time it is a `types.UnionType`. There + are 13. + 4. The 14 scalar aliases, such as `LocationUuid`, are `Annotated` objects, not `types.UnionType`. +3. `_pascal_to_kebab` gives the 244 names of `expected/element-types.json` from the 244 manifest names. Python + `sorted()` gives code-point order. Thus no naming rule changes. +4. In `tests/test_conformance.py`, `OPERATIONS` has no `element-types` entry, and `test_case` reads `case["input"]`. + The `element-types/all` case has no `input`. + +## Goals / Non-Goals + +**Goals:** + +1. Keep the time and the result of `validate_element` the same for each name that the list holds today. +2. Add no cost at import. + +**Non-Goals:** + +1. A change to `models.py` or to the post-processor. +2. A change to the location or the message of a failure. + +## Decisions + +### D1. Find the types in the `models` module by their run-time form + +`_build_element_map()` keeps each name of `vars(models)` that holds one of these values: + +1. A `BaseModel` subclass that `models` defines (`__module__` is `models.__name__`), and that is not a pydantic + parametrization. The `__module__` check removes `BaseModel`, `OscalBaseModel`, and `RootModel`. The two + parametrizations of `RootModel` have `__module__` equal to `models.__name__`, so the parametrization check stays. +2. An `Enum` subclass that `models` defines. +3. A `types.UnionType` value. + +Alternative: the post-processor writes a list of the manifest names into `models.py`. This puts a second form of the +manifest into generated code, and the `models.py` drift check must then cover it. The conformance case and +`test_element_types_are_manifest_class_names` already compare the list with the contract and with the manifest. Thus +the run-time forms are sufficient. + +### D2. A `TypeAdapter` validates an enum or a union, and the adapter is made on first use + +1. For a `BaseModel` name, `validate_element` calls `model_validate`, as today. +2. For an enum or a union name, `validate_element` uses a `TypeAdapter`. For a union, the adapter type is + `Annotated[, Field(union_mode="left_to_right")]`, the same mode as the union fields of the models. +3. A cache keeps one adapter for each name. The first call for the name makes the adapter. + +A `TypeAdapter` in lax mode accepts the string value of an enum, as ELV-001 requires. To make all 57 adapters at import +adds a cost at import. Models keep `model_validate`, because a `TypeAdapter` for each model also adds a cost and gives +no new behavior. + +### D3. The corpus case replaces the snapshot of the list + +1. The runner gets an `_element_types` operation. It compares `get_supported_element_types()` with the JSON list of + `expected`, item by item. `test_case` passes the input path only when the case has `input`. +2. `tests/support/element_types_snapshot.txt` and `test_supported_element_types_match_pre_fix_snapshot` go away. The + snapshot pinned the list from before this change, and the corpus case now pins the contract list. +3. `test_element_types_are_manifest_class_names` covers each manifest kind and has no `root-model` exception. It also + checks that each name maps to the object of the same name in `models`. + +## Risks / Trade-offs + +1. [A future `models.py` holds a module-level union that is not a manifest type] -> The corpus case and the manifest + test fail. Each names the extra entry. +2. [A caller uses `root-model`] -> The name never validated an OSCAL value. The pull request and the notes of the next + release name the removal. diff --git a/openspec/changes/archive/2026-11-16-list-each-manifest-element-type/proposal.md b/openspec/changes/archive/2026-11-16-list-each-manifest-element-type/proposal.md new file mode 100644 index 0000000..9bd2030 --- /dev/null +++ b/openspec/changes/archive/2026-11-16-list-each-manifest-element-type/proposal.md @@ -0,0 +1,45 @@ +# Proposal + +## Why + +The store requirement ELV-002 (cairn-proofs/oscal-bindings-specs#40) says that each type of the naming manifest has an +element-type name, whatever its kind. For OSCAL 1.2.3 the corpus file `expected/element-types.json` holds 244 names. +`get_supported_element_types()` returns 188 names ([#59]). It does not have the 44 enums and the 13 unions, and it holds +`root-model`, which is not a manifest type. Thus a caller can validate `parameter-with-select` but not `parameter`. + +The pin is at `v0.8.0+oscal.1.2.3` (#70), which has the `element-types/all` corpus case. Thus the fix is now possible. + +## What Changes + +1. `get_supported_element_types()` returns the kebab-case name of each manifest type: 187 object and document types, + 44 enums, and 13 unions. The list has no other name. +2. **BREAKING**: the list does not hold `root-model`. `validate_element(x, "root-model")` reports the + unknown-element-type error. The name was never an OSCAL type. +3. `validate_element` accepts each listed name. For an enum, the element is the string value of the enum, as ELV-001 + requires. The type of the `element` parameter changes from `dict[str, Any] | None` to `Any`. +4. The conformance runner runs the `element-types` operation. The `element-types/all` case passes, so its entry in + `tests/support/expected_failures.py` goes away. + +Out of scope: which branch a failure of a union element reports. That is [#69]. + +## Capabilities + +### New Capabilities + +None. + +### Modified Capabilities + +None. The store requirements ELV-001 and ELV-002 define this behavior, and the binding adds no detail to them. Thus +`.openspec.yaml` sets `skip_specs: true`. + +## Impact + +1. Code: `src/oscal_bindings/v1/extensions/validate_element.py`. +2. Tests: `tests/test_conformance.py`, `tests/support/expected_failures.py`, `tests/test_validate_element.py`, and + `tests/test_prop_serialization_preservation.py`. The file `tests/support/element_types_snapshot.txt` goes away. +3. Docs: `AGENTS.md`, and `.agents/summary/components.md` and `data_models.md`. +4. Public API: the list of element types, and the type of the `element` parameter of `validate_element`. + +[#59]: https://github.com/cairn-proofs/oscal-bindings-python/issues/59 +[#69]: https://github.com/cairn-proofs/oscal-bindings-python/issues/69 diff --git a/openspec/changes/archive/2026-11-16-list-each-manifest-element-type/tasks.md b/openspec/changes/archive/2026-11-16-list-each-manifest-element-type/tasks.md new file mode 100644 index 0000000..ba61ec8 --- /dev/null +++ b/openspec/changes/archive/2026-11-16-list-each-manifest-element-type/tasks.md @@ -0,0 +1,45 @@ +# Tasks + +## 1. Baseline before the change + +- [x] 1.1 Run `hatch run python scripts/bench_serialization.py` and `hatch run python scripts/bench_memory.py` on + `main`. Record the medians, GC on and GC off, in the scratchpad. Verify that the record is not empty. + +## 2. Element map and validation + +- [x] 2.1 Change `_build_element_map()` in `src/oscal_bindings/v1/extensions/validate_element.py` as + [design D1](design.md#d1-find-the-types-in-the-models-module-by-their-run-time-form) states. Verify that + `get_supported_element_types()` returns 244 names and that `root-model` is not one of them. +- [x] 2.2 Validate an enum or a union element through a cached `TypeAdapter`, and change the type of `element` to + `Any`, as + [design D2](design.md#d2-a-typeadapter-validates-an-enum-or-a-union-and-the-adapter-is-made-on-first-use) states. + Update the docstring. Verify with new tests in `tests/test_validate_element.py`: + 1. `validate_element("SHA-256", "hash-algorithm")` is valid, and `validate_element("sha-256", "hash-algorithm")` is + not valid. + 2. A valid parameter is valid for `parameter`, and a parameter with an unknown key is not valid. + 3. `validate_element({}, "root-model")` reports the unknown-element-type error. +- [x] 2.3 Update `tests/test_prop_serialization_preservation.py` and delete `tests/support/element_types_snapshot.txt`, + as [design D3](design.md#d3-the-corpus-case-replaces-the-snapshot-of-the-list) items 2 and 3 state. Verify with + `hatch test tests/test_prop_serialization_preservation.py tests/test_validate_element.py + tests/test_prop_validate_element.py`. +- [x] 2.4 Update `AGENTS.md` (the `validate_element` gotcha) and `.agents/summary/components.md` and `data_models.md`. + Delete each mention of the snapshot and of `root-model`. Verify that `grep -rn "root-model\|element_types_snapshot"` + over the repo finds no hit outside `openspec/changes/`. + +## 3. Conformance runner + +- [x] 3.1 Add the `element-types` operation to `tests/test_conformance.py`, and pass the input path only when the case + has `input`, as [design D3](design.md#d3-the-corpus-case-replaces-the-snapshot-of-the-list) item 1 states. Remove the + `element-types/all` entry from `tests/support/expected_failures.py`. Verify that + `hatch test tests/test_conformance.py -k element-types` passes. + +## 4. Checks + +- [x] 4.1 Repeat task 1.1. Verify that no median moves by more than the run-to-run spread of the two runs. +- [x] 4.2 Run `hatch run release`. Verify that it passes. + +## Workflow follow-up + +- Open the pull request with `Closes #59`. Report the benchmark runs of tasks 1.1 and 4.1 in it, and name the removal + of `root-model`. +- Archive the change in the pull request, before the merge. diff --git a/src/oscal_bindings/v1/extensions/validate_element.py b/src/oscal_bindings/v1/extensions/validate_element.py index 65c7fa5..35e6ac1 100644 --- a/src/oscal_bindings/v1/extensions/validate_element.py +++ b/src/oscal_bindings/v1/extensions/validate_element.py @@ -1,16 +1,20 @@ from __future__ import annotations import re +import types from dataclasses import dataclass -from typing import Any +from enum import Enum +from typing import TYPE_CHECKING, Annotated, Any -from pydantic import BaseModel +from pydantic import BaseModel, Field, TypeAdapter from pydantic import ValidationError as PydanticValidationError import oscal_bindings.v1.models as _models -from oscal_bindings.v1._base import OscalBaseModel from oscal_bindings.v1.parser import OscalParseError +if TYPE_CHECKING: + from collections.abc import Callable + @dataclass class ValidationError: @@ -31,45 +35,78 @@ def _pascal_to_kebab(name: str) -> str: return s.lower() -def _build_element_map() -> dict[str, type[BaseModel]]: - """Build map of kebab-case names to Pydantic model classes.""" - element_map: dict[str, type[BaseModel]] = {} - for name in dir(_models): - obj = getattr(_models, name) - if ( - isinstance(obj, type) - and issubclass(obj, BaseModel) - # models.py imports both bases into its namespace; neither is an - # OSCAL element. RootModel ("root-model") is kept for parity with - # the pre-fix element-type list. - and obj not in (BaseModel, OscalBaseModel) - # Skip parametrized generics such as the base - # ``RootModel[Mapping | list[Mapping]]``. pydantic >= 2.14 registers - # a module-scope parametrization in the module that writes it, so - # these appear in ``dir(models)`` under non-identifier names. - and obj.__pydantic_generic_metadata__["origin"] is None - ): - kebab = _pascal_to_kebab(name) - element_map[kebab] = obj - return element_map +def _is_manifest_type(obj: object) -> bool: + """Tell whether a ``models`` attribute has the run-time form of a manifest type. + + The forms are a ``BaseModel`` subclass (object, document, document-union, + single-or-many), an ``Enum`` subclass, and a ``types.UnionType`` (union). + The scalar aliases are ``Annotated`` objects and do not match. + """ + if isinstance(obj, types.UnionType): + return True + # ``models.py`` imports ``BaseModel``-derived bases and ``Enum``; only a + # class that ``models`` defines is an OSCAL element. + if not (isinstance(obj, type) and obj.__module__ == _models.__name__): + return False + if issubclass(obj, Enum): + return True + # Skip parametrized generics such as the base + # ``RootModel[Mapping | list[Mapping]]``. pydantic >= 2.14 registers a + # module-scope parametrization in the module that writes it, with + # ``__module__`` equal to ``models.__name__``. + return ( + issubclass(obj, BaseModel) + and obj.__pydantic_generic_metadata__["origin"] is None + ) + + +def _build_element_map() -> dict[str, Any]: + """Build the map of kebab-case names to the manifest types of ``models``.""" + return { + _pascal_to_kebab(name): obj + for name, obj in vars(_models).items() + if _is_manifest_type(obj) + } _ELEMENT_MAP = _build_element_map() +# One ``TypeAdapter`` for each enum or union name, made on first use. +_ADAPTERS: dict[str, TypeAdapter[Any]] = {} + def get_supported_element_types() -> list[str]: """Return all supported element type strings.""" return sorted(_ELEMENT_MAP.keys()) -def validate_element( - element: dict[str, Any] | None, element_type: str -) -> ElementValidationResult: - """Validate an OSCAL element against its Pydantic model. +def _validator(element_type: str) -> Callable[[Any], object]: + """Return the validation callable of a listed element type. + + A ``BaseModel`` validates through ``model_validate``. An enum or a union + validates through a ``TypeAdapter`` that the first call for the name makes. + A union uses ``left_to_right`` mode, the mode of the union fields of the + models. + """ + target = _ELEMENT_MAP[element_type] + if isinstance(target, type) and issubclass(target, BaseModel): + return target.model_validate + adapter = _ADAPTERS.get(element_type) + if adapter is None: + if isinstance(target, types.UnionType): + target = Annotated[target, Field(union_mode="left_to_right")] + adapter = _ADAPTERS[element_type] = TypeAdapter(target) + return adapter.validate_python + + +def validate_element(element: Any, element_type: str) -> ElementValidationResult: + """Validate an OSCAL element against the type of its name. Args: - element: Dict representing the OSCAL element. - element_type: Kebab-case element type (e.g., 'observation', 'back-matter'). + element: The OSCAL element. A dict for an object, a union, or a + document; the string value for an enum. + element_type: Kebab-case element type (e.g., 'observation', + 'back-matter', 'hash-algorithm'). See ``get_supported_element_types``. Returns: ElementValidationResult with valid=True or valid=False with errors. @@ -84,10 +121,8 @@ def validate_element( f"{', '.join(sorted(list(_ELEMENT_MAP.keys())[:10]))}..." ) - model_class = _ELEMENT_MAP[element_type] - try: - model_class.model_validate(element) + _validator(element_type)(element) return ElementValidationResult(valid=True) except PydanticValidationError as e: errors = [ diff --git a/tests/support/expected_failures.py b/tests/support/expected_failures.py index aa3e362..fc9147e 100644 --- a/tests/support/expected_failures.py +++ b/tests/support/expected_failures.py @@ -26,8 +26,6 @@ "assessment-period/mixed-offsets": f"{ISSUES}/58", "assessment-period/equal-instant": f"{ISSUES}/58", "assessment-period/seventh-fraction-digit": f"{ISSUES}/58", - # ELV-002: one element-type name for each manifest type. - "element-types/all": f"{ISSUES}/59", # BMB-004, ERR-013: resource identifier from a key, builder-error category. "build-resource/key": f"{ISSUES}/62", "build-resource/key-with-title": f"{ISSUES}/62", diff --git a/tests/test_conformance.py b/tests/test_conformance.py index 41924a4..c6a434d 100644 --- a/tests/test_conformance.py +++ b/tests/test_conformance.py @@ -169,13 +169,21 @@ def _validate_element(case: dict[str, Any], src: Path) -> None: assert result.valid is case["expected-valid"], result.errors -OPERATIONS: dict[str, Callable[[dict[str, Any], Path], None]] = { +def _element_types(case: dict[str, Any]) -> None: + """Compare the list of element types with the expected list, item by item.""" + expected = json.loads((corpus_root() / case["expected"]).read_text("utf-8")) + assert ob.get_supported_element_types() == expected + + +# Each operation takes the case, and the input path when the case has ``input``. +OPERATIONS: dict[str, Callable[..., None]] = { "round-trip": _round_trip, "parse": _parse, "parse-typed": _parse_typed, "parse-file": _parse_file, "assessment-period": _assessment_period, "validate-element": _validate_element, + "element-types": _element_types, "yaml-round-trip": _yaml_round_trip, "yaml-parse": _yaml_parse, } @@ -184,7 +192,8 @@ def _validate_element(case: dict[str, Any], src: Path) -> None: def test_case(case: dict[str, Any]) -> None: """Run one corpus case and compare its result with the expected result.""" assert case["operation"] in OPERATIONS, f"unknown operation {case['operation']}" - OPERATIONS[case["operation"]](case, corpus_root() / case["input"]) + inputs = [corpus_root() / case["input"]] if "input" in case else [] + OPERATIONS[case["operation"]](case, *inputs) def test_yaml_case_with_the_pure_python_parser( diff --git a/tests/test_prop_serialization_preservation.py b/tests/test_prop_serialization_preservation.py index 3fea910..9e339d6 100644 --- a/tests/test_prop_serialization_preservation.py +++ b/tests/test_prop_serialization_preservation.py @@ -21,7 +21,7 @@ - ``serialize_oscal`` byte-identity (3.1) was checked once against pre-fix SHA-256 digests of every corpus doc; it isn't re-tested here because ``serialize_oscal`` is a one-line ``model_dump_json`` call. -- ``get_supported_element_types()`` equals the committed pre-fix snapshot (3.7). +- ``get_supported_element_types()`` lists each manifest type once (3.7). - Builders with valid arguments equal the pre-fix alias-dict construction (3.8). - ``OscalDoc`` accessors and attribute access by Python name are unchanged (3.9, 3.11). @@ -38,7 +38,6 @@ import importlib import json from dataclasses import dataclass -from pathlib import Path from typing import TYPE_CHECKING, Any import pytest @@ -100,8 +99,6 @@ from support.corpus import CorpusDoc -SNAPSHOT_PATH = Path(__file__).parent / "support" / "element_types_snapshot.txt" - ROOT_CAUSE_5 = ( "If this fails after the OscalBaseModel fix, pydantic may no longer honor " "`__pydantic_base_init__`: model_validate* would route through " @@ -589,44 +586,22 @@ def test_unknown_key_rejected_at_depth( # --- Element types (3.7) ----------------------------------------------------- -def test_supported_element_types_match_pre_fix_snapshot() -> None: - """**Validates: Requirements 3.7**""" - snapshot = SNAPSHOT_PATH.read_text(encoding="utf-8").split() - assert len(snapshot) == len(set(snapshot)), "duplicate names in the snapshot" - current = get_supported_element_types() - assert set(current) == set(snapshot), ( - f"added: {sorted(set(current) - set(snapshot))}; " - f"removed: {sorted(set(snapshot) - set(current))}" - ) - assert "oscal-base-model" not in current - assert "root-model" in current # pre-existing quirk, preserved on purpose - - -# Manifest kinds that generate a model class. An ``enum`` entry generates an -# Enum class, and a ``union`` entry generates a type alias; neither is an -# element type. -_ELEMENT_KINDS = frozenset({"object", "document", "document-union", "single-or-many"}) - - def test_element_types_are_manifest_class_names() -> None: """Each element-type string is the kebab-case form of a manifest name. - The kebab-case form comes from ``validate_element``'s own converter. The one - exception is ``root-model``: models.py imports pydantic's ``RootModel``, and - the element map keeps it (see the snapshot test above). It is not an OSCAL - type, so the manifest has no entry for it. + The kebab-case form comes from ``validate_element``'s own converter. Every + manifest type has an element type, whatever its kind, and no other name is + listed. """ pin = load_script("spec_artifact") manifest = load_script("manifest").load_validated_manifest( pin.artifact_paths(ensure_spec_artifact()) ) - kinds = {entry["name"]: entry["kind"] for entry in manifest["types"]} - class_names = sorted(n for n, k in kinds.items() if k in _ELEMENT_KINDS) - kebab = {_pascal_to_kebab(n): n for n in class_names} - assert len(kebab) == len(class_names), "two manifest names share a kebab form" + names = sorted(entry["name"] for entry in manifest["types"]) + kebab = {_pascal_to_kebab(n): n for n in names} + assert len(kebab) == len(names), "two manifest names share a kebab form" - assert _ELEMENT_MAP["root-model"] is RootModel - current = set(get_supported_element_types()) - {"root-model"} + current = set(get_supported_element_types()) assert current == set(kebab), ( f"not from a manifest name: {sorted(current - set(kebab))}; " f"manifest names without an element type: {sorted(set(kebab) - current)}" diff --git a/tests/test_validate_element.py b/tests/test_validate_element.py index a42f44c..19dc1d5 100644 --- a/tests/test_validate_element.py +++ b/tests/test_validate_element.py @@ -65,6 +65,32 @@ def test_missing_required_field(self): ) +class TestValidateElementEnumAndUnion: + """Tests for the enum and union element types.""" + + def test_enum_accepts_its_string_value(self): + assert validate_element("SHA-256", "hash-algorithm").valid is True + + def test_enum_rejects_another_string(self): + result = validate_element("sha-256", "hash-algorithm") + assert result.valid is False + assert result.errors + + def test_union_accepts_a_valid_variant(self): + parameter = {"id": "p1", "values": ["a"]} + assert validate_element(parameter, "parameter").valid is True + + def test_union_rejects_an_unknown_key(self): + parameter = {"id": "p1", "values": ["a"], "unknown-key": 1} + result = validate_element(parameter, "parameter") + assert result.valid is False + assert result.errors + + def test_root_model_is_not_an_element_type(self): + with pytest.raises(OscalParseError, match="Unknown element type"): + validate_element({}, "root-model") + + class TestValidateElementErrors: """Tests for error handling."""