Issue #860 identifier scoping documentation

[Rene2mt]

Committer Notes

Issue 860 updating OSCAL model descriptions where needed to clarify the scope and uniqueness of identifiers used within the OSCAL models.

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)?
• 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.

[brian-ruf]

I reviewed this at the request of @iMichaela, but paused my review based on a fundamental observation. I believe many of these descriptions do not fully describe the scope.

For example, while it's true that each document-level UUID is ONLY document scoped, many other identifiers are both document scoped and intended to be visible by downstream documents as a result of import statements.

I suggest this be re-worked. Consider borrowing from programming parlance describing variable scope, such as "local" describing an identifier that is only intended to be used within the document itself and "global" describing an identifier that is intended to be used both within the document itself as well as by any document importing that document.
There are only certain allowed import paths, so "global" would be constrained by import possibilities.

NOTE: After five months I am a little rusty, but if there are any identifiers that are exposed to some documents through import statements, while they are not exposed to other documents despite being imported, we may need a more granular expression of scope beyond just "local" and "global".

Ideally, I believe scope should reflect these concepts (as examples, not necessarily in this format):

Defining Model	Identifier	Catalog	Profile	Component	SSP	AP	AR	POA&M
Catalog	uuid	X
Catalog	control-id	X	X	X	X	X	X	X
SSP	Component uuid			X	X	X	X	X
AP	Subject uuid				X	X
AR	Subject uuid					X

Known import paths, which would constrain "global" include:

• Catalog -> Profile -> Component Definition
• Catalog -> Profile -> SSP -> POA&M
• Catalog -> Profile -> SSP -> AP -> AR

Finally, while I haven't been in the working sessions in the past several months and don't know if there was discussion/consensus on terminology, I am not certain "document" is the best term to use to talk about scope. Consider using "model".

[Rene2mt]

Thanks for the inputs. Please review the latest two commits to see the latest WIP ( 81dfc3c and 108b86e ). These commits just have changes for identifier descriptions in just two of the metaschemas but additional changes will be made and committed once we confirm we are on the right track:

• oscal_metadata_metaschema.xml
• oscal_catalog_metaschema.xml

As I reviewed the identifier descriptions in these metaschemas, I focused on clarifying

1. Uniqueness of the Identifier - I added "global" or "local" to describe the "uniqueness" of identifiers. By default, identifiers of type uuid are globally unique, but it thinks its still good to call out explicitly. Other identifiers (e.g. of type token) are often unclear, so I focused on these to make sure it was clearly stated.
2. Scope (of use) - I added some verbiage to indicate if the identifier was "cross-instance" scoped or just "instance" scoped.
3. Consistency - I made sure the descriptions specified what should happen to the identifier when revisions are made (e.g., should remain consistent across revisions or should change with each revision).

``

[david-waltermire]

How about something like this:

<!-- identifier declarations -->
<description>A <em>machine-oriented</em>, <em>globally unique</em> identifier with a <em>cross-instance</em> scope that can be used to reference this defined resource elsewhere in this or another OSCAL instance. This UUID should be assigned <em>per-subject</em>, which means it should be consistently used to identify the same subject across revisions of the document.</description>
<remarks>
    <!-- UUID -->
    <p>Type: machine-oriented</p>
    <p>Uniqueness: globally-unique</p>
    <p>Scope: cross-instance - Provides an identifier that can be used to refer to this concept in OSCAL APs, ARs, and POAMs.</p>
    <p>Consistency: per-subject</p>
    <p>Additional Information:</p>
</remarks>

and for references:

<!-- identifier references -->
<description>Something similar to the above that incorporates key words</description>
<remarks>
    <!-- UUID -->
    <p>Type: machine-oriented</p>
    <p>Source: cross-instance - References an identifier from the SSP referenced in the assessment plan's <code>import-ssp</code> directive.</p>
    <p>Additional Information:</p>
</remarks>

[david-waltermire]

This is a link to the XML index. The JSON index should be referenced as well.

[Rene2mt]

added JSON index. Will be in next commit.

[bradh]

I'm not sure that this is true. Because OSCAL is extensible, I could have my own UUIDs. Perhaps something like

Suggested change

	The [OSCAL Reference Index](/reference/latest/complete/xml-index/#/@uuid) provides a complete listing of UUIDs in OSCAL. References to these identifiers typically follow a naming convention of the object type followed by “-uuid”. For example, see the reference index for [location-uuid](/reference/latest/complete/xml-index/#/location-uuid).
	The [OSCAL Reference Index](/reference/latest/complete/xml-index/#/@uuid) provides a listing of UUIDs in the core OSCAL model. References to these identifiers typically follow a naming convention of the object type followed by “-uuid”. For example, see the reference index for [location-uuid](/reference/latest/complete/xml-index/#/location-uuid).

[Rene2mt]

valid point. Updating locally and will include with my next commit

[aj-stein-nist]

This will get crowded with brad's recommendation. It seems we single space between sentences and there is an additional space at "followed by “-uuid”. For example," between the period and for. I noticed this when re-reading locally.

[aj-stein-nist]

Some initial feedback, more to come. I see Dave is adding a lot too, so I wanted to get this in the mix. Will give it more reviews a few times over before I say I am done done. :-)

[aj-stein-nist]

identifiers are guaranteed to be unique across all other identifier

Does this mean over all time? Maybe be overly obvious and say that?

[bradh]

They aren't really unique. They're unlikely to be duplicated accidently with reasonable assumptions of time and usage, but nothing stops me using something you've already used (either because I didn't know better - maybe I copied an example and didn't realise what it all meant; or maliciously).

[aj-stein-nist]

I agree per you review of my review. I meant more in the aspirational view that they should not be reused intentionally by developers unless in clear case; UUIDs are presumed to not be reusable. In a previous part of my review, I thought somewhere here, I added a link to the explanation of how UUIDs should be used for this reason.

I guess your point stands, maybe it is better not to muddy the waters! I'll resolve this one for now.

[Rene2mt]

we'll create a follow on issue for this item

[aj-stein-nist]

Non-blocking: Additional feedback: I am not sure we clarify on the data type page even why they are different and why that matters. I will open up a separate issue, but we might want to remove that part.

[aj-stein-nist]

OK, I moved the larger discussion into #1105.

As for the content here, my recommendation below: OSCAL generally provides the token data to enable human-oriented identifiers. These human-oriented identifiers ..."

[bradh]

I'm not sure that this is true. Because OSCAL is extensible, I could have my own UUIDs. Perhaps something like

Suggested change

	The [OSCAL Reference Index](/reference/latest/complete/xml-index/#/@uuid) provides a complete listing of UUIDs in OSCAL. References to these identifiers typically follow a naming convention of the object type followed by “-uuid”. For example, see the reference index for [location-uuid](/reference/latest/complete/xml-index/#/location-uuid).
	The [OSCAL Reference Index](/reference/latest/complete/xml-index/#/@uuid) provides a listing of UUIDs in the core OSCAL model. References to these identifiers typically follow a naming convention of the object type followed by “-uuid”. For example, see the reference index for [location-uuid](/reference/latest/complete/xml-index/#/location-uuid).

[bradh]

They aren't really unique. They're unlikely to be duplicated accidently with reasonable assumptions of time and usage, but nothing stops me using something you've already used (either because I didn't know better - maybe I copied an example and didn't realise what it all meant; or maliciously).

[bradh]

Links to the import types might be useful.

[Rene2mt]

I reworked the scope section quite a bit locally, adding an svg diagram illustrating the relationship between OSCAL instances. Links to import types would be useful...I'll go ahead and add them as well.

[aj-stein-nist]

Some more feedback, hope this helps. I am free to talk today if you want to work on it together.

[aj-stein-nist]

In some places we say it is a "token" data type and other places we capitalize and say a "Token" data type. We should be consistent, I am not sure what the team has agreed upon.

[aj-stein-nist]

Dave said we should keep them lower case. This still might need to be fixed, @Rene2mt.

[aj-stein-nist]

This will get crowded with brad's recommendation. It seems we single space between sentences and there is an additional space at "followed by “-uuid”. For example," between the period and for. I noticed this when re-reading locally.