Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions .agents/summary/components.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion .agents/summary/data_models.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.).
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
schema: spec-driven
created: 2026-11-16
skip_specs: true
Original file line number Diff line number Diff line change
@@ -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[<Alias>, 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.
Original file line number Diff line number Diff line change
@@ -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
Original file line number Diff line number Diff line change
@@ -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.
Loading
Loading