Proposed metaschema docs updates by wendellpiez · Pull Request #50 · david-waltermire/OSCAL

wendellpiez · 2022-07-29T22:07:16Z

Committer Notes

Addresses usnistgov#1392.

Connects from there back to usnistgov#1263.

All Submissions:

Have you selected the correct base branch per Contributing guidance?
Have you set "Allow edits and access to secrets by maintainers
"?
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.

src/metaschema/oscal_control-common_metaschema.xml

src/metaschema/oscal_profile_metaschema.xml

david-waltermire · 2022-08-12T16:38:28Z

src/metaschema/oscal_profile_metaschema.xml

+                              <p>Whenever combining controls from multiple (import) pathways, an issue arises of what to do in cases of clashing invocations (which may be multiple competing versions of a control). </p>
+                              <p>This setting permits a profile designer to apply a rule for the resolution of such cases. In a well-designed profile such collisions would ordinarily be avoided, but this setting can be useful for defining what to do when it occurs.</p>
+                              <p>If no <code>combine</code> element appears, the default behavior is to treat the profile the same as one whose <code>combine</code> indicates a method of “keep”. In this case, controls are all kept (and not regarded as duplicative), leading to validation errors in the result if their IDs should happen to collide. This is easily detectable as an error condition.</p>
+                              <p>Conversely, a profile with <code>combine="keep"</code> that shows no such control collisions in profile resolution, demonstrates thereby that no conflicting controls have been selected, even among sources that may be very similar in other respects (for example, as distinct profiles both derived from the same catalog).</p>
+                              <p>Another setting for <code>combine</code>, "use-first", can be useful in specific situations. (The deprecated value "merge" represents a proposed use case not fully specified.)</p>


We need to move these changes to a different branch that is based on develop, since this is based on main.

src/metaschema/oscal_profile_metaschema.xml

Adjustments based on model review feedback on 8/12.

src/metaschema/oscal_profile_metaschema.xml

Removed outdated merge phase remarks. Created issue #53 to address this.

david-waltermire

Thanks!

* Feedback based on usnistgov#1392 * Adjustments based on model review feedback on 8/12. * Removed outdated merge phase remarks. Created issue #53 to address this. Co-authored-by: David Waltermire <david.waltermire@nist.gov>

@Rene2mt

…1263) * completed partial update of the Metadata object documentation. * adjustments to roles * adjusted the cardinality of location/address to make address optional. * Improved documentation and constraints related to location and parties * addressed the remainder of metadata and control feedback from @Rene2mt. * Improved the introductory remarks for a profile to better describe what a profile is and what it does. * Fixed a broken constraint that was not targeting the right node. * started refining descriptions and adding properties to describe identifier attributes. * Addressed feedback from AJ during 20220718-20220722. (#48) * Week 30 feedback on SSP model. (#49) * Proposed metaschema docs updates (#50) * Addressed feedback based on usnistgov#1392 * Adjustments based on model review feedback on 8/12. * Removed outdated merge phase remarks. Created issue #53 to address this. * Addressed A.J. Stein's Week 32 Feedback for Model Review (#52) * Addressed AJ Stein's week 32 feedback for usnistgov#1331. * Addressed DRAFT: Update catalog & profile metaschema documentation (#51) * Update catalog & profile metaschema documentation * Add props to control identifier * Fixed broken syntax and addressed consistency in wording within the Profile 'merge' construct. * Adjustments to alter, moving to to an inline definition * cleaned up empty remark. * Removed redundant constraints * removed some redundant constraints * Preliminary work on URI documentation to address usnistgov#1249. * More work on document URI use in OSCAL * Updating data types related to usnistgov/metaschema#224. * Improved consistency of how URI concepts are discussed. * Added note about party locations * Updated Metaschema instances of `uri` and `uri-reference` data types to indicate their URI semantics. Resolves usnistgov#1249. * Added identifier props to control layer metaschemas (#55) * Responding to usnistgov#1066: metaschema edits; CSS enhancement (#56) * Whitespace cleanup in metadata metaschema * Apply suggestions from code review Co-authored-by: Alexander Stein <alexander.stein@nist.gov> Co-authored-by: Wendell Piez <wapiez@wendellpiez.com> Co-authored-by: Rene Tshiteya <rene-claude.tshiteya@gsa.gov>

@Rene2mt

…1263) * completed partial update of the Metadata object documentation. * adjustments to roles * adjusted the cardinality of location/address to make address optional. * Improved documentation and constraints related to location and parties * addressed the remainder of metadata and control feedback from @Rene2mt. * Improved the introductory remarks for a profile to better describe what a profile is and what it does. * Fixed a broken constraint that was not targeting the right node. * started refining descriptions and adding properties to describe identifier attributes. * Addressed feedback from AJ during 20220718-20220722. (#48) * Week 30 feedback on SSP model. (#49) * Proposed metaschema docs updates (#50) * Addressed feedback based on usnistgov#1392 * Adjustments based on model review feedback on 8/12. * Removed outdated merge phase remarks. Created issue #53 to address this. * Addressed A.J. Stein's Week 32 Feedback for Model Review (#52) * Addressed AJ Stein's week 32 feedback for usnistgov#1331. * Addressed DRAFT: Update catalog & profile metaschema documentation (#51) * Update catalog & profile metaschema documentation * Add props to control identifier * Fixed broken syntax and addressed consistency in wording within the Profile 'merge' construct. * Adjustments to alter, moving to to an inline definition * cleaned up empty remark. * Removed redundant constraints * removed some redundant constraints * Preliminary work on URI documentation to address usnistgov#1249. * More work on document URI use in OSCAL * Updating data types related to usnistgov/metaschema#224. * Improved consistency of how URI concepts are discussed. * Added note about party locations * Updated Metaschema instances of `uri` and `uri-reference` data types to indicate their URI semantics. Resolves usnistgov#1249. * Added identifier props to control layer metaschemas (#55) * Responding to usnistgov#1066: metaschema edits; CSS enhancement (#56) * Whitespace cleanup in metadata metaschema * Apply suggestions from code review Co-authored-by: Alexander Stein <alexander.stein@nist.gov> Co-authored-by: Wendell Piez <wapiez@wendellpiez.com> Co-authored-by: Rene Tshiteya <rene-claude.tshiteya@gsa.gov>

@Rene2mt

…1263) * completed partial update of the Metadata object documentation. * adjustments to roles * adjusted the cardinality of location/address to make address optional. * Improved documentation and constraints related to location and parties * addressed the remainder of metadata and control feedback from @Rene2mt. * Improved the introductory remarks for a profile to better describe what a profile is and what it does. * Fixed a broken constraint that was not targeting the right node. * started refining descriptions and adding properties to describe identifier attributes. * Addressed feedback from AJ during 20220718-20220722. (#48) * Week 30 feedback on SSP model. (#49) * Proposed metaschema docs updates (#50) * Addressed feedback based on usnistgov#1392 * Adjustments based on model review feedback on 8/12. * Removed outdated merge phase remarks. Created issue #53 to address this. * Addressed A.J. Stein's Week 32 Feedback for Model Review (#52) * Addressed AJ Stein's week 32 feedback for usnistgov#1331. * Addressed DRAFT: Update catalog & profile metaschema documentation (#51) * Update catalog & profile metaschema documentation * Add props to control identifier * Fixed broken syntax and addressed consistency in wording within the Profile 'merge' construct. * Adjustments to alter, moving to to an inline definition * cleaned up empty remark. * Removed redundant constraints * removed some redundant constraints * Preliminary work on URI documentation to address usnistgov#1249. * More work on document URI use in OSCAL * Updating data types related to usnistgov/metaschema#224. * Improved consistency of how URI concepts are discussed. * Added note about party locations * Updated Metaschema instances of `uri` and `uri-reference` data types to indicate their URI semantics. Resolves usnistgov#1249. * Added identifier props to control layer metaschemas (#55) * Responding to usnistgov#1066: metaschema edits; CSS enhancement (#56) * Whitespace cleanup in metadata metaschema * Apply suggestions from code review Co-authored-by: Alexander Stein <alexander.stein@nist.gov> Co-authored-by: Wendell Piez <wapiez@wendellpiez.com> Co-authored-by: Rene Tshiteya <rene-claude.tshiteya@gsa.gov>

@Rene2mt

…1263) * completed partial update of the Metadata object documentation. * adjustments to roles * adjusted the cardinality of location/address to make address optional. * Improved documentation and constraints related to location and parties * addressed the remainder of metadata and control feedback from @Rene2mt. * Improved the introductory remarks for a profile to better describe what a profile is and what it does. * Fixed a broken constraint that was not targeting the right node. * started refining descriptions and adding properties to describe identifier attributes. * Addressed feedback from AJ during 20220718-20220722. (#48) * Week 30 feedback on SSP model. (#49) * Proposed metaschema docs updates (#50) * Addressed feedback based on usnistgov#1392 * Adjustments based on model review feedback on 8/12. * Removed outdated merge phase remarks. Created issue #53 to address this. * Addressed A.J. Stein's Week 32 Feedback for Model Review (#52) * Addressed AJ Stein's week 32 feedback for usnistgov#1331. * Addressed DRAFT: Update catalog & profile metaschema documentation (#51) * Update catalog & profile metaschema documentation * Add props to control identifier * Fixed broken syntax and addressed consistency in wording within the Profile 'merge' construct. * Adjustments to alter, moving to to an inline definition * cleaned up empty remark. * Removed redundant constraints * removed some redundant constraints * Preliminary work on URI documentation to address usnistgov#1249. * More work on document URI use in OSCAL * Updating data types related to usnistgov/metaschema#224. * Improved consistency of how URI concepts are discussed. * Added note about party locations * Updated Metaschema instances of `uri` and `uri-reference` data types to indicate their URI semantics. Resolves usnistgov#1249. * Added identifier props to control layer metaschemas (#55) * Responding to usnistgov#1066: metaschema edits; CSS enhancement (#56) * Whitespace cleanup in metadata metaschema * Apply suggestions from code review Co-authored-by: Alexander Stein <alexander.stein@nist.gov> Co-authored-by: Wendell Piez <wapiez@wendellpiez.com> Co-authored-by: Rene Tshiteya <rene-claude.tshiteya@gsa.gov>

@Rene2mt

…1263) * completed partial update of the Metadata object documentation. * adjustments to roles * adjusted the cardinality of location/address to make address optional. * Improved documentation and constraints related to location and parties * addressed the remainder of metadata and control feedback from @Rene2mt. * Improved the introductory remarks for a profile to better describe what a profile is and what it does. * Fixed a broken constraint that was not targeting the right node. * started refining descriptions and adding properties to describe identifier attributes. * Addressed feedback from AJ during 20220718-20220722. (#48) * Week 30 feedback on SSP model. (#49) * Proposed metaschema docs updates (#50) * Addressed feedback based on usnistgov#1392 * Adjustments based on model review feedback on 8/12. * Removed outdated merge phase remarks. Created issue #53 to address this. * Addressed A.J. Stein's Week 32 Feedback for Model Review (#52) * Addressed AJ Stein's week 32 feedback for usnistgov#1331. * Addressed DRAFT: Update catalog & profile metaschema documentation (#51) * Update catalog & profile metaschema documentation * Add props to control identifier * Fixed broken syntax and addressed consistency in wording within the Profile 'merge' construct. * Adjustments to alter, moving to to an inline definition * cleaned up empty remark. * Removed redundant constraints * removed some redundant constraints * Preliminary work on URI documentation to address usnistgov#1249. * More work on document URI use in OSCAL * Updating data types related to usnistgov/metaschema#224. * Improved consistency of how URI concepts are discussed. * Added note about party locations * Updated Metaschema instances of `uri` and `uri-reference` data types to indicate their URI semantics. Resolves usnistgov#1249. * Added identifier props to control layer metaschemas (#55) * Responding to usnistgov#1066: metaschema edits; CSS enhancement (#56) * Whitespace cleanup in metadata metaschema * Apply suggestions from code review Co-authored-by: Alexander Stein <alexander.stein@nist.gov> Co-authored-by: Wendell Piez <wapiez@wendellpiez.com> Co-authored-by: Rene Tshiteya <rene-claude.tshiteya@gsa.gov>

wendellpiez requested a review from david-waltermire as a code owner July 29, 2022 22:07

david-waltermire force-pushed the issue1066-metaschema-updates branch from 7ed2bd2 to d05ed55 Compare August 1, 2022 16:01

wendellpiez added 4 commits August 12, 2022 11:16

Addressing usnistgov#1392 wish me luck

1135ad8

In case new improved authoring CSS is wanted

a35ec95

Whitespace fixup for legibility

872a28e

Further whitespace dampening

ef16f20

david-waltermire force-pushed the issue1066-metaschema-updatesA branch from c5cddb2 to ef16f20 Compare August 12, 2022 15:17