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 usnistgov/OSCAL#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 https://github.com/usnistgov/metaschema/issues/232 and https://github.com/usnistgov/OSCAL/issues/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 https://github.com/usnistgov/OSCAL/issues/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).