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
4 changes: 3 additions & 1 deletion .agents/summary/components.md
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,8 @@ graph LR
- `assessment_period() -> (date|None, date|None)` — defined only for Assessment Plan (walks `tasks[].timing`, including nested subtasks: `on-date`, `within-date-range`; `at-frequency` contributes nothing) and Assessment Results (aggregates `results[].start`/`.end`). Earliest start / latest end win. Raises `OscalAccessError` on other types.
- Type unions `OscalBody` and `OscalWrapper` (each an 8-way union), and the module-private `_WRAPPER_TO_BODY_ATTR` dispatch map.
- `OscalAccessError` — raised when a typed accessor is used on the wrong document type.
- `OscalUnknownElementTypeError` — raised by `validate_element` for an unrecognized element type; a category of its own, outside the parse errors.
- `OscalDocumentTypeMismatchError` (in `parser.py`) — a subclass of `OscalParseError` that the typed parsers raise for a document of another type. `OscalParseError.limit` names the documented limit that stopped a parse, else `None`.

## 4. `v1/extensions/builders.py` — back-matter builders

Expand All @@ -88,7 +90,7 @@ graph LR
- `_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: Any, 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 `OscalUnknownElementTypeError` for an unrecognized type; 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
4 changes: 2 additions & 2 deletions .agents/summary/interfaces.md
Original file line number Diff line number Diff line change
Expand Up @@ -123,10 +123,10 @@ sequenceDiagram
| Invalid JSON / invalid UTF-8 bytes | `OscalParseError` (from `parse_oscal`) |
| Schema validation failure | `OscalParseError` with `.errors` = Pydantic error dicts |
| File missing | `FileNotFoundError` (from `parse_oscal_file`, includes path) |
| Typed parser, wrong document type | `OscalParseError("Document is not a …")` |
| Typed parser, wrong document type | `OscalDocumentTypeMismatchError("Document is not a …")` (subclass of `OscalParseError`) |
| `assessment_period()` on non-AP/AR | `OscalAccessError` |
| `OscalDoc(...)` with unrelated object | `TypeError` |
| `validate_element` unknown element type | `OscalParseError` |
| `validate_element` unrecognized element type | `OscalUnknownElementTypeError` (outside the parse errors) |
| Builders with invalid input | `pydantic.ValidationError` |
| `validate_oscal` on invalid input | returns `False` (never raises) |

Expand Down
2 changes: 1 addition & 1 deletion .agents/summary/review_notes.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ Cross-document facts were verified against the source files (`v1/parser.py`, `v1
| Top level is a pure re-export; `__all__` derived from `v1.__all__` | ✅ | codebase_info, architecture, components, interfaces, index agree; asserted by `tests/test_oscal_bindings.py` |
| Active schema release `1.2.3` / `__oscal_schema_version__` | ✅ | index, codebase_info, architecture, data_models, workflows, dependencies agree; tests assert it against the release of the pin and the artifact schema `$id` |
| Names come only from `names.json` (hoist + post-processor guards; no naming rule in the binding) | ✅ | architecture, workflows, interfaces, components, data_models, index agree |
| Exceptions `OscalParseError` (with `.errors`) / `OscalAccessError` | ✅ | Consistent; `validate_element` unknown-type also raises `OscalParseError` |
| Exceptions `OscalParseError` (with `.errors`) / `OscalAccessError` | ✅ | Consistent; `validate_element` raises `OscalUnknownElementTypeError` for an unrecognized type, a separate category |
| `serialize_oscal` defaults (`indent=2`, `by_alias`, `exclude_none`) | ✅ | Matches source |
| Two `RootModel`s: `OscalDocument`, `MappingCollectionMappings` | ✅ | architecture, components, data_models, workflows agree |
| Single runtime dependency (Pydantic v2) | ✅ | dependencies.md matches `pyproject.toml` |
Expand Down
4 changes: 2 additions & 2 deletions .agents/summary/workflows.md
Original file line number Diff line number Diff line change
Expand Up @@ -99,7 +99,7 @@ flowchart TD
E --> F{"typed parser?"}
F -->|"parse_catalog etc."| G["hasattr(doc.root, 'catalog')?"]
G -->|yes| H["return doc.root (CatalogDocument)"]
G -->|no| I["raise OscalParseError('Document is not a Catalog')"]
G -->|no| I["raise OscalDocumentTypeMismatchError('Document is not a Catalog')"]
F -->|no| E
```

Expand Down Expand Up @@ -157,7 +157,7 @@ sequenceDiagram
```mermaid
flowchart TD
A["validate_element(element, 'observation')"] --> B{"element_type in _ELEMENT_MAP?"}
B -->|no| C["raise OscalParseError('Unknown element type')"]
B -->|no| C["raise OscalUnknownElementTypeError('Unknown element type')"]
B -->|yes| D["model_class.model_validate(element)"]
D -->|ok| E["ElementValidationResult(valid=True)"]
D -->|PydanticValidationError| F["ElementValidationResult(valid=False,<br/>errors=[ValidationError(path, message)])"]
Expand Down
4 changes: 2 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -94,10 +94,10 @@ See `.agents/summary/workflows.md` for the flow diagram.
## Repo-Specific Patterns & Gotchas

- **Parsers accept `str | bytes`.** Passing `bytes` (from HTTP/S3/file) skips a UTF-8 decode; `parse_oscal_file` reads bytes deliberately. Invalid UTF-8 surfaces as `OscalParseError`, not `UnicodeDecodeError`.
- **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.
- **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)).
- **`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.
- **`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.
- **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
20 changes: 11 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -265,16 +265,16 @@ An entry for a [resource limit](#resource-limits) has `input` `None`.

### Resource limits

The parse operations apply six documented limits (PRS-010 of the spec store). An input past any of them is an `OscalParseError`, also when the document is otherwise valid, and `validate_oscal` returns `False` for it. The error carries one entry whose `type` names the limit, and no entry holds the input text.
The parse operations apply six documented limits (PRS-010 of the spec store). An input past any of them is an `OscalParseError`, also when the document is otherwise valid, and `validate_oscal` returns `False` for it. The error carries one entry whose `type` names the limit, and no entry holds the input text. The error also has the attribute `limit`, the identifier in the last column of the table. The two alias limits share an entry `type`, and `limit` tells them apart. For each other parse error, `limit` is `None`. Test an `OscalParseError` with `error.limit is not None`, and an error of any class with `getattr(error, "limit", None) is not None`.

| Limit | Value | Measure | Operations | Entry `type` |
|---|---|---|---|---|
| JSON depth | 200 levels | The number of arrays and objects that hold a value in the JSON text. Arrays and objects count the same. | `parse_oscal`, `parse_oscal_file`, the eight typed parsers, `OscalDoc.from_json`, `OscalDoc.from_file`, `validate_oscal` | `json_depth_limit` |
| JSON digits | 4,300 digits | The digits of the integer part of one JSON number, at any location. A sign, a fraction, and an exponent do not count. | The operations of the JSON depth limit, and `parse_oscal_yaml` and `parse_oscal_yaml_file` at each number location | `json_digit_limit` |
| Alias nodes | 100,000 nodes | The scalars, sequences, mappings, and mapping keys that aliases add to one YAML input | `parse_oscal_yaml`, `parse_oscal_yaml_file` | `yaml_alias_budget` |
| Alias characters | 1,000,000 characters | The characters of scalar text and key text that aliases add to one YAML input | `parse_oscal_yaml`, `parse_oscal_yaml_file` | `yaml_alias_budget` |
| YAML depth | 128 levels | The number of sequences and mappings that hold a node, after alias expansion | `parse_oscal_yaml`, `parse_oscal_yaml_file` | `yaml_depth_limit` |
| Line-break placeholders | about 137,000 private-use characters | The free private-use characters that a YAML input with U+0085, U+2028, or U+2029 leaves for them | `parse_oscal_yaml`, `parse_oscal_yaml_file` | `yaml_line_break_placeholder` |
| Limit | Value | Measure | Operations | Entry `type` | `limit` |
|---|---|---|---|---|---|
| JSON depth | 200 levels | The number of arrays and objects that hold a value in the JSON text. Arrays and objects count the same. | `parse_oscal`, `parse_oscal_file`, the eight typed parsers, `OscalDoc.from_json`, `OscalDoc.from_file`, `validate_oscal` | `json_depth_limit` | `json_depth` |
| JSON digits | 4,300 digits | The digits of the integer part of one JSON number, at any location. A sign, a fraction, and an exponent do not count. | The operations of the JSON depth limit, and `parse_oscal_yaml` and `parse_oscal_yaml_file` at each number location | `json_digit_limit` | `json_digits` |
| Alias nodes | 100,000 nodes | The scalars, sequences, mappings, and mapping keys that aliases add to one YAML input | `parse_oscal_yaml`, `parse_oscal_yaml_file` | `yaml_alias_budget` | `yaml_alias_nodes` |
| Alias characters | 1,000,000 characters | The characters of scalar text and key text that aliases add to one YAML input | `parse_oscal_yaml`, `parse_oscal_yaml_file` | `yaml_alias_budget` | `yaml_alias_characters` |
| YAML depth | 128 levels | The number of sequences and mappings that hold a node, after alias expansion | `parse_oscal_yaml`, `parse_oscal_yaml_file` | `yaml_depth_limit` | `yaml_depth` |
| Line-break placeholders | about 137,000 private-use characters | The free private-use characters that a YAML input with U+0085, U+2028, or U+2029 leaves for them | `parse_oscal_yaml`, `parse_oscal_yaml_file` | `yaml_line_break_placeholder` | `yaml_line_break_placeholders` |

pydantic-core's JSON parser sets the two JSON limits, and the binding cannot change them. The YAML depth limit is lower than the JSON depth limit, so deep YAML input always gets the YAML depth error. For a JSON limit, the entry's `line` and `column` give the position in the JSON text, and `column` counts UTF-8 bytes. For a YAML input, they give the position in the YAML source. No limit bounds the input size. See [Performance](#performance) for the memory that a parse uses.

Expand Down Expand Up @@ -302,6 +302,8 @@ Each OSCAL document type has a dedicated parser:
- `parse_plan_of_action_and_milestones(json)` → `PlanOfActionAndMilestonesDocument`
- `parse_mapping_collection(json)` → `MappingCollectionDocument`

A typed parser raises `OscalDocumentTypeMismatchError` for a document of another type. It is a subclass of `OscalParseError`, so `except OscalParseError` also catches it. `validate_element` raises `OscalUnknownElementTypeError` for an element type that the library does not recognize. That error is a category of its own, outside the parse errors. Test the category of an error with `isinstance`.

## Building

```bash
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-11-16
Loading
Loading