`@class` Under-Defined in OSCAL Specification

[brian-comply0]

Describe the bug

The use of @class is under-defined in the OSCAL syntax leading to inconsistent or ambiguous usage in actual content.

When analyzing the current uses cases of @class in NIST content examples, it appears this is serving a similar function to @ns, but with different syntax and a lack of consistency among values.

For example, when developing tools to handle the @name='label' property as used in NIST SP 800-53r5 catalog, there is nothing in the specification that helps me understand how to interpret class, or when to display which label.

Who is the bug affecting

Tool developers attempting to consistently process OSCAL content.

What is affected by this bug

Documentation

How do we replicate this issue

1. View content that uses @class, such as groups, controls, and label properties in NIST SP 800-53r5.
2. Read NIST OSCAL documentation regarding class.
3. Attempt to explain how a tool should process this content relative to the class attribute based only on the published documentation.

Expected behavior (i.e. solution)

Tool developers should clearly understand the use of the @class attribute and its use should be consistent with the content.

Other comments

Some of this is related to the authoring of 800-53 itself and may be better suited to an issue in the oscal-content repo; however, the ambiguous use of @class in that content highlights a lack of clear OSCAL guidance on the topic.

Revisions

No response

[brian-comply0]

I would argue that there is similarity between @ns and @class - at least in the way each is used for properties in current NIST content, and that @class should be dropped from the prop field. In concert with this, the OSCAL specification should enforce a cardinality of 0 or 1 for property labels in the default/OSCAL namespace. Then any other labels are assigned an @ns property and are defined by the namespace-owners assigning them. This would remove ambiguity for tool processing.

As for the use of @class on group and control, the use seems arbitrary. If there is a useful meaning behind adding @class='family' to SP 800-53 groups, its intent is unclear. Why does the 800-53 catalog need to add a class value of 800-53 to its controls? This only has value if merging in controls from multiple catalogs via profile resolution, except that the use of @class for this purpose is under-documented in profile resolution.

If the point is profile resolution, guidance and documentation is needed to clarify that class values should be assigned with this use case in mind, or a different mechanism for clarifying upstream catalog sources should be defined and documented. (In this case, the use of @class is still ambiguous if both r4 and r5 catalogs are inadvertently included in a more complex profile resolution scenario.

[iMichaela]

@brian-comply0 - NIST 800-53 catalog is most likely not reflecting OSCAL best catalog representation practices based on your descriptions above, but we need to also admit that 800-53 + 53A is far from being a simple data set or easy to represent. In addition, 800-53 evolved and NIST team did their best of capturing the original data. With CPRT as original data format, I hope we can do better when it will come to representing v6.0. Please note thoughl that an initial attempt of eliminating some of the prop@name="label" caused big commotions among our community members because tools are using them.

If there is a useful meaning behind adding @class='family' to SP 800-53 groups,

In 800-53 a group is called "family" , in CSF a group is a 'function' , in other catalogs, a group is 'chapter'

Why does the 800-53 catalog need to add a class value of 800-53 to its controls

I am assuming you are referring to the props with class="800-53a" - I can only speculate that @wendellpiez and other team members used the 'label's to represent the 800-53a data, and it's formatting - the use of () and [] brackets - which had significant importance in assigning the objectives and methods to the controls.

I am aware of other data sets (catalogs) that are using props with class in a consistent way. Until we move to a major release, we cannot make backwards incompatible changes, but some examples could be created. If you want to provide some, we are open to discuss and incorporate them.

Please let me know if you would like to meet and chat more around this topic. I am always open for improvements. I also agree that some guidance could be useful. But being very prescriptive will prevent others from being innovative with their data set representation.

[wendellpiez]

The flip side of @class being free to use is that ... when used freely especially across a data set aggregated from multiple sources, it becomes meaningless and noisy.

But I'm afraid that enforcing more rigor upstream isn't really possible or wanted until we can be more specific about what such rigor entails or how to enforce it. (And this applies not only to @class.)

The alternative isn't always pretty, but it works - analysis, surfacing regularities, expressing constraints, and data normalization as appropriate.

Like @iMichaela, I feel there is more to discuss here, but the discussion takes the form as so often of looking at specific examples and considering options and tradeoffs, before generalizing.

[brian-comply0]

Thank you @iMichaela and @wendellpiez for your responses.

It sounds like both of you are suggesting that the use of @class would normally be at the catalog author's discretion, which implies that the catalog author should then publish clarifications about the use of @class similar to the way a content owner needs to publish clarifications on the use of @ns outside the OSCAL default namespace.

The problem here is that the NIST OSCAL Team is trying to represent content owned by the NIST RMF Team, thus it becomes unclear as to what should be addressed as part of the OSCAL spec and what should be addressed by the NIST RMF Team. (The OSCAL team is acting as an agent of the RMF team when making decisions about the representation of 800-53 content in OSCAL.)

At a minimum, I recommend:

• The NIST OSCAL Team publish OSCAL guidance to clarify that @class is open to whatever use the content owner sees fit; however, the content owner must document that use if they expect tools to interoperate with their content. Undefined/under-defined use of @class is subject to being mishandled or ignored by tools.
• The NIST RMF (perhaps via the NIST OSCAL Team) must then publish clarifications on the use of @class within the 800-53 content, and attempt to be consistent with this usage in future iterations of 800-53 publications.

As a best practice recommendation, content owners should have a single mechanism for packaging up both human-readable and machine-readable guidance on:

• extensions (@ns)
• org/domain-specific allowed values
• org/domain-specific constraints
• org/domain-specific use of @class

[iMichaela]

@brian-comply0 - All your points are valid.

The problem here is that the NIST OSCAL Team is trying to represent content owned by the NIST RMF Team, thus it becomes unclear as to what should be addressed as part of the OSCAL spec and what should be addressed by the NIST RMF Team. (The OSCAL team is acting as an agent of the RMF team when making decisions about the representation of 800-53 content in OSCAL.)

I personally think that the two hats (OSCAL maintainers, OSCAL catalog(s) author) NIST is wearing need to be have a better delineation, especially that NIST intends to represent other frameworks in OSCAL (we have and will make available soon the CSF v2.0). Personally I think that some guidance is needed, and the point I was making is that we still have work to do on identifying what needs to be part of OSCAL guidance and what should be left open. props exist to provide native extensibility, but when they are not understood tools will ignore them too. Or if abused in a particular context, they are super useful, but that context is noise to others. Think of prop@name="label" - extremely important to 800-53 user because the catalog used them as a system supporting human readability, but really useless to other catalog owners.

So, yes, I agree with you, an OSCAL registry as I see it, (similar to FHIR) will have to allow documentation of more than the 'ns' and the elements including them. To get it right, we need input like yours from the community members, and contributions (ideas, proposed solutions).

[wendellpiez]

The problem as @brian-comply0 describes it is likely to grow worse, not better, over time. But it is not a problem that will ever be 'solved' either.

FWIW I always assume that content and hence its quality are always the responsibility of the data owners and publishers on their behalf -- I feel publishers of content may defer to 'standards' but even this doesn't let them off the hook if data is bad or broken, however nominally conformant. Similarly with documenting your usage ('dialect' or local form) of a standard language.

One application of a constraint layer is indeed to capture these 'emergent regularities'. If you have a rule that says that each control must have exactly one X and that X must follow rules X1 X2 X3, that all serves as documentation of X.

@brian-comply0 if you are interested in writing a set of Metaschema constraints that would validate regularities within any of the published docs or doc sets, let me know - this would be interesting to think about and is an obvious early application of standoff constraint definitions.