Updates to OSCAL Metaschema documentation and constraints #1263

david-waltermire · 2022-05-12T20:41:36Z

Committer Notes

Metaschema updates in support of a comprehensive review of the OSCAL models (#1066).

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

david-waltermire · 2022-07-29T16:14:08Z

Today we discussed annotating identifier fields as follows using the new Metaschema prop feature.

Must be one of:

<prop name="value-type" value="identifier"/>
<prop name="identifier-type" value="machine-oriented"/>
<prop name="identifier-type" value="human-oriented"/>
# Need to update the documentation to clarify that the value set is constrained and what the options are.
<prop name="identifier-type" value="unspecified"/>

Must be one of:

<prop name="identifier-uniqueness" value="global"/>
<prop name="identifier-uniqueness" value="local-instance"/>

Must be one of:

<prop name="identifier-scope" value="instance"/>
<prop name="identifier-scope" value="cross-instance"/>

Must be one of:

<prop name="identifier-persistence" value="per-instance"/>
<prop name="identifier-persistence" value="change-on-write"/>

src/metaschema/oscal_metadata_metaschema.xml

* 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]>

Co-authored-by: Alexander Stein <[email protected]>

david-waltermire · 2022-09-26T17:48:03Z

@aj-stein-nist Can you give this a quick once over? I need a review to merge this.

wendellpiez

LGTM nice work

david-waltermire · 2022-09-27T13:17:10Z

Merging this well reviewed PR.

@Rene2mt

* 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]>

Recently added links in documentation refer to href="/OSCAL" and not href="https://pages.nist.gov/OSCAL" in error or to simplify link gen and lookup. Now that we are remapping the full URLs to local paths and offsets for link-checking, we want these to be consistent across the board in Metaschema after usnistgov#1263.

…anch (#1518) * Fix documentation relative paths in Metaschema Recently added links in documentation refer to href="/OSCAL" and not href="https://pages.nist.gov/OSCAL" in error or to simplify link gen and lookup. Now that we are remapping the full URLs to local paths and offsets for link-checking, we want these to be consistent across the board in Metaschema after #1263. * Pushing generated website pages manual override [ci skip]. * Restore rel paths for develop branch ref model docs and fix link checks. * Test full URLs per @dave-waltermire-nist's PR feedback.

@Rene2mt

* 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]>

…anch (#1518) * Fix documentation relative paths in Metaschema Recently added links in documentation refer to href="/OSCAL" and not href="https://pages.nist.gov/OSCAL" in error or to simplify link gen and lookup. Now that we are remapping the full URLs to local paths and offsets for link-checking, we want these to be consistent across the board in Metaschema after #1263. * Pushing generated website pages manual override [ci skip]. * Restore rel paths for develop branch ref model docs and fix link checks. * Test full URLs per @dave-waltermire-nist's PR feedback.

@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 <[email protected]> Co-authored-by: Wendell Piez <[email protected]> Co-authored-by: Rene Tshiteya <[email protected]>

…anch (usnistgov#1518) * Fix documentation relative paths in Metaschema Recently added links in documentation refer to href="/OSCAL" and not href="https://pages.nist.gov/OSCAL" in error or to simplify link gen and lookup. Now that we are remapping the full URLs to local paths and offsets for link-checking, we want these to be consistent across the board in Metaschema after usnistgov#1263. * Pushing generated website pages manual override [ci skip]. * Restore rel paths for develop branch ref model docs and fix link checks. * Test full URLs per @dave-waltermire-nist's PR feedback.

@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 <[email protected]> Co-authored-by: Wendell Piez <[email protected]> Co-authored-by: Rene Tshiteya <[email protected]>

…anch (usnistgov#1518) * Fix documentation relative paths in Metaschema Recently added links in documentation refer to href="/OSCAL" and not href="https://pages.nist.gov/OSCAL" in error or to simplify link gen and lookup. Now that we are remapping the full URLs to local paths and offsets for link-checking, we want these to be consistent across the board in Metaschema after usnistgov#1263. * Pushing generated website pages manual override [ci skip]. * Restore rel paths for develop branch ref model docs and fix link checks. * Test full URLs per @dave-waltermire-nist's PR feedback.

…anch (#1518) * Fix documentation relative paths in Metaschema Recently added links in documentation refer to href="/OSCAL" and not href="https://pages.nist.gov/OSCAL" in error or to simplify link gen and lookup. Now that we are remapping the full URLs to local paths and offsets for link-checking, we want these to be consistent across the board in Metaschema after usnistgov/OSCAL#1263. * Pushing generated website pages manual override [ci skip]. * Restore rel paths for develop branch ref model docs and fix link checks. * Test full URLs per @dave-waltermire-nist's PR feedback.

@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 <[email protected]> Co-authored-by: Wendell Piez <[email protected]> Co-authored-by: Rene Tshiteya <[email protected]>

@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 <[email protected]> Co-authored-by: Wendell Piez <[email protected]> Co-authored-by: Rene Tshiteya <[email protected]>

…anch (usnistgov#1518) * Fix documentation relative paths in Metaschema Recently added links in documentation refer to href="/OSCAL" and not href="https://pages.nist.gov/OSCAL" in error or to simplify link gen and lookup. Now that we are remapping the full URLs to local paths and offsets for link-checking, we want these to be consistent across the board in Metaschema after usnistgov#1263. * Pushing generated website pages manual override [ci skip]. * Restore rel paths for develop branch ref model docs and fix link checks. * Test full URLs per @dave-waltermire-nist's PR feedback.

@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 <[email protected]> Co-authored-by: Wendell Piez <[email protected]> Co-authored-by: Rene Tshiteya <[email protected]>

…anch (usnistgov#1518) * Fix documentation relative paths in Metaschema Recently added links in documentation refer to href="/OSCAL" and not href="https://pages.nist.gov/OSCAL" in error or to simplify link gen and lookup. Now that we are remapping the full URLs to local paths and offsets for link-checking, we want these to be consistent across the board in Metaschema after usnistgov#1263. * Pushing generated website pages manual override [ci skip]. * Restore rel paths for develop branch ref model docs and fix link checks. * Test full URLs per @dave-waltermire-nist's PR feedback.

david-waltermire changed the title ~~completed partial update of the Metadata object documentation.~~ Updates to OSCAL Metaschema documentation and constraints May 12, 2022

david-waltermire self-assigned this May 12, 2022

david-waltermire added this to the OSCAL 1.1.0 milestone May 12, 2022

david-waltermire force-pushed the develop branch from 6587e35 to 51741c7 Compare May 17, 2022 12:13

david-waltermire force-pushed the issue1066-metaschema-updates branch from 622b65f to 7a75ba6 Compare May 19, 2022 19:22

aj-stein-nist reviewed May 27, 2022

View reviewed changes

src/metaschema/oscal_metadata_metaschema.xml Show resolved Hide resolved

david-waltermire mentioned this pull request May 31, 2022

Clarify behavior for conflicts in role, location, party, and reference identifiers across imported OSCAL content #1290

Open

6 tasks

david-waltermire linked an issue Jun 16, 2022 that may be closed by this pull request

Identifier Scoping and Uniqueness Documentation Review #1066

Open

29 tasks

david-waltermire force-pushed the develop branch from b7d376f to d8682eb Compare June 21, 2022 16:14

david-waltermire changed the base branch from develop to release-1.0 June 24, 2022 15:44

david-waltermire force-pushed the issue1066-metaschema-updates branch from 70cbd3b to 5b4e58b Compare June 24, 2022 15:46

david-waltermire modified the milestones: OSCAL 1.1.0, OSCAL 1.0.5 Jun 24, 2022

This was linked to issues Jul 1, 2022

Provide guidance around relative URI handling for href instances #1249

Closed

Review Control layer models #1331

Closed

david-waltermire force-pushed the release-1.0 branch from 9889ff2 to 4a4a2c5 Compare July 13, 2022 21:40

david-waltermire mentioned this pull request Jul 28, 2022

Review Control layer models #1331

Closed

11 tasks

wendellpiez mentioned this pull request Jul 28, 2022

Submit Model docs feedback on profile model #1392

Closed

3 tasks

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

wendellpiez mentioned this pull request Jul 29, 2022

Proposed metaschema docs updates david-waltermire/OSCAL#50

Merged

9 tasks

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

david-waltermire marked this pull request as ready for review August 19, 2022 16:34

david-waltermire force-pushed the issue1066-metaschema-updates branch from 5863b73 to ea31b2b Compare August 19, 2022 17:22

david-waltermire changed the base branch from release-1.0 to develop August 21, 2022 03:27

david-waltermire commented Aug 21, 2022

View reviewed changes

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

david-waltermire commented Aug 21, 2022

View reviewed changes

src/metaschema/oscal_metadata_metaschema.xml Show resolved Hide resolved

david-waltermire modified the milestones: OSCAL 1.0.5, OSCAL 1.1.0 Aug 21, 2022

david-waltermire force-pushed the issue1066-metaschema-updates branch from 0e411b7 to 0aa0e7a Compare August 22, 2022 23:10

wendellpiez and others added 3 commits September 26, 2022 13:29

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

Apply suggestions from code review

16f2bcd

Co-authored-by: Alexander Stein <[email protected]>

Update docs/content/concepts/uri-use.md

172dc90

Co-authored-by: Alexander Stein <[email protected]>

david-waltermire force-pushed the issue1066-metaschema-updates branch from 9849fbf to 172dc90 Compare September 26, 2022 17:30

david-waltermire requested review from aj-stein-nist and wendellpiez September 26, 2022 17:47

wendellpiez approved these changes Sep 26, 2022

View reviewed changes

david-waltermire merged commit 39477fd into usnistgov:develop Sep 27, 2022

aj-stein-nist mentioned this pull request Oct 18, 2022

Fix broken uri-use page links in updated reference docs of develop branch #1518

Merged

5 tasks

aj-stein-nist removed this from the v1.1.0 milestone Jul 27, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Updates to OSCAL Metaschema documentation and constraints #1263

Updates to OSCAL Metaschema documentation and constraints #1263

david-waltermire commented May 12, 2022 •

edited

Loading

david-waltermire commented Jul 29, 2022 •

edited

Loading

david-waltermire commented Sep 26, 2022

wendellpiez left a comment

david-waltermire commented Sep 27, 2022

Updates to OSCAL Metaschema documentation and constraints #1263

Updates to OSCAL Metaschema documentation and constraints #1263

Conversation

david-waltermire commented May 12, 2022 • edited Loading

Committer Notes

All Submissions:

Changes to Core Features:

david-waltermire commented Jul 29, 2022 • edited Loading

david-waltermire commented Sep 26, 2022

wendellpiez left a comment

Choose a reason for hiding this comment

david-waltermire commented Sep 27, 2022

david-waltermire commented May 12, 2022 •

edited

Loading

david-waltermire commented Jul 29, 2022 •

edited

Loading