Same Field/Flag Names Used in Different Context

[brian-ruf]

User Story:

As an OSCAL user, I need to clearly understand how the same field/element name (or a flag/attribute name) may represent different information from one context to the next.

For example, the field name "title" is used in the "metadata" context to represent the title of the document (i.e. catalog, profile, or SSP title). The field name "title" is also used in the "role" context, to indicate the formal title for the indicated role (i.e. System Owner, ISSO, Authorizing Official).

There are multiple ways to handle these situations where a field/element name or attribute/flag name is appears in more than one.

Where this exists, three possible solutions are available:

1. Use a different field/flag name.
2. Ensure the metaschema field/flag definition includes documentation and examples that address every context.
3. Modify the OSCAL metaschema mechanism/structure to enable separate definitions for the duplicate field/flag name based on its context. (This is a more systemic solution that requires significant re-work of the existing metaschema mechanism/structure.)

Goals:

1. Eliminate confusion by minimizing field/flag name reuse in multiple contexts.
2. Ensure each re-use of a field/flag name is sufficiently addressed in documentation and examples.

Dependencies:

None.

Acceptance Criteria

Any place a field name is used in more than one context, its documentation and examples address every context in which it is used, such that an OSCAL user can clearly understand which aspect of the documentation/examples applies to any given context.

[wendellpiez]

There is a metaschema rule, enforced by its Schematron, that only one definition is permitted per assembly, field, or flag name. There can be many references to field title but only one definition for it. Consequently even when a field or assembly is reused, its model will be consistent across its appearances. (XSD does not require this: the same name does not guarantee the same model, so a section title may be different from a chapter title.) This policy considerably reduces the scope of the problem - rather than manage multiple models, we manage multiple potential uses for the same element in different contexts (for example, title inside role or control).

It does not eliminate it, however, and documentation of an element such as title needs to be consistent with its "variable use" to the extent that there is any.

Formal schema documentation will sometimes report for each element, which elements in the model can be its parent. We could do this. @brianrufgsa do you think this would help? For example (scroll down to "This element may be contained in":

https://www.niso-sts.org/TagLibrary/niso-sts-TL-1-0-html/element/p.html

[david-waltermire]

@brianrufgsa and @wendellpiez Is this still an issue to be addressed? If not, please comment and assign this back to me to close.

[wendellpiez]

The requirements described by this issue have been addressed by the improvements to Metaschema modularity and related improvements to the documentation pipeline (#339, #326). Autoproduced docs now report the permitted parentage of elements ("title is permitted inside group, control, subcontrol and part", etc.) which also helps. I am good with closing the Issue and making a new one for newly determined requirements.

[brian-ruf]

This issue is partially addressed. We still need to make a pass as the descriptions and examples. Every place the same field or flag name is re-used, there must either be a portion of the global description/example that address the use, or a local-ized override of the description and/or example.

I think we've made good progress on this, but I am not aware of a comprehensive pass to ensure this has been holistically addressed.

[brian-ruf]

Based on discussion between @wendellpiez and @brianrufgsa, consider something in the CI/CD pipeline that ensures if an element name or attribute name is used in more than one place, then the documentation is appropriate in all places.

[wendellpiez]

If not something in the CI/CD pipeline, certainly some sort of rule or policy addressing documentation of flags, fields and assemblies used in different contexts, such as when something is used in several places (such as title), Metaschema docs should explicitly call this out and address it.

Generated (web site) documentation for a Metaschema now lists, with every element on the XML side, which contexts it appears in. This can also be determined by querying a (composed) metaschema.

This effort should perhaps be folded into #478. Comments, @david-waltermire-nist and @brianrufgsa ?

[david-waltermire]

OSCAL has supported the use of the same field and flag names since adopting the Metaschema M4 toolchain.