Best Practices for Props, Links, and UUID Version Management

[aj-stein-nist]

User Story:

As an OSCAL tool developer, in order to best implement component definitions and document instances of other models, I would like to know best practices on how to properly use link's and prop's within assemblies by properly referencing a component's UUID to convey when the component has significantly changed or stayed the same (with some reasonable semantic assumptions).

Goals:

Documenting best practices for developers implementing software that consumes or produces OSCAL document instances, specifically components, and knowing how to interpret a component's UUID staying the same and differing. Additionally, best practices guidance on how to pin such an assembly with a link/@hrefs in a coherent and useful way.

(This was discussed on the OSCAL Lunch with the Devs on December 30, 2021. @david-waltermire-nist suggested we can better document best practices around what are identifying data of an assembly with a UUID, like component, and the supporting data of that assembly, and how that dictates if it "the same" or not, and additionally I discussed potential linking constructs to support that.)

Dependencies:

N/A

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.

{The items above are general acceptance criteria for all User Stories. Please describe anything else that must be completed for this issue to be considered resolved.}

[david-waltermire]

#1023 requests the addition of an imported-from link rel, which can address the need here.

[david-waltermire]

This could take advantage of prop/link grouping (#1064) to express a link/prop pair to point the component definition (using imported-from) and identify the specific component by UUID using a prop with a TBD name.

[david-waltermire]

Addressing this issue requires features from OSCAL 1.1.0. Moving this issue to that milestone.