Skip to content

refactor(exporters): type field mappings by their structure - #57

Merged
aaronlippold merged 2 commits into
nextfrom
refactor/style-config-field-mappings
Nov 18, 2026
Merged

aaronlippold merged 2 commits into
nextfrom
refactor/style-config-field-mappings

Conversation

@aaronlippold

Copy link
Copy Markdown
Member

A field mapping's keys depend on its structure, and until now a key that didn't belong to the structure was ignored. This PR makes field_mappings a pydantic discriminated union on structure (left out means simple), built with pydantic's Discriminator and Tag.

What each structure takes

The keys are the ones the engine reads for that structure, measured from mapping_engine.py; any other key is refused.

  • simple: source_field, transform, source_logic (only cci_lookup_with_deduplication), cci_lookup (source_field, cis_controls_version, extract, fallback_cci, mapping_file), multiple, and any attributes.
  • composite: sources (required; each with field, label, transform), separator, and any attributes.
  • nested: exactly one child in children (source_field, element, transform). The engine builds only the first child, so a second is refused rather than dropped. attributes.system only.
  • dublin_core: source_field (required), source_logic (only nist_after_cci_deduplication), dc_elements, and attributes.href. Its dc_elements prefixes must be bound in benchmark.namespaces, as the benchmark reference's are.
  • Every structure also takes target_element.
  • embedded_xml_tags, ident_from_list and metadata_from_config are accepted as JSON-like data until they get their own types.
  • An unknown structure is refused with the list of known ones. null still switches off a mapping a style inherits.

Template and TransformName are the shared types for every template and transform value of the four typed structures. Dublin Core element text is a Template too.

Keys removed from the styles

None of these keys was ever read, so exports are unchanged:

  • Field-mapping description text is now YAML comments.
  • optional (cis.yaml warning): a mapping with no value is already left out.
  • content: "" (disa.yaml fix): fix is written empty because it has attributes and no source. The fix text itself comes from the fixtext mapping, unchanged.
  • multiple on dublin_core: one reference is written per NIST control regardless.
  • cci_lookup.enabled and deduplicate_nist: the lookup runs because of source_logic, and deduplication is switched by cci_deduplication.enabled.

Each is refused with a hint saying what happens instead. The CCIs and fix text in the exports are unchanged.

Docs

yaml-config-reference.md and mapping-engine-guide.md describe the structures. The "Static Content Field" section, which described a content key nothing read, is corrected. The CCI and optional examples, and examples of keys that never existed (condition, default), are fixed.

Verification

  • pytest tests/: 2740 passed. pytest tests/scripts: 53 passed. mypy, ruff check, ruff format --check and mkdocs build --strict are clean.
  • 28 XCCDF exports (9 cached benchmarks and 5 synthetic fixtures, DISA and CIS styles) are byte-identical to the exports before this branch, and cis-bench validate passes on all 28.

field_mappings is a discriminated union on structure (left out = simple),
built with pydantic's Discriminator and Tag. simple, composite, nested
and dublin_core each declare the keys the engine reads for that structure
and refuse any other; embedded_xml_tags, ident_from_list and
metadata_from_config are accepted as JSON-like data until typed. An
unknown structure is refused with the known ones; null still switches off
an inherited mapping. Template and TransformName are the shared types of
every template and transform value; a dublin_core mapping's dc_elements
prefixes must be bound, as the benchmark reference's are.

Keys nothing read are gone from the styles: field-mapping descriptions
are YAML comments; optional, content (the empty fix comes from its
attributes; the fix text is fixtext's), multiple on dublin_core, and
cci_lookup.enabled and deduplicate_nist are refused with what happens
instead. A nested mapping takes exactly one child, which the engine
builds; source_logic takes only the value its structure acts on.
Exports are unchanged.

Signed-off-by: Aaron Lippold <lippold@gmail.com>
A Dublin Core element's content is filled with {variables} when it is
written, so it is a Template like every other template value of the
typed field mappings (and of the benchmark reference, which shares the
model); content written with no value is refused with the shared "has
no value" message. The style_config module docstring describes the typed
field-mapping structures.

Signed-off-by: Aaron Lippold <lippold@gmail.com>
@aaronlippold
aaronlippold merged commit 9e0c719 into next Nov 18, 2026
7 checks passed
@aaronlippold
aaronlippold deleted the refactor/style-config-field-mappings branch November 18, 2026 23:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant