Review Control layer models

[david-waltermire]

User Story:

As an OSCAL content creator or tool developer, I need a clear understanding around the use of all model items in the OSCAL control layer models.

Control Layer

• oscal_control-common_metaschema.xml
• oscal_catalog_metaschema.xml
• oscal_profile_metaschema.xml

This issue is part of the epic #1066.

Goals:

For each model item:

• Ensure the documentation for the model item clearly identifies its purpose.
• Ensure the documentation identifies any additional considerations the user needs to consider to use the model item.
• Ensure all related constraints appropriately define the cardinalities, co-dependencies, and allowed values within the OSCAL namespace.
• Ensure identifier use is clearly defined and the scope of the identifier is clearly indicated
• Ensure identifier references are clearly defined and the scope of reference is clearly indicated

Dependencies:

None.

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.

[wendellpiez]

My notes are here: https://hackmd.io/D4W1e9bnSpq797myjrJVyQ

[david-waltermire]

@wendellpiez Can you create a PR based on your changes? This should be against my branch related to PR #1263.

[aj-stein-nist]

Potential follow-up food for thought about model-review:

• We need to consider an automatable or reliable developer-driven process to given every constraint with a unique ID so that error messaging in an aware app could report which constraint is the origin of the error Deferred to Constraint Has Its Own Unique Name or ID metaschema#232 and Add Constraint IDs/Names for All Constraints in Model #1430
• We need to go back and review adding indices for all the different document models, covering the key objects of that model and the cross-document references you need for that model (examples: SSP needs an index of every control in that SSP model; the SAP would have indices from imported assembly it gets from an instance of a different model) Deferred to Review Top-Level Model Indices and Supporting Constraints #1431

Update: discussed delay with Dave in weekly model review check-in meeting and decided to defer the updated work to separate issues to be prioritized outside of the current review issue and upcoming PR merge. Thanks to @wendellpiez for reminding me.

[wendellpiez]

Have some ideas about IDs. They must be "sticky" (not change on the thing that has the ID) so once assigned they should not change. We could either:

1 develop some arbitrary/random id assignment and then agree never to change
2 have a simple structured rule such as simple name assigned by first developer

I like option two as 2 lightweight. Especially if the rule for how to make the named ID is clear and robust.

Second item above is also important, and automatablish (happy to help).