usnistgov
Imprecise description of profile backmatter resolution
Describe the bug
See https://pages.nist.gov/OSCAL/concepts/processing/profile-resolution/#d2e1377-head, which states
The output's backmatter MUST be generated by copying in each resource object from the backmatters of the imported catalogs/profiles in top-to-bottom order, then by copying in each resource object from the backmatter of the source profile itself. These objects MUST be processed in the order they are defined in each respective document.
Neither "top-to-bottom order" nor "the order they are defined in each respective document" have sufficient precision. Nor does this describe the order in which the "catalogs/profiles" should be processed (which should likely be the order in which they are cited in the "source profile", namely "document order"), nor the order in which the back-matter/resource elements of each "catalogs/profiles" should be processed (likely "document order"), nor the source profile's back-matter/resource element processing (likely "document order").
Who is the bug affecting
Profile resolution aficionados.
What is affected by this bug
Documentation
How do we replicate this issue
See https://pages.nist.gov/OSCAL/concepts/processing/profile-resolution/#d2e1377-head.
Expected behavior (i.e. solution)
The term "document order" should be used.
The order in which "catalogs/profiles" are processed should likely be the "document order" in which they are cited, followed ultimately by the "source profile".
I am uncertain if catalog or profile importation entails transitive catalog and profile importation and resolution, though that seems likely.
Other comments
A cat attempted to collaborate on this issue but was dissuaded.
Perhaps it is mentioned elsewhere: there is no explicit accommodation of XML comments or processing-instructions, nor of whitespace handling/normalization. For an XML profile resolution a simple accommodation would be to copy all descendant nodes of each the involved back-matter elements (in document order).
As Dave has rolled off the project, I will re-assign this to myself in the interim until I can update it.
- [x] Review the documentation and make the relevant change with team consultation on this page
- [ ] Review XSLT-M4 implementation for alignment with edits to the spec, ensure it is still accurate
- [ ] Review liboscal-java implementation for alignment with edits to the spec, ensure it is still accurate
Perhaps related: the subsequent (to "Backmatter Resolution") section "Metadata Resolution" first bullet asserts "The output catalog's metadata MUST have a unique top-level UUID (metadata:uuid)…". The metadata element does not possess a UUID. The "top-level UUID" might perhaps be the document root UUID, but that is not metadata.
The fourth bullet in "Metadata Resolution" asserts "The value of metadata:last-modified in the target MUST be set with a valid timestamp representing the time the profile resolution completed." [emphasis mine]. This requires extraordinary effort to achieve when using XSLT for profile resolution. Use of XPath current-dateTime() during a transformation will provide the time of transformation initiation: not transformation termination.
Edit: this observation has been filed as #1699 for separate treatment.
This requires extraordinary effort to achieve when using XSLT for profile resolution. Use of XPath
current-dateTime()during a transformation will provide the time of transformation initiation: not transformation termination.
Point well made but a little out of scope for this issue. Would you be comfortable filing a new issue for us in regards to that? Thanks.
I pushed up this local work to catch back up on it when I return, or for others. The changes are very small, but I updated my previous comment checklist in https://github.com/usnistgov/OSCAL/issues/1442#issuecomment-1450389887 resolve. to review both implementations. I am not 100% sure it is correct but seems likely, but do need to double check.
Perhaps related: the subsequent (to "Backmatter Resolution") section "Metadata Resolution" first bullet asserts "The output catalog's metadata MUST have a unique top-level UUID (metadata:uuid)…". The metadata element does not possess a UUID. The "top-level UUID" might perhaps be the document root UUID, but that is not metadata.
@aj-stein-nist - the new issue created by Gary (#1699) does not include the confusing description raised by @GaryGapinski above (thank you Gary! Good catch). Do you want another issue for the wording correction around UUID being document's root level UUID and not metadata's UUID or would you prefer this wording correction to be addressed as part of the of #1548?
Perhaps related: the subsequent (to "Backmatter Resolution") section "Metadata Resolution" first bullet asserts "The output catalog's metadata MUST have a unique top-level UUID (metadata:uuid)…". The metadata element does not possess a UUID. The "top-level UUID" might perhaps be the document root UUID, but that is not metadata.
@aj-stein-nist - the new issue created by Gary (#1699) does not include the confusing description raised by @GaryGapinski above (thank you Gary! Good catch). Do you want another issue for the wording correction around UUID being document's root level UUID and not metadata's UUID or would you prefer this wording correction to be addressed as part of the of #1548?
I will circle back on my PR today and update this issue with a follow-up comment when I have made up my mind on this. It seems simple enough, but wanted to keep the issues and their PRs more thematically organized moving forward.
This was not added to Sprint 65, it can be added to a follow-on sprint. The remainder of work todo is PR review and merging. Then we will close be able to close this in said subsequent sprint.
I will move forward this to next sprint, but think it is best to work on not updating this in develop, but the feature branch merged from a wonderful community member in https://github.com/usnistgov/OSCAL/pull/1596 and then prepare that for a release. Will have to discuss this during sprint planning.
This issue was discussed during sprint review. There was not sufficient time to meet, brain storm, and agree to the wording modification needed during this sprint. It will have to be moved forward to the next sprint. @JustKuzya will need to meet with @aj-stein-nist, @nikitawootten-nist, and @wendellpiez to move this forward.
After deep-dive with team we came to the conclusion that we don't have a better version of the profile resolution guidance wording at the moment. If @GaryGapinski and/or any other community member(s) have any ideas for better wording in the profile resolution description - we are open to the changes suggested.
The second conclusion of the discussion was: we do need more examples of the profile resolution with one and more base catalogs, that may have multiple unique as well as matching and/or similar back-matter items. For the purposes of generating examples we should have illustrative material presented in a brief concise form to not overburden the readers.
At 11/9/23 Triage Meeting: @JustKuzya suggested that this ticket along with #1314 will be superseded by a new issue in order to create examples and if needed clarify the profile resolution specification.
@JustKuzya and @Compton-NIST - is this issue closable? It is marked Done.
At the 11/30 Triage Meeting: this issue is closable. The remaining work will be captured in a separate issue by @JustKuzya.