Clarify Back Matter Resource Resolution Order in Profile Resolution #1700
Conversation
Some order of operations for processing being described in back matter resource resolution and other key operations of the specification are described as 'top-down order' and similar phrases that are approachable but less precise than 'document order' for underlying markup and data languages we use, like XML, where 'document order' has a more precise meaning.
There was a problem hiding this comment.
So, we actually avoided the term "document order" as a specifically XML concept -- indeed this term does not appear in the XML Recommendation, and is defined formally (tmk) only in the context of XPath/XDM. Since it had no meaning for JSON, we avoided it in favor of spelling it out, i.e. top-down, depth first ordering.
Given this, should we not at least define the term if we are going to use it? Alternatively we could add a note saying "in XML, document order".
https://www.w3.org/TR/1999/REC-xpath-19991116/#data-model
https://www.w3.org/TR/query-datamodel/#document-order
I'm approving because I don't want to block this as an improvement if you consider it to be one.
If "document order" is considered too formal, perhaps "the order of occurrence within the document" (deficiently) covers XML and JSON (presuming it entails depth first, which seems to be the case). The term linear also comes to mind. |
|
Happy to see clearer language crafted. Also not opposed to saying 'document order' if it can be clarified appropriately or perhaps glossed to make sense in an object processing (i.e. JSON or YAML) context. Note that because order of properties on objects in JSON is not defined, a data caster going from objects back into XML must look at the metaschema to know that parameters come before properties (props), for example (or know ahead of time). |
Address feedback from @GaryGapinski and @iMichaela in issue comment that is linked below. #1442 (comment)
aj-stein-nist
force-pushed
the
1442-imprecise-description-of-profile-backmatter-resolution
branch
from
285b339 to
3b54234
Compare
|
I made some light changes and also addressed #1442 (comment). @wendellpiez, can I get a quick re-review? |
src/specifications/profile-resolution/profile-resolution-specml.xml
Outdated
Show resolved
Hide resolved
src/specifications/profile-resolution/profile-resolution-specml.xml
Outdated
Show resolved
Hide resolved
|
This was not completed in time for the remainder for Sprint 64 and higher priorities came up with Sprint 65. I will add the related issue to sprint 66 and reopen the PR or start over accordingly as time permits. |
Committer Notes
Closes #1442.
Some order of operations for processing being described in back matter resource resolution and other key operations of the specification are described as 'top-down order' and similar phrases that are approachable but less precise than 'document order' for underlying markup and data languages we use, like XML, where 'document order' has a more precise meaning.
All Submissions:
"?
By submitting a pull request, you are agreeing to provide this contribution under the CC0 1.0 Universal public domain dedication.
Changes to Core Features:
Have you written new tests for your core changes, as applicable?(intended for separate dev work tracked in another task, link later)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.