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
2 changes: 1 addition & 1 deletion .agents/summary/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@ Consequences of that choice, as implemented:
Every OSCAL top-level document carries `metadata` and a body-level `uuid`, but the path to them differs per type (`doc.catalog.metadata` vs `doc.system_security_plan.metadata`). `OscalDoc` collapses that dispatch behind uniform properties. A class-level dict `_WRAPPER_TO_BODY_ATTR` maps each of the 8 wrapper types to its body attribute name, so `body` is a single `getattr` rather than an 8-way `if`/`elif` chain.

### Adapter / Convenience constructors — builders
`make_hash`, `make_rlink`, `make_resource` wrap the models in kwarg-friendly constructors with sensible defaults (e.g. auto UUID4, string `algorithm` coercion). Because `OscalBaseModel` accepts field-name kwargs, they construct directly (`BackMatterResourceRlink(media_type=...)`, `BackMatterResource(document_ids=...)`), so every argument, `document_ids` included, is validated at construction.
`make_hash`, `make_rlink`, `make_resource` wrap the models in kwarg-friendly constructors with sensible defaults (e.g. auto UUID4, an identifier from a `key`, string `algorithm` coercion). Each builder validates a JSON-shaped object with one `model_validate` call, so every argument, also an item of a list input that the caller made with `model_construct`, is validated. A failure raises `OscalBuilderError`.

### Hand-written base class — `OscalBaseModel`
`v1/_base.py` is the one piece of hand-written behavior generated code inherits, wired in by codegen's `--base-class` rather than by editing output. It makes default serialization valid OSCAL (`serialize_by_alias=True` plus a wrap serializer that drops None) and maps field-name constructor kwargs to aliases. Its `__init__` carries `__pydantic_base_init__` so `model_validate*` never routes through it, keeping OSCAL input alias-only. It imports only `pydantic` and stdlib, so `models.py → _base` can't cycle.
Expand Down
7 changes: 4 additions & 3 deletions .agents/summary/components.md
Original file line number Diff line number Diff line change
Expand Up @@ -79,9 +79,10 @@ graph LR

| Function | Notes |
|----------|-------|
| `make_hash(value, algorithm=HashAlgorithm.SHA_256)` | Accepts enum or string (`"SHA-256"`); coerces string via `HashAlgorithm(...)` |
| `make_rlink(href, *, media_type=None, hashes=None)` | `BackMatterResourceRlink(href=..., media_type=..., hashes=...)` — by-name kwargs via `OscalBaseModel` |
| `make_resource(*, title, description, rlinks, uuid, document_ids)` | Generates a UUID4 when `uuid` omitted; one `BackMatterResource(...)` call, so `document_ids` is validated at construction (`[]` or non-`DocumentId` items raise `ValidationError`) |
| `OscalBuilderError(message, errors)` | A `ValueError` that is not an `OscalParseError`; `errors` holds the Pydantic-shaped entries |
| `make_hash(value, algorithm=HashAlgorithm.SHA_256)` | Accepts enum or string; a string that is a `HashAlgorithm` value gives the member, any other string goes to the model as is; one `model_validate` call |
| `make_rlink(href, *, media_type=None, hashes=None)` | One `model_validate` of a JSON-shaped object; items of `hashes` are validated, also an item made with `model_construct` |
| `make_resource(*, title, description, rlinks, uuid, key, document_ids)` | `key` gives the UUID version 5 of the key (an empty key, or a key with `uuid`, raises `OscalBuilderError`); with neither, a UUID4; one `model_validate` call, so `rlinks` and `document_ids` items are validated (`[]` or non-`DocumentId` items raise `OscalBuilderError`) |

## 5. `v1/extensions/validate_element.py` — element-level validation

Expand Down
4 changes: 2 additions & 2 deletions .agents/summary/interfaces.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@ OscalDoc.assessment_period() -> tuple[date | None, date | None] # AP/AR only
```python
make_hash(value: str, algorithm: str | HashAlgorithm = HashAlgorithm.SHA_256) -> Hash
make_rlink(href: str, *, media_type: str | None = None, hashes: list[Hash] | None = None) -> BackMatterResourceRlink
make_resource(*, title=None, description=None, rlinks=None, uuid=None, document_ids=None) -> BackMatterResource
make_resource(*, title=None, description=None, rlinks=None, uuid=None, key=None, document_ids=None) -> BackMatterResource
```

### Element validation
Expand Down Expand Up @@ -128,7 +128,7 @@ sequenceDiagram
| `assessment_period()` on non-AP/AR | `OscalAccessError` |
| `OscalDoc(...)` with unrelated object | `TypeError` |
| `validate_element` unrecognized element type | `OscalUnknownElementTypeError` (outside the parse errors) |
| Builders with invalid input | `pydantic.ValidationError` |
| Builders with invalid input (also an empty `key`, or a `key` with a `uuid`) | `OscalBuilderError` (a `ValueError`, outside the parse errors; `.errors` = entries) |
| `validate_oscal` on invalid input | returns `False` (never raises) |

## Code-Generation Interface (build-time)
Expand Down
12 changes: 6 additions & 6 deletions .agents/summary/workflows.md
Original file line number Diff line number Diff line change
Expand Up @@ -144,12 +144,12 @@ sequenceDiagram
C->>H: make_hash(digest) %% default HashAlgorithm.SHA_256
H-->>C: Hash
C->>L: make_rlink(href, media_type=, hashes=[Hash])
L->>L: BackMatterResourceRlink(href=.., media_type=.., hashes=..)
L-->>C: BackMatterResourceRlink
C->>R: make_resource(title=, description=, rlinks=[BackMatterResourceRlink])
R->>R: uuid = uuid4() if not provided
R->>R: BackMatterResource(uuid=.., ..., document_ids=..)
R-->>C: BackMatterResource (validated)
L->>L: BackMatterResourceRlink.model_validate({href, media-type, hashes})
L-->>C: BackMatterResourceRlink (or OscalBuilderError)
C->>R: make_resource(title=, description=, rlinks=[BackMatterResourceRlink], key=)
R->>R: uuid = uuid5(namespace, key) if key, else uuid4() if not provided
R->>R: BackMatterResource.model_validate({uuid, ..., document-ids})
R-->>C: BackMatterResource (validated, or OscalBuilderError)
```

## 5. Element-level Validation
Expand Down
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.
- **A file-path parse finds the error category from the read itself.** `_read_oscal_file` (`v1/parser.py`) makes no `Path.exists()` call: `read_bytes` raises, and `ENOENT`, `ENOTDIR`, or a `ValueError` (a NUL byte) gives `FileNotFoundError`; each other `OSError` gives `OscalReadError(OSError)`, which is not a parse error and not a not-found error (ERR-012). `exists()` hides the `errno` and changes its answer with the Python version. `parse_oscal_file`, `parse_oscal_yaml_file`, and `OscalDoc.from_file` all share this path.
- **Typed parsers return the wrapper, not the body.** `parse_catalog()` returns `CatalogDocument` (access `.catalog.metadata...`). It `hasattr`-checks `doc.root` and raises `OscalDocumentTypeMismatchError("Document is not a Catalog")` (a subclass of `OscalParseError`) 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)).
- **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 a caller constructs directly. The builders validate a JSON-shaped object and raise `OscalBuilderError` (a `ValueError`, not an `OscalParseError`). 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`). 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; an unrecognized type raises `OscalUnknownElementTypeError`, which is not an `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.
Expand Down
2 changes: 1 addition & 1 deletion DEVELOPING.md
Original file line number Diff line number Diff line change
Expand Up @@ -220,7 +220,7 @@ changes only for a new OSCAL **major** version.
- **Major-version namespace** — the bindings live in `oscal_bindings.v1`, named for the OSCAL major version with no minor or patch component. OSCAL is backward-compatible within a major version (newer schemas accept older documents; minor bumps have not added required fields), so the compatibility boundary is the major version and one binding set covers every 1.x producer. A minor-version namespace (`v1_2`, `v1_3`) was considered and rejected: it would encode a break at each routine refresh that does not exist. `__oscal_schema_version__` records the exact release the models were generated from. This mirrors NIST's own schema `$id` (`ns/oscal/1.0/1.2.2/...`), which scopes the namespace to the major line and hangs the release off it. OSCAL 2.0 is the trigger for a second version package; nothing is factored out between version packages before then, because the seam is unknowable until 2.0's differences are in hand.
- **Strict models tie coverage to the release of the pin** — every model carries `extra='forbid'`, so bindings generated from 1.2.3 reject a later 1.x document that uses a new field. "Supports OSCAL 1.x" therefore means "supports the release of the pin and earlier"; `__oscal_schema_version__` makes that gap visible. `extra='ignore'` was rejected because `serialize_oscal` would silently drop unknown fields. An opt-in lenient mode is deferred, not rejected.
- **Valid OSCAL by default** — `v1/_base.py` defines `OscalBaseModel`, wired in through codegen's `--base-class` so `models.py` stays pristine generator output. It sets `serialize_by_alias=True` (needs pydantic ≥2.11; the floor is now 2.14.2, below) and adds a wrap `model_serializer` that drops None values, so every serialization path, including `pydantic_core.to_json` and `TypeAdapter` calls that never see our kwargs, emits OSCAL keys and no `null`. `serialize_oscal` keeps its explicit `by_alias=True, exclude_none=True`. The wrap serializer costs a Python callback per model node (benchmarks below). Per-field `Field(exclude_if=lambda v: v is None)` measured about 1.35× the pre-fix time in a prototype (the wrap serializer was about 2.4× there), with identical output, but it isn't implemented: the post-processor would have to rewrite all 698 optional fields, and `exclude_if` needs pydantic ≥2.12. It's the documented fallback if serialize time becomes a problem.
- **Construction by name, validation by alias.** `OscalBaseModel.__init__` maps field-name kwargs to aliases, so `BackMatterResourceRlink(media_type=...)` works and the builders construct directly. The override carries `__pydantic_base_init__ = True`, the marker `RootModel.__init__` uses. Without it pydantic sets `__pydantic_custom_init__` and routes `model_validate*` through `__init__`: a probe of that variant accepted and kept name-keyed input at every depth, in dict and JSON mode, even with `by_alias=True, by_name=False`. The marker is undocumented, so tests pin it structurally and behaviorally.
- **Construction by name, validation by alias.** `OscalBaseModel.__init__` maps field-name kwargs to aliases, so `BackMatterResourceRlink(media_type=...)` works. The builders do not construct directly: each validates a JSON-shaped object with `model_validate` one time and raises `OscalBuilderError`. The override carries `__pydantic_base_init__ = True`, the marker `RootModel.__init__` uses. Without it pydantic sets `__pydantic_custom_init__` and routes `model_validate*` through `__init__`: a probe of that variant accepted and kept name-keyed input at every depth, in dict and JSON mode, even with `by_alias=True, by_name=False`. The marker is undocumented, so tests pin it structurally and behaviorally.
- **Not config `validate_by_name`.** Setting `validate_by_name=True` in the base config, with per-call `by_alias=True, by_name=False` at our validation sites (Option A), was rejected. Alias-only would become opt-in per call, so a user's direct `Model.model_validate` would accept and populate name-keyed OSCAL. Nested plain dicts in constructor kwargs would accept names too. Don't add `validate_by_name`, `validate_by_alias`, or `populate_by_name` to the base config. Revisit if pydantic adds per-mode by-name validation (pydantic#12056).
- **Pydantic floor 2.14.2: JSON mode rejects name keys.** pydantic 2.13.x through 2.14.1 had `model_validate_json` silently discard a key equal to the Python name of one of the model's alias-differing fields, instead of reporting `extra_forbidden` ([#6](https://github.com/cairn-proofs/oscal-bindings-python/issues/6)). pydantic#13275, released in 2.14.2 (GHSA-qpmf-fgh3-ff25), made JSON mode match dict mode, so the runtime range is `pydantic[email]>=2.14.2,<3` and the JSON-mode tests require `extra_forbidden`. The base doesn't change JSON validation either way.
- **Parametrized bases in the models namespace.** Since 2.14, pydantic registers a module-scope parametrization such as `RootModel[Mapping | list[Mapping]]` in the module that writes it, under a non-identifier name (pydantic#13243; 2.14.2 also sets its `__module__` there, pydantic#13994). So the bases of `OscalDocument` and `MappingCollectionMappings` appear in `vars(models)`. `validate_element`'s element map and the module scans in the tests skip any class whose `__pydantic_generic_metadata__["origin"]` is set, and `test_each_parametrized_generic_of_the_module_is_a_manifest_base` keeps that skip limited to those bases. `models.py` is unchanged.
Expand Down
16 changes: 16 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -159,6 +159,22 @@ resource = make_resource(
],
)
# resource.uuid is a freshly generated UUID4

# A key gives a stable identifier: the UUID version 5 of the key.
make_resource(key="https://example.org/policies/access-control").uuid
# '51beb3e9-30bb-535f-ba49-e68d4661aaa9'
```

An invalid input raises `OscalBuilderError`, a `ValueError` that is not an `OscalParseError`. Its `errors` attribute
holds the structured entries. An empty `key`, or a `key` with a `uuid`, is invalid.

```python
from oscal_bindings import OscalBuilderError, make_hash

try:
make_hash(digest, algorithm=" SHA-256")
except OscalBuilderError as e:
print(e.errors)
```

### Serialization
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-11-17
Loading
Loading