A.J. Stein's Week 30 Feedback for Model Review by aj-stein-nist · Pull Request #49 · david-waltermire/OSCAL

aj-stein-nist · 2022-07-29T14:27:52Z

Committer Notes

This is AJ's week 30 feedback for model review, focused as instructed on SSPs.

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_ssp_metaschema.xml

aj-stein-nist · 2022-07-29T15:24:18Z

src/metaschema/oscal_implementation-common_metaschema.xml

            <formal-name>System Identification</formal-name>
            <!-- Identifier Declaration -->
-            <description>A <a href="/concepts/identifier-use/#human-oriented">human-oriented</a>, <a href="/concepts/identifier-use/#globally-unique">globally unique</a> identifier with <a href="/concepts/identifier-use/#cross-instance">cross-instance</a> scope that can be used to reference this system identification property elsewhere in <a href="/concepts/identifier-use/#scope">this or other OSCAL instances</a>. When referencing an externally defined <code>system identification</code>, the <code>system identification</code> must be used in the context of the external / imported OSCAL instance (e.g., uri-reference). This string should be assigned <a href="/concepts/identifier-use/#consistency">per-subject</a>, which means it should be consistently used to identify the same system across revisions of the document.</description>
+            <description>A <a href="/concepts/identifier-use/#globally-unique">globally unique</a> identifier with <a href="/concepts/identifier-use/#cross-instance">cross-instance</a> scope that can be used to reference this system identification property elsewhere in <a href="/concepts/identifier-use/#scope">this or other OSCAL instances</a>. When referencing an externally defined <code>system identification</code>, the <code>system identification</code> must be used in the context of the external / imported OSCAL instance (e.g., uri-reference). This string should be assigned <a href="/concepts/identifier-use/#consistency">per-subject</a>, which means it should be consistently used to identify the same system across revisions of the document.</description>


I am unsure of my recommendation here, but there can be one of two outcomes in my opinion. Feedback welcome. As it stands, in the allowed-values/enum, we have system identifer types that are both human oriented or machine-oriented like UUIDs (RFC-4122)

We suggest this is not only a human-oriented identifier in the documentation string, because we recommend both a type for human-oriented and machine-oriented.

We update the enumeration values

Do nothing and leave it is as-is.

1 is easier, and 2 might be more disruptive and less than ideal.

Key Model Review Criteria:

This criteria is given approach 1. 2 is more complex, 3 obviously none of it applies. :-)

Is this proposed change to 1) the model itself, 2) documentation embedded in the model, or 3) both? 2

Is this proposed change to 1) enhance the model in short-term way that will not break backwards compatibility, 2) a significant change that will require breaking backwards compatibility or 3) it is unclear, and I need to provide explanation? 1

Is this proposed change to 1) current operational use of one model or 2) cross-document mechanics or 3) not change the operational use of the models? 3

We had some good constructive discussion about this, and the documentation approach is ill-advised. What would be preferred, as part of the docs with machine readable attributes in the Metaschema source. We had talked about that, but we need to further that in Metaschema (per usnistgov/metaschema#222). Also moving forward, the equivalent change that will result here is not approach 1, leave it out.

I will roll back the change and leave a comment, but we need to further usnistgov/metaschema#222 before we can have a different approach that is explicit and not implicit (like approach 1).

src/metaschema/oscal_ssp_metaschema.xml

aj-stein-nist · 2022-08-12T13:08:08Z

Updated and rebased before our model sync meeting.

david-waltermire

Thanks!

@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>

aj-stein-nist changed the base branch from main to issue1066-metaschema-updates July 29, 2022 14:28

aj-stein-nist commented Jul 29, 2022

View reviewed changes

src/metaschema/oscal_ssp_metaschema.xml Show resolved Hide resolved

aj-stein-nist force-pushed the issue1066-metaschema-updates-feedback-week30 branch from 7e7564d to 79a8e14 Compare July 29, 2022 15:17

aj-stein-nist commented Jul 29, 2022

View reviewed changes

aj-stein-nist force-pushed the issue1066-metaschema-updates-feedback-week30 branch from 79a8e14 to 63e0fd3 Compare July 29, 2022 15:40

aj-stein-nist commented Jul 29, 2022

View reviewed changes

src/metaschema/oscal_ssp_metaschema.xml Outdated Show resolved Hide resolved

aj-stein-nist mentioned this pull request Jul 29, 2022

Add Identifier Use Properties to Metaschema Schema for Model Use usnistgov/metaschema#222

Closed

3 tasks

aj-stein-nist force-pushed the issue1066-metaschema-updates-feedback-week30 branch 4 times, most recently from 311f040 to b48662c Compare July 29, 2022 18:25

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

Week 30 feedback on SSP model.

d3745d2

aj-stein-nist force-pushed the issue1066-metaschema-updates-feedback-week30 branch from b48662c to d3745d2 Compare August 12, 2022 13:07

aj-stein-nist marked this pull request as ready for review August 12, 2022 13:08

aj-stein-nist changed the title ~~Week 30 Feedback for Model Review~~ A.J. Stein's Week 30 Feedback for Model Review Aug 12, 2022

david-waltermire approved these changes Aug 12, 2022

View reviewed changes

david-waltermire merged commit 3c72868 into david-waltermire:issue1066-metaschema-updates Aug 12, 2022

david-waltermire pushed a commit that referenced this pull request Aug 19, 2022

Week 30 feedback on SSP model. (#49)

7b26e7f

david-waltermire pushed a commit that referenced this pull request Aug 22, 2022

Week 30 feedback on SSP model. (#49)

e031480

david-waltermire pushed a commit that referenced this pull request Aug 23, 2022

Week 30 feedback on SSP model. (#49)

a9e99ef

david-waltermire pushed a commit that referenced this pull request Aug 23, 2022

Week 30 feedback on SSP model. (#49)

7e1649e

david-waltermire pushed a commit that referenced this pull request Sep 26, 2022

Week 30 feedback on SSP model. (#49)

364328d

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

A.J. Stein's Week 30 Feedback for Model Review#49

A.J. Stein's Week 30 Feedback for Model Review#49
david-waltermire merged 1 commit intodavid-waltermire:issue1066-metaschema-updatesfrom
aj-stein-nist:issue1066-metaschema-updates-feedback-week30

aj-stein-nist commented Jul 29, 2022

Uh oh!

Uh oh!

aj-stein-nist Jul 29, 2022 •

edited

Loading

Uh oh!

aj-stein-nist Jul 29, 2022

Uh oh!

Uh oh!

aj-stein-nist commented Aug 12, 2022

Uh oh!

david-waltermire left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

aj-stein-nist commented Jul 29, 2022

Committer Notes

All Submissions:

Changes to Core Features:

Uh oh!

Uh oh!

aj-stein-nist Jul 29, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aj-stein-nist Jul 29, 2022

Choose a reason for hiding this comment

Uh oh!

Uh oh!

aj-stein-nist commented Aug 12, 2022

Uh oh!

david-waltermire left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

aj-stein-nist Jul 29, 2022 •

edited

Loading