Add actions assembly to encode an action (i.e. approval) and its role, party, and approval date.

[xee5ch]

Committer Notes

A follow-up to #1033, a recommended implementation for an actions assembly to allow developers using OSCAL to encode approval data for given staff certain roles for a responsible-party at a certain date and time.

This PR supercedes the obsolete PR #1038.

All Submissions:

• Have you followed the guidelines in our Contributing document?
• Have you checked to ensure there aren't other open Pull Requests for the same update/change?
• Have you squashed any non-relevant commits and commit messages? [instructions]
• Do all automated CI/CD checks pass?

Changes to Core Features:

• Have you added an explanation of what your changes do and why you'd like us to include them?
• Have you written new tests for your core changes, as applicable?
• Have you included examples of how to use your new feature(s)? (deferred to Examples of Actions in Metadata Assembly of Different OSCAL Model Instances oscal-content#130)
• Have you updated all OSCAL website and readme documentation affected by the changes you made? Changes to the OSCAL website can be made in the docs/content directory of your branch.

[wendellpiez]

Suggest:

• Add (required) type flag of type token. An example can show this with value "approval" (our primary use case).
• All other flags should be optional not required, should they not?

[xee5ch]

OK, feedback rolled in, and ready for final review. I hope to discuss tomorrow during model meeting if possible.

cc @david-waltermire-nist @wendellpiez

[david-waltermire]

I believe we should adjust the action type to be namespaced similar to properties. This will allow different organizations to define new action types without coordinating with OSCAL. OSCAL can define a core set of actions in the OSCAL namespace.

[xee5ch]

Per feedback from Dave, I need to improve the documentation for the new assembly, fields, and flags before finalizing and removing the draft tag.

[xee5ch]

After a second pass, it seems adding other documentation strings will be too wordy and add unnecessary content. I think this is ready for the NIST OSCAL Team to review. :-)

[xee5ch]

OK, I think this is ready. I addressed feedback above in fe39f58 but also added some missing formal-names and other things I should probably add. Let me know if you want further changes or that goes beyond the scope of what you think was/is prudent.

[xee5ch]

OK, I touched up with the feedback requests, @david-waltermire-nist and company. I am iffy on the constraints but and XPathy syntax target="system" versus target="./system" et cetera. If we are good with it as-is, I will merge the commits as needed once your formal review is complete. :-)

[wendellpiez]

In XPath and also Metapath, ./system is an abbreviated form of self::node()/child::system and returns the same nodes as system (expanded as child::system). So for purposes of addressing nodes they are functionally equivalent.

This doesn't mean that all XPath processors always treat them the same way, e.g. a delinter might even rewrite one to the other, etc.

[xee5ch]

In XPath and also Metapath, ./system is an abbreviated form of self::node()/child::system and returns the same nodes as system (expanded as child::system). So for purposes of addressing nodes they are functionally equivalent.

This doesn't mean that all XPath processors always treat them the same way, e.g. a delinter might even rewrite one to the other, etc.

Thanks for the clarifying explanation. Much appreciated! In terms of Metapath, I see targets in constraints that use either/or in some cases. I am not sure if there is a better answer, or it is simply right or wrong.

[xee5ch]

Also, in terms of acceptance criteria, we still ask for examples. It seems in #1263 NIST has begun removing examples from the Metaschema and I am not sure of: do we need examples for this PR? Do we need a follow-up issue for examples? Either way, where should new examples go? Let me know. Thank you!

[david-waltermire]

This looks good. Thanks!

[david-waltermire]

Also, in terms of acceptance criteria, we still ask for examples. It seems in #1263 NIST has begun removing examples from the Metaschema and I am not sure of: do we need examples for this PR? Do we need a follow-up issue for examples? Either way, where should new examples go? Let me know. Thank you!

It would be good to add an issue to create an example in the oscal-content repo maybe?

[aj-stein-nist]

@david-waltermire-nist, I pointed this PR to a feature branch as instructed during the weekly sync for when we are ready to merge after soliciting model feedback during an upcoming Model Review meeting next week.

[david-waltermire]

LGTM. Thanks!