Skip to content
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

Identifier Scoping and Uniqueness Documentation Review #1066

Open
7 of 29 tasks
Rene2mt opened this issue Dec 9, 2021 · 4 comments · Fixed by #1263
Open
7 of 29 tasks

Identifier Scoping and Uniqueness Documentation Review #1066

Rene2mt opened this issue Dec 9, 2021 · 4 comments · Fixed by #1263
Labels
Aged A label for issues older than 2023-01-01 Epic A collection of issues to be worked on over a series of sprints ongoing effort Scope: Documentation This issue relates to OSCAL documentation.

Comments

@Rene2mt
Copy link
Contributor

Rene2mt commented Dec 9, 2021 •
edited by david-waltermire
Loading

This issue is for a comprehensive review of the changes made in PR#941to ensure documentation describes identifier uniqueness and scoping clearly and accurately. The (peer) review should include the following:

Concepts - Identifier User Page Peer Review (see added Identifier Use page )

  • Clear description of identifier types
  • Clear description of identifier description
  • Clear description of identifier scope (review tables)

Metaschemas to Peer Review: (see metaschema identifier description changes)

  • Common
    • Oscal_metadata_metaschema.xml
  • Control Layer (Review Control layer models #1331)
    • Oscal_control-common_metaschema.xml
    • Oscal_catalog_metaschema.xml
    • Oscal_profile_metaschema.xml
  • Implementation Layer
  • Assessment Layer
    • Oscal_assessment-common_metaschema.xml
    • Oscal_assessment-plan_metaschema.xml
    • Oscal_assessment-results_metaschema.xml
    • Oscal_poam_metaschema.xml

Peer Review Checklist for each of the Metaschemas listed above:

  • Check all "Identifier Declarations" for the following:
    • Description is satisfactory (e.g., specific enough, grammatically correct, etc.)
    • Description clearly states if identifier is "machine-oriented" or "human oriented"
    • Description clearly states the uniqueness of the identifier (e.g. locally vs globally unique)
    • Description clearly states if the scope (e.g. instance vs cross-instance)
    • Description is clear in how to externally reference the identifier (e.g. if the OSCAL resource where the identifier is defined is imported into another OSCAL instance)
    • Description clearly states how revision to the containing OSCAL instance impact the identifier
  • Check all "Identifier References" for the following:
    • Description is satisfactory (e.g., specific enough, grammatically correct, etc.)
    • When applicable, indicates the source (local or imported document) of the identifier being referenced
@Rene2mt Rene2mt mentioned this issue Jan 6, 2022
Closed
6 tasks
@david-waltermire david-waltermire added Epic A collection of issues to be worked on over a series of sprints ongoing effort Scope: Documentation This issue relates to OSCAL documentation. and removed question labels Jan 13, 2022
@david-waltermire david-waltermire added this to the OSCAL 1.0.2 milestone Jan 21, 2022
@Rene2mt Rene2mt self-assigned this Feb 10, 2022
@david-waltermire david-waltermire mentioned this issue May 12, 2022
Merged
9 tasks
@david-waltermire david-waltermire mentioned this issue May 31, 2022
Open
6 tasks
@aj-stein-nist aj-stein-nist mentioned this issue Jun 10, 2022
Closed
@david-waltermire david-waltermire linked a pull request Jun 16, 2022 that will close this issue
Updates to OSCAL Metaschema documentation and constraints #1263
Merged
9 tasks
@david-waltermire david-waltermire mentioned this issue Jul 1, 2022
Closed
11 tasks
This was referenced Jul 19, 2022
Merged
Open
@david-waltermire
Copy link
Contributor

As follow-on work, we could normalize the description to be one or two sentences. The first sentence fragment might start with a verb that describes what the thing does. Such as "Describes what the thing does."

@david-waltermire
Copy link
Contributor

Need to extract RMF constraints into an external constraints file.

@aj-stein-nist aj-stein-nist mentioned this issue Jul 22, 2022
Open
5 tasks
@GaryGapinski
Copy link

Worthy of mention: UUIDs are not case-sensitive, thus uniqueness and comparisons are not simple equalities.

@david-waltermire david-waltermire mentioned this issue Aug 1, 2022
Closed
5 tasks
wendellpiez added a commit to wendellpiez/OSCAL that referenced this issue Aug 26, 2022
@wendellpiez
Responding to usnistgov#1066: metaschema edits; CSS enhancement
dd836a1
david-waltermire pushed a commit to wendellpiez/OSCAL that referenced this issue Sep 9, 2022
@wendellpiez @david-waltermire
Responding to usnistgov#1066: metaschema edits; CSS enhancement
f3f1ecf
david-waltermire added a commit to david-waltermire/OSCAL that referenced this issue Sep 9, 2022
@wendellpiez @david-waltermire
Responding to usnistgov#1066: metaschema edits; CSS enhancement (#56)
6882d51 
* Responding to usnistgov#1066: metaschema edits; CSS enhancement
* Whitespace cleanup in metadata metaschema
* Apply suggestions from code review

Co-authored-by: David Waltermire <[email protected]>
david-waltermire added a commit to david-waltermire/OSCAL that referenced this issue Sep 26, 2022
@wendellpiez @david-waltermire
Responding to usnistgov#1066: metaschema edits; CSS enhancement (#56)
7894fef 
* Responding to usnistgov#1066: metaschema edits; CSS enhancement
* Whitespace cleanup in metadata metaschema
* Apply suggestions from code review

Co-authored-by: David Waltermire <[email protected]>
david-waltermire added a commit that referenced this issue Sep 27, 2022
@david-waltermire @aj-stein-nist
@wendellpiez @Rene2mt
Updates to OSCAL Metaschema documentation and constraints (#1263)
39477fd 
* 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 #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 #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 #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 #1249.
* Added identifier props to control layer metaschemas (#55)
* Responding to #1066: metaschema edits; CSS enhancement (#56)
* Whitespace cleanup in metadata metaschema
* Apply suggestions from code review

Co-authored-by: Alexander Stein <[email protected]>
Co-authored-by: Wendell Piez <[email protected]>
Co-authored-by: Rene Tshiteya <[email protected]>
aj-stein-nist added a commit that referenced this issue Oct 18, 2022
@david-waltermire @aj-stein-nist
@wendellpiez @Rene2mt
Updates to OSCAL Metaschema documentation and constraints (#1263)
52b81c9 
* 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 #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 #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 #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 #1249.
* Added identifier props to control layer metaschemas (#55)
* Responding to #1066: metaschema edits; CSS enhancement (#56)
* Whitespace cleanup in metadata metaschema
* Apply suggestions from code review

Co-authored-by: Alexander Stein <[email protected]>
Co-authored-by: Wendell Piez <[email protected]>
Co-authored-by: Rene Tshiteya <[email protected]>
david-waltermire added a commit that referenced this issue Oct 31, 2022
@david-waltermire @aj-stein-nist
@wendellpiez @Rene2mt
Updates to OSCAL Metaschema documentation and constraints (#1263)
6f775a4 
* 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 #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 #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 #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 #1249.
* Added identifier props to control layer metaschemas (#55)
* Responding to #1066: metaschema edits; CSS enhancement (#56)
* Whitespace cleanup in metadata metaschema
* Apply suggestions from code review

Co-authored-by: Alexander Stein <[email protected]>
Co-authored-by: Wendell Piez <[email protected]>
Co-authored-by: Rene Tshiteya <[email protected]>
aj-stein-nist added a commit to aj-stein-nist/OSCAL-forked that referenced this issue Jan 10, 2023
@david-waltermire @aj-stein-nist
@wendellpiez @Rene2mt
Updates to OSCAL Metaschema documentation and constraints (usnistgov#…
d1902c3 
…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 <[email protected]>
Co-authored-by: Wendell Piez <[email protected]>
Co-authored-by: Rene Tshiteya <[email protected]>
aj-stein-nist added a commit to aj-stein-nist/OSCAL-forked that referenced this issue Feb 6, 2023
@david-waltermire @aj-stein-nist
@wendellpiez @Rene2mt
Updates to OSCAL Metaschema documentation and constraints (usnistgov#…
f5a03e7 
…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 <[email protected]>
Co-authored-by: Wendell Piez <[email protected]>
Co-authored-by: Rene Tshiteya <[email protected]>
aj-stein-nist added a commit to aj-stein-nist/OSCAL-forked that referenced this issue Jun 29, 2023
@david-waltermire @aj-stein-nist
@wendellpiez @Rene2mt
Updates to OSCAL Metaschema documentation and constraints (usnistgov#…
ffd5032 
…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 <[email protected]>
Co-authored-by: Wendell Piez <[email protected]>
Co-authored-by: Rene Tshiteya <[email protected]>
aj-stein-nist added a commit to aj-stein-nist/OSCAL-forked that referenced this issue Jul 10, 2023
@david-waltermire @aj-stein-nist
@wendellpiez @Rene2mt
Updates to OSCAL Metaschema documentation and constraints (usnistgov#…
988817c 
…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 <[email protected]>
Co-authored-by: Wendell Piez <[email protected]>
Co-authored-by: Rene Tshiteya <[email protected]>
@aj-stein-nist aj-stein-nist removed this from the v1.1.0 milestone Jul 27, 2023
@aj-stein-nist aj-stein-nist moved this from Todo to Needs Refinement in NIST OSCAL Work Board Sep 27, 2023
@aj-stein-nist
Copy link
Contributor

As an epic predating #1688 board reorganization, I will want to label this as needs refinement for now until it can be broken down, rescoped, and or closed.

aj-stein-nist added a commit to galtm/OSCAL that referenced this issue Sep 28, 2023
@david-waltermire @aj-stein-nist
@wendellpiez @Rene2mt
Updates to OSCAL Metaschema documentation and constraints (usnistgov#…
947048d 
…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 <[email protected]>
Co-authored-by: Wendell Piez <[email protected]>
Co-authored-by: Rene Tshiteya <[email protected]>
@Compton-US Compton-US added the Aged A label for issues older than 2023-01-01 label Nov 2, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
Aged A label for issues older than 2023-01-01 Epic A collection of issues to be worked on over a series of sprints ongoing effort Scope: Documentation This issue relates to OSCAL documentation.
Projects
NIST OSCAL Work Board
Status: Needs Refinement
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Updates to OSCAL Metaschema documentation and constraints david-waltermire/OSCAL
5 participants
@GaryGapinski @david-waltermire @Rene2mt @aj-stein-nist @Compton-US