Incorrect Allowed @name values for @prop in documentation

[brian-comply0]

Describe the bug

There are many places in the OSCAL documentation lists incorrect values for the @name attribute on the prop field.

For example, prop[@name='marking'] is only supposed to be valid in the //metadata of each model; however, it is also incorrectly listed in the documentation as valid in many other places.

A search of the Catalog documentation shows eight additional occurrences of prop[@name='marking'] in places such as:

• //metadata/revisions/prop
• //metadata/role/prop
• //metadata/location/prop
• //metadata/party/prop
• //metadata/responsible-party/prop
• //param/prop (root, group, and control levels)
• //control/prop (root, group, and control levels)
• //part/prop (group and control levels)
• //group/prop
• //back-matter/resource/prop

Who is the bug affecting

Developers trying to properly implement OSCAL properties.

What is affected by this bug

Documentation

How do we replicate this issue

1. Visit the documentation page for any model.
2. Search the page for "marking" (three occurrences of marking per entry)
3. Observe prop[@name='marking'] as valid in places other than //metadata/prop

Expected behavior (i.e. solution)

Documentation for prop in each context should include only the actual accepted values for @name.

Other comments

This issue has existed since the pre 1.0.0 release candidates. To my knowledge no issue was created for it. I could not find one among the open issues.

Revisions

No response

[aj-stein-nist]

I am not 100% certain this belongs in OSCAL-Reference. If this does require a fix in usnistgov/metaschema-xslt, I will 1) request the assigned developer open a cross-referencing issue in that repo and 2) work with me or the delegated developer to coordinate a potential fix to that repo.

[aj-stein-nist]

@JustKuzya, I heard you were looking into picking this one up. If you are able and willing, please do!

[JustKuzya]

While looking and trying to understand this one, I found non-working data-type #-anchored references from both Outline and Reference Pages - should I fix that one first? It does looks ugly and very broken, while this one seems more obscure.

Though it seems that there is no issue created for it yet.

[aj-stein-nist]

While looking and trying to understand this one, I found non-working data-type #-anchored references from both Outline and Reference Pages - should I fix that one first? It does looks ugly and very broken, while this one seems more obscure.

Though it seems that there is no issue created for it yet.

@aj-stein-nist volunteered to open an issue for this as reported by Dmitry.

[aj-stein-nist]

@JustKuzya and @wendellpiez and @aj-stein-nist have volunteered to sync on this and complete a root cause analysis, confirm whether this is a minor document generation issue or something more significant, and act accordingly.

[aj-stein-nist]

I set aside some time with @JustKuzya and @wendellpiez tomorrow as today as pretty packed for me.

[aj-stein-nist]

We need to enumerate all constraints with allowed-values for props of a given name. There is some homework for Dmitry and I to do here and I will want to consult @david-waltermire-nist and the Metaschema core team before moving forward on adapting the documentation further. Moving this to blocked in the interim.

[wendellpiez]

A path to find all these is unfortunately not straightforward since the @target uses XPath syntax, and XPath can't (yet) parse XPath ... but a couple of greedier queries could work. //allowed-values[not(@allow-other='yes')] could be a start.

Keep in mind that allowed-values targeting prop could either indicate prop in their @target, or it could be implicit (by virtue of targeting "." in the definition of a prop).

Also, this Issue implicates not only allowed values on props, but also others....

[aj-stein-nist]

I just wanted to give a status update: we are working on usnistgov/metaschema#411 but it will not get completely reviewed and possibly merged by the end of this sprint, but work continues.

[aj-stein-nist]

There will be updates to the aforementioned issue but as of a sync with Metaschema developers I am working with on the associated PR for issue 411, more work is needed to be done on the spec and updating documentation will have to wait on certain discuss of allowed values processing that ought to come after the next two weeks of sprint, so I will be moving this out of Sprint 75 for now.

[david-waltermire]

This is not a bug in the allowed values. It is a bug in marking not showing up properly in the documentation. See usnistgov/OSCAL#1972