New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Requirement Tagging - Profile Resolution Specification #1089

Merged

david-waltermire merged 4 commits into usnistgov:release-1.0 from stephenbanghart:release-1.0

Feb 24, 2022

Contributor

stephenbanghart commented Jan 14, 2022

Committer Notes

This pull request includes the following changes to the Profile Resolution Specification:

Added requirement tagging to the XML source. added "req" to the .rnc schema
Added a draft status notice to the document and the landing page of the OSCAL website
Fixed errors in the Modify section (ref-id -> by-id, removed extraneous text)
Editorial fixes throughout document

david-waltermire linked an issue

that may be closed by this pull request

Profile Resolution Requirement Tagging #1086

Closed

aj-stein-nist suggested changes

View reviewed changes

Contributor

aj-stein-nist left a comment •

edited

Loading

OK, this turned out to be a few more fixes than I thought, but it should be easy for you to go through, separately or with me, Stephen, and approve or ignore those you do not agree with. You will not even need to make changes on your workstation.

Let me know what you think. Not sure I caught every one, and I will skim again tomorrow for a final pass.

src/specifications/profile-resolution/profile-resolution-specml.xml Outdated Show resolved Hide resolved

src/specifications/profile-resolution/profile-resolution-specml.xml Show resolved Hide resolved

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

src/specifications/profile-resolution/profile-resolution-specml.xml Outdated Show resolved Hide resolved

src/specifications/profile-resolution/profile-resolution-specml.xml Outdated

                     </p>
-                    <p>resource - distinctiveness is defined by the value of the
+                    <p><req level="must" id="req-id-uuid">For the object resource, distinctiveness MUST be determined by the value of the
                       <q>uuid</q>

Contributor

aj-stein-nist Jan 20, 2022

Consistent quoting

Suggested change

      
                    <q>uuid</q>
          
                    &quot;uuid&quot;

src/specifications/profile-resolution/profile-resolution-specml.xml Outdated

-                      <p>See
-                        <a href="https://pages.nist.gov/OSCAL/reference/latest/complete/xml-definitions/">the complete XML reference</a>for model requirements.
+                      <p><req level="must" id="req-output-xml">The final Catalog output, if using XML, MUST be valid as defined by the XML model documentation for the OSCAL Catalog. See
+                        <a href="https://pages.nist.gov/OSCAL/reference/latest/complete/xml-definitions/">the complete XML reference</a>for model requirements.</req>

Contributor

aj-stein-nist Jan 20, 2022

Spacing

Suggested change

      
                      <a href="https://pages.nist.gov/OSCAL/reference/latest/complete/xml-definitions/">the complete XML reference</a>for model requirements.</req>
          
                      <a href="https://pages.nist.gov/OSCAL/reference/latest/complete/xml-definitions/">the complete XML reference</a> for model requirements.</req>

src/specifications/profile-resolution/profile-resolution-specml.xml Outdated

-                      <p>See the
-                        <a href="https://pages.nist.gov/OSCAL/reference/latest/complete/json-reference/">complete JSON reference</a>for model requirements.
+                      <p><req level="must" id="req-output-json">The final Catalog output, if using JSON, MUST be valid as defined by the JSON model documentation for the OSCAL Catalog. See the
+                        <a href="https://pages.nist.gov/OSCAL/reference/latest/complete/json-reference/">complete JSON reference</a>for model requirements. </req>

Contributor

aj-stein-nist Jan 20, 2022

Spacing

Suggested change

      
                      <a href="https://pages.nist.gov/OSCAL/reference/latest/complete/json-reference/">complete JSON reference</a>for model requirements. </req>
          
                      <a href="https://pages.nist.gov/OSCAL/reference/latest/complete/json-reference/">complete JSON reference</a> for model requirements. </req>

src/specifications/profile-resolution/profile-resolution-specml.xml Outdated

-                      <p>See the
-                        <a href="https://pages.nist.gov/OSCAL/reference/latest/complete/json-reference/">complete JSON reference</a>for model requirements.
+                      <p><req level="must" id="req-output-json">The final Catalog output, if using JSON, MUST be valid as defined by the JSON model documentation for the OSCAL Catalog. See the
+                        <a href="https://pages.nist.gov/OSCAL/reference/latest/complete/json-reference/">complete JSON reference</a>for model requirements. </req>
                       </p>
                       <p>The JSON format, in general use, does not require the preservation of order of fields. As order matters in OSCAL, care should be taken to adhere to the canonical OSCAL order
                         <xref rid="order" />when outputting a catalog in JSON.

Contributor

aj-stein-nist Jan 20, 2022

Spacing

Suggested change

      
                      <xref rid="order" />when outputting a catalog in JSON.
          
                      <xref rid="order" /> when outputting a catalog in JSON.

src/specifications/profile-resolution/profile-resolution-specml.xml Outdated

                       </p>
                       <p>The JSON format, in general use, does not require the preservation of order of fields. As order matters in OSCAL, care should be taken to adhere to the canonical OSCAL order
                         <xref rid="order" />when outputting a catalog in JSON.
                       </p> <!-- TODO: Add Namespace (BaseURI) -->
                     </section>
                     <section id="yamlrequirements">
                       <head>Requirements and Guidance for YAML Output</head>
-                      <p>YAML is considered a simple variation on the JSON format. Beyond cosmetic differences there are no differences in the information structure between these formats. Therefore, the
+                      <p><req level="must" id="req-output-yaml">The final Catalog output, if using YAML, MUST be valid as defined by the JSON model documentation for the OSCAL Catalog. </req> YAML is considered a simple variation on the JSON format. Beyond cosmetic differences there are no differences in the information structure between these formats. Therefore, the
                         <a href="https://pages.nist.gov/OSCAL/reference/latest/complete/json-reference/">complete JSON reference</a>provides model requirements.

Contributor

aj-stein-nist Jan 20, 2022

Spacing

Suggested change

      
                      <a href="https://pages.nist.gov/OSCAL/reference/latest/complete/json-reference/">complete JSON reference</a>provides model requirements.
          
                      <a href="https://pages.nist.gov/OSCAL/reference/latest/complete/json-reference/">complete JSON reference</a> provides model requirements.

aj-stein-nist mentioned this pull request

Website Build Scripts Path Confusion and Filesystem Watching #1102

Closed

aj-stein-nist suggested changes

View reviewed changes

Contributor

aj-stein-nist left a comment

So I apologize in advance, I was reminded in our earlier meeting, Stephen, Dave pointed out to me I had missed one early on in my previous review, very close to the site of one of my first suggestions. I gave it another look over since I was reminded a little while ago.

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

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

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

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

src/specifications/profile-resolution/profile-resolution-specml.xml Outdated

-                      </li>
-                      <li>
-                        <p>If a
+                        <p><req level="must" id="req-backmatter-dupe">If a given
                           <src>resource</src>has the same

Contributor

aj-stein-nist Jan 24, 2022

Another miss

Suggested change

      
                        <src>resource</src>has the same
          
                        <src>resource</src> has the same

src/specifications/profile-resolution/profile-resolution-specml.xml Outdated

-                    <p>Tools MAY check for pruning conditions
-                      <xref rid="cleanup" />as resources are added as long as the final result is the same as if the pruning had taken place at the end of all resource addition.
+                    <p><req level="may" id="req-backmatter-prune">Tools MAY check for pruning conditions
+                      <xref rid="cleanup" />as resources are added as long as the final result is the same as if the pruning had taken place at the end of all resource addition.</req>

Contributor

aj-stein-nist Jan 24, 2022

I think this will also cause a spacing issue, not sure why I skipped it before.

Suggested change

      
                    <xref rid="cleanup" />as resources are added as long as the final result is the same as if the pruning had taken place at the end of all resource addition.</req>
          
                    <xref rid="cleanup" /> as resources are added as long as the final result is the same as if the pruning had taken place at the end of all resource addition.</req>

david-waltermire force-pushed the release-1.0 branch from e277f19 to 1697757 Compare

January 26, 2022 16:14

Contributor

wendellpiez commented Feb 10, 2022

Noting a few cosmetic / editorial issues that need correction at some point --

review inline tagging especially usage of <code>, <term> and <em>, <q> and literal ""text"" for consistency.
- is "directive" formal enough to index? I.e. how useful would be a tag for "directive" or are (or should be) directive names be tagged consistently as <term> for example?
in section 8.2.2 "Removing contents from controls" the singular form should be criterion not criteria (the plural)
- so, "meets all the criteria" is correct
- "The remove directive criteria class-ref MUST match" should be "The remove directive criterion class-ref MUST match"
- etc

thanks!

david-waltermire requested a review from aj-stein-nist

February 10, 2022 18:12

david-waltermire linked an issue

that may be closed by this pull request

Profile Spec - Intro rewrite/trim #1043

Closed

david-waltermire mentioned this pull request

Profile Spec - Intro rewrite/trim #1043

Closed

canb227 and others added 3 commits

February 10, 2022 15:14


          Tagged Requirements (updated .rnc), Added Draft Status, several small…

e597769

… fixes in modify section


          Applying AJ's fixes, other various small fixes - pending larger autom…

b440d69

…ated formating

Co-authored-by: Alexander Stein <alexander.stein@nist.gov>


          Readding CSS header

7e0ec36

stephenbanghart force-pushed the release-1.0 branch from c305e7f to 7e0ec36 Compare

February 10, 2022 20:15

aj-stein-nist approved these changes

View reviewed changes

Contributor

aj-stein-nist left a comment

Looks good! I am sure we can pick up other minor cosmetic things as we enhance it, you caught everything I found, nice work.

david-waltermire suggested changes

View reviewed changes

Contributor

david-waltermire left a comment •

edited

Loading

On line 24 of the specml, there is a stray ")" after depend.
The intro doesn't state why profile resolution is needed. The implementation layer works with catalogs of controls. Profile resolution allows for a profile to produce a resolved set of controls for use in the implementation and higher layers.
The text from Profile specification #1017 (comment) was removed, but not moved anywhere from what i can tell. Should this be added to a web page as indicated?

aj-stein-nist mentioned this pull request

Profile Resolution Specification for Back-Matter Resources Only with rlinks? #1140

Closed


          Intro purpose rewrite. Editorial fixes from comments. Small edits to …

d4a1124

…"Processing" page on site.

david-waltermire merged commit d2f5108 into usnistgov:release-1.0

david-waltermire mentioned this pull request

Profile Resolution Requirement Tagging #1086

Closed

david-waltermire pushed a commit that referenced this pull request


          Requirement Tagging - Profile Resolution Specification (#1089)

539fd73

* Tagged Requirements (updated .rnc), Added Draft Status, several small fixes in modify section
* Applying AJ's fixes, other various small fixes - pending larger automated formating
* Intro purpose rewrite. Editorial fixes from comments. Small edits to "Processing" page on site.

Co-authored-by: Alexander Stein <alexander.stein@nist.gov>
Co-authored-by: Stephen Banghart <stephen.banghart@outlook.com>

stephenbanghart added a commit to stephenbanghart/OSCAL that referenced this pull request


          Requirement Tagging - Profile Resolution Specification (usnistgov#1089)

636c1ff

* Tagged Requirements (updated .rnc), Added Draft Status, several small fixes in modify section
* Applying AJ's fixes, other various small fixes - pending larger automated formating
* Intro purpose rewrite. Editorial fixes from comments. Small edits to "Processing" page on site.

Co-authored-by: Alexander Stein <alexander.stein@nist.gov>
Co-authored-by: Stephen Banghart <stephen.banghart@outlook.com>

david-waltermire added this to the OSCAL 1.0.2 milestone

iMichaela pushed a commit to iMichaela/OSCAL that referenced this pull request


          Requirement Tagging - Profile Resolution Specification (usnistgov#1089)

* Tagged Requirements (updated .rnc), Added Draft Status, several small fixes in modify section
* Applying AJ's fixes, other various small fixes - pending larger automated formating
* Intro purpose rewrite. Editorial fixes from comments. Small edits to "Processing" page on site.

Co-authored-by: Alexander Stein <alexander.stein@nist.gov>
Co-authored-by: Stephen Banghart <stephen.banghart@outlook.com>

Rene2mt pushed a commit to Rene2mt/OSCAL that referenced this pull request


          Requirement Tagging - Profile Resolution Specification (usnistgov#1089)

8a253fa

* Tagged Requirements (updated .rnc), Added Draft Status, several small fixes in modify section
* Applying AJ's fixes, other various small fixes - pending larger automated formating
* Intro purpose rewrite. Editorial fixes from comments. Small edits to "Processing" page on site.

Co-authored-by: Alexander Stein <alexander.stein@nist.gov>
Co-authored-by: Stephen Banghart <stephen.banghart@outlook.com>

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet