Optional Typing of Parameter Content

[brian-ruf]

User Story:

As an OSCAL adopter, it would be helpful to have optional, additional parameter syntax that allows units and boundaries to be associated with constraints and values.

For example, a parameter may reflect an organizationally-defined policy review requirement. If the constraint or value is "at least annually", it should be possible to identify units a days, months or years, and a boundary of "maximum", "at least annually" can be expressed as:

• boundary: maximum
• units: months
• value: 12

Goals:

To better facilitate machine-readable content, by creating additional, optional syntax that allows better modeling of common parameter scenarios.

Dependencies:

None.

Acceptance Criteria

• metaschema files updated.
• 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.}

[brian-ruf]

It may be possible to accomplish this with prop/part elements, which are already allowed under constraint; however, they are not currently allowed under value.

[rgauss]

As discussed in the OSCAL model review meeting today, I think using as many standards as possible, potentially referenced in a value type, to express the actual value representation will then allow easier interpretation of those values using common tools/libraries, and easier representation of things like parameter-constraint test expressions.

In this example, ISO 8601 Durations could be specified as a value type such that tools can interpret a value of P11M to represent 11 months and test it with a parameter constraint test expression that checks that it is less than or equal to a maximum of P1Y (or P12M).

Using a widely adopted standard like ISO 8601 enables implementers to use common tools like Java's Duration or Moment.js Durations to parse, compare, and even display in localized, human-readable formats.

The same could be done for other value types of course, and hopefully in the future the maintainers of control catalogs could adopt those as the preferred or required data types for parameters.

[GaryGapinski]

W3C XML Schema Definition Language (XSD) 1.1 Part 2: Datatypes seems to be a good candidate for types (and extensions thereof).

[wendellpiez]

I would like to see a means by which we could use and support compound data types. For example, a frequency is a count (whole number or non-negative Integer) divided by a duration. There has got to be a manageable number of these types accounting for 80% of the instances. (The 20% will be interesting too.)

Then too, "every January" can be broken into two rules, one a frequency (1/annum) the other a date test (month()=January). So we also need a way to express how rules expressed in prose are to be refactored, not just rewritten.

A close examination of the parameters in use in SP800-53 could give us a sense at least of the range of opportunity. At present (OSCAL 1.0.0), parameters can offer a select to constrain a value selection, because those are clearly derivable from the data. But other constraints we need are not expressed except for in the catch-all (constraint), and not formalized in any case.

Maybe we need to conduct a data survey to see where the low-hanging fruit is.

Also, I think we need to be looking at the param and the set-parameter assemblies separately (albeit in combination). Currently they are modeled so that the parameter setting echoes its definition (I think everything can be rewritten or amended but label?), but they do not have to be.

[wendellpiez]

See also #206.

But note, what I said above is wrong. A frequency is not (only) a count divided by a duration. The length of the duration is significant. Three times / day is not the same as once every eight hours. In order to get these right, we probably have to delve all the way into how we expect to use these types to surface information (i.e. their operations).

[david-waltermire]

This work relates closely to #1059 and the constellation of issues around automating testing and evaluation. That work is targeted at OSCAL 1.2.0, so pushing this issue to the 1.2.0 release.