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

[xee5ch]

Committer Notes

A follow-up to usnistgov/OSCAL#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 usnistgov/OSCAL#1038.

All Submissions:

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

Changes to Core Features:

• [x] Have you added an explanation of what your changes do and why you'd like us to include them?
• [x] Have you written new tests for your core changes, as applicable?
• [ ] Have you included examples of how to use your new feature(s)?
• [x] 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 https://github.com/usnistgov/OSCAL/commit/fe39f58a92b5a8160b2b68f5b05e701ff1ef7dbc 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]

And woops, last amend was because of a typo in universally in one doc string, but now we should be good.

[wendellpiez]

If this is linked to @ns would it be better to call it action/@name not action/@type?

[xee5ch]

If this is linked to @ns would it be better to call it action/@name not action/@type?

When we met to discuss the PR, Dave suggested that @ns was only appropriate with @name and maybe we should stick with @type. I guess he and others will weigh in here, but the only PR feedback was to touch up docs in the model and to move forward with a @system="URI" approach instead. See https://github.com/usnistgov/OSCAL/pull/1052/files#r943772853.

[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]

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.