Clarification of "matching-rationale" and "relationship"

[stephenbanghart0]

User Story

Discussion from TWG meeting on June 17th, 2025

Proposal 2:

“matching-rationale” and “relationship” should be combined into a single object to remove ambiguity.

The relationship (equal-to, subset-of, superset-of, etc.) between two frameworks has a different meaning depending on the “matching-rationale” context (syntactic, semantic, functional). This is explained in documentation and in NIST IR 8477 but is not currently reflected in the schema.

To prevent confusion, “matching-rationale” and “relationship” should be two mandatory fields of a new assembly “matching-relationship”, forcing the association between the two.

0..n matching-relationship
1 matching-rationale
1 relationship
1 priority

A priority field has been included to differentiate when multiple matching relationships are included.

Goals

"matching-rationale" and "relationship" should more closely align with their source of https://nvlpubs.nist.gov/nistpubs/ir/2024/NIST.IR.8477.pdf

Dependencies

No response

Acceptance Criteria

• All OSCAL website and readme documentation affected by the changes in this issue have been updated. Changes to the OSCAL website can be made in the docs/content directory of your branch.
• A Pull Request (PR) is submitted that fully addresses the goals of this User Story. This issue is referenced in the PR.
• The CI-CD build process runs without any reported errors on the PR. This can be confirmed by reviewing that all checks have passed in the PR.

(For reviewers: The wiki has guidance on code review and overall issue review for completeness.)

Revisions

No response

[xee5ch]

0..n matching-relationship 1 matching-rationale 1 relationship 1 priority

A priority field has been included to differentiate when multiple matching relationships are included.

Given more than one relationship, each with different priorities, how does one priority "win out" in resolution? Given NIST IR 8477 and other data formats and methodologies do not have it (e.g. OpenCRE), how can OSCAL benefit from it whether other approaches have unconsciously or consciously avoided it?