1062 ssp link semantics by Rene2mt · Pull Request #1167 · usnistgov/OSCAL

Rene2mt · 2022-03-11T20:10:01Z

Committer Notes

This pull request adds content to the SSP concepts page to clarify link semantics in the SSP model to address issue #1062.

All Submissions:

Have you selected the correct base branch per Contributing guidance?
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.

aj-stein-nist

It seems the PR needs to be rebased, but I have some minor suggestions. Sorry it took long to give pertinent feedback, Rene. I will review again more thoroughly for substantive feedback about content tomorrow, not small grammar fixes. 😆

docs/content/concepts/layer/implementation/ssp/_index.md

aj-stein-nist · 2022-03-17T16:36:59Z

Hey @Rene2mt, @david-waltermire-nist and I rebased this PR for you. Can you delete your local copy of the branch and pull down the remote one we touched up (with git reset or git rebase) for you when you have a chance?

We still have some outstanding feedback. Can we talk about it later today?

Rene2mt · 2022-03-17T17:22:08Z

Hey @Rene2mt, @david-waltermire-nist and I rebased this PR for you. Can you delete your local copy of the branch and pull down the remote one we touched up (with git reset or git rebase) for you when you have a chance?

We still have some outstanding feedback. Can we talk about it later today?

Yes, we can go over feedback later today.

docs/content/concepts/layer/implementation/ssp/_index.md

david-waltermire

This looks good. Thanks!

aj-stein-nist

Content looks good and I think it is a wonderful addition, @Rene2mt! I did find some small issues around typos, consistency, and wording we might want to quickly tighter up before release before we pull it in for the release.

/cc @david-waltermire-nist

docs/content/concepts/layer/implementation/ssp/_index.md

david-waltermire

While I love this table, I think there are still issues to be addressed.

The text of the reference link is ambiguous regarding the path into the model.
The target of the reference link is point to the XML index that mentions other locations in the model, including the one being referenced. It also doesn't provide a JSON link.
The targets of the reference are not linked either.

For these reasons, the table might be confusing.

I'd like to come up with a way to address these issues. We can push this back to 1.0.3 to allow for some time to address this.

Rene2mt · 2022-03-24T14:12:54Z

Agreed. Latest WIP commit made the following changes

Reference column - In order to make less ambiguous, named the model reference element and provided direct links to both XML model reference and JSON model reference. Where the reference could be in various parts of the SSP model (e.g., component-uuid), added a separate table row for each SSP model reference location.
Target Element column - Also updated, adding links to both XML model reference and JSON model reference.
Misc description column updates.

We can do another round of review on these latest updates.

wendellpiez · 2022-04-28T19:46:09Z

docs/content/concepts/layer/implementation/ssp/_index.md

+
+- **Local**: Scenario where an identifier references information in the same OSCAL instance.  This scenario supports  “compile time” enforcement of constraints since the validity of the reference can be checked as soon as the SSP is authored.
+- **Import-Profile**:  Scenario where an identifier references information in its imported profile.  This scenario can support “compile time” enforcement of constraints if there is access to the imported OSCAL profile.
+- **Leveraged-Authorizations/Links**:  In this scenario where an OSCAL SSP has leveraged-authorization(s), some of the information in the leveraged SSP may be referenced (e.g., if the leveraged SSP is also in OSCAL format).  This scenario supports “runtime” validation of constraints since SSP author may or may not have access the leveraged system SSP to validate / enforce the referential integrity.  However, the authorizing official (AO) must ultimately validate any such links and references.


Suggest:

Links to leveraged authorizations: In a scenario where an OSCAL SSP has a leveraged authorization, some of the information in a leveraged SSP may be referenced (if the leveraged SSP is also in OSCAL format).

Reworked this section, removing un-necessary hyphens and capitalization. Created subsection headers for instance, cross instance, and external with narrative scenario descriptions.

david-waltermire · 2022-04-28T21:39:51Z

@Rene2mt I just rebased this onto release-1.0. I can walk you through resyncing your working branch.

iMichaela · 2022-04-29T02:01:18Z

docs/content/concepts/layer/implementation/ssp/_index.md


+### Identifier References
+
+An OSCAL SSP may contain references to information that is defined locally (e.g., in the SSP model) or externally (e.g., in a referenced profile, catalog, or component definition model).  The following lists the mechanisms through which objects in an OSCAL SSP may "link" to other OSCAL content:


The locally defined references reside in OSCAL SSP content or Catalog/Profile/CDef content, and not in the mentioned models).

Use instance vs cross-instance terminology from the identifier scoping instead of "locally", etc.

Reworded as:
An OSCAL SSP may contain references to information that is instance scoped (e.g., in the SSP model), cross-instance scoped (e.g., in a referenced profile, catalog, or component definition model), or external (e.g., references to non-OSCAL resources). The following summarizes the scenarios where an OSCAL SSP may have references to other content.

iMichaela · 2022-04-29T02:12:24Z

docs/content/concepts/layer/implementation/ssp/_index.md

+
+An OSCAL SSP may contain references to information that is defined locally (e.g., in the SSP model) or externally (e.g., in a referenced profile, catalog, or component definition model).  The following lists the mechanisms through which objects in an OSCAL SSP may "link" to other OSCAL content:
+
+- **Local**: Scenario where an identifier references information in the same OSCAL instance.  This scenario supports  “compile time” enforcement of constraints since the validity of the reference can be checked as soon as the SSP is authored.


I suggest classifying the references as local and external with different use cases for the external type of references: 1) in another OSCAL instance like 1.1) an imported profile, 1.2) in a leveraged authorization, 1.3) in a cdef sourced by a component of a system or 2) in a document referenced by a general link.

We should use local and cross-instance to be consistent with the identifier scoping. External should be limited to references to external non-OSCAL resources.

Created subsection headers for instance, cross instance, and external with narrative scenario descriptions.

iMichaela · 2022-04-29T02:15:24Z

docs/content/concepts/layer/implementation/ssp/_index.md

+| [responsible-role/party-uuid](/reference/latest/system-security-plan/xml-index/#/party-uuid) | Local SSP, leveraged-authorization | Party | UUID         | A single target role must be found by the UUID. |
+-->
 ### Modeling Validation Information
 OSCAL is designed to allow capture relevant details related to independent validation of components. See the [Validation Modeling](/learn/tutorials/validation-modeling/) tutorial for details.


OSCAL is designed to allow the capture of relevant ...

docs/content/concepts/layer/implementation/ssp/_index.md

david-waltermire · 2022-04-29T18:26:24Z

docs/content/concepts/layer/implementation/ssp/_index.md

+
+The following table summarizes constraints for identifier references in an OSCAL SSP:
+
+| Reference | Target Scope | Target Element | Target ID Type | Referential Constraint Description |


In the table can you link to the data type definition? https://pages.nist.gov/OSCAL/reference/datatypes/

david-waltermire · 2022-05-04T21:45:13Z

@Rene2mt I made a PR against your working branch (Rene2mt#3) regarding #1167.

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

Co-authored-by: David Waltermire <david.waltermire@nist.gov>

david-waltermire

LGTM. Thanks!

* Update SSP concepts page * Clarify link semantics in SSP model Co-authored-by: Alexander Stein <alexander.stein@nist.gov> Co-authored-by: David Waltermire <david.waltermire@nist.gov>

aj-stein-nist suggested changes Mar 15, 2022

View reviewed changes

docs/content/concepts/layer/implementation/ssp/_index.md Outdated Show resolved Hide resolved

docs/content/concepts/layer/implementation/ssp/_index.md Outdated Show resolved Hide resolved

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

Clarification of link semantics in SSP model #1062

Closed

david-waltermire self-requested a review March 17, 2022 15:44

aj-stein-nist force-pushed the 1062-ssp-link-semantics branch from fa417f6 to e422a05 Compare March 17, 2022 16:35

david-waltermire reviewed Mar 17, 2022

View reviewed changes

docs/content/concepts/layer/implementation/ssp/_index.md Outdated Show resolved Hide resolved

david-waltermire approved these changes Mar 17, 2022

View reviewed changes

david-waltermire requested a review from aj-stein-nist March 17, 2022 18:11

aj-stein-nist mentioned this pull request Mar 17, 2022

Style Guide for OSCAL Documentation #1185

Open

3 tasks

aj-stein-nist approved these changes Mar 17, 2022

View reviewed changes

david-waltermire suggested changes Mar 18, 2022

View reviewed changes

david-waltermire force-pushed the release-1.0 branch from 7ff253c to b0573ee Compare March 18, 2022 19:41

david-waltermire self-requested a review April 28, 2022 18:24

david-waltermire added this to the OSCAL 1.0.3 milestone Apr 28, 2022

wendellpiez reviewed Apr 28, 2022

View reviewed changes

david-waltermire force-pushed the 1062-ssp-link-semantics branch from 8472a99 to c224ccc Compare April 28, 2022 21:38

iMichaela reviewed Apr 29, 2022

View reviewed changes

david-waltermire reviewed Apr 29, 2022

View reviewed changes

docs/content/concepts/layer/implementation/ssp/_index.md Outdated Show resolved Hide resolved

david-waltermire reviewed Apr 29, 2022

View reviewed changes

docs/content/concepts/layer/implementation/ssp/_index.md Outdated Show resolved Hide resolved

david-waltermire reviewed Apr 29, 2022

View reviewed changes

docs/content/concepts/layer/implementation/ssp/_index.md Outdated Show resolved Hide resolved

david-waltermire reviewed Apr 29, 2022

View reviewed changes

Rene2mt requested review from david-waltermire, iMichaela and wendellpiez May 3, 2022 03:02

Rene Tshiteya and others added 12 commits May 4, 2022 19:08

Update SSP concepts page

8c8bb6a

Apply suggestions from code review

c7eb5ea

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

Update docs/content/concepts/layer/implementation/ssp/_index.md

a2767cd

Apply suggestions from code review

bf8fc77

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

WIP upddate ssp page

a23c176

Fix broken link

97bb772

Fix bad anchor

537e887

Remove compile/runtime validation descriptions

04290c9

Co-authored-by: David Waltermire <david.waltermire@nist.gov>

Remove compile time validation description

984bb22

Co-authored-by: David Waltermire <david.waltermire@nist.gov>

Update leveraged authorization link description

c9b47fa

Co-authored-by: David Waltermire <david.waltermire@nist.gov>

Clarify link semantics in SSP model

7baf5d6

Some refinements to the reference table

655c35a

david-waltermire force-pushed the 1062-ssp-link-semantics branch from e9697b4 to 655c35a Compare May 4, 2022 23:09

fixing broken link

9405f94

david-waltermire approved these changes May 4, 2022

View reviewed changes

david-waltermire merged commit 2908e46 into usnistgov:release-1.0 May 4, 2022


		### Identifier References

		An OSCAL SSP may contain references to information that is defined locally (e.g., in the SSP model) or externally (e.g., in a referenced profile, catalog, or component definition model). The following lists the mechanisms through which objects in an OSCAL SSP may "link" to other OSCAL content:


		An OSCAL SSP may contain references to information that is defined locally (e.g., in the SSP model) or externally (e.g., in a referenced profile, catalog, or component definition model). The following lists the mechanisms through which objects in an OSCAL SSP may "link" to other OSCAL content:

		- Local: Scenario where an identifier references information in the same OSCAL instance. This scenario supports “compile time” enforcement of constraints since the validity of the reference can be checked as soon as the SSP is authored.


		The following table summarizes constraints for identifier references in an OSCAL SSP:

		\| Reference \| Target Scope \| Target Element \| Target ID Type \| Referential Constraint Description \|

Conversation

Rene2mt commented Mar 11, 2022

Committer Notes

All Submissions:

Changes to Core Features:

Uh oh!

aj-stein-nist left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

aj-stein-nist commented Mar 17, 2022

Uh oh!

Rene2mt commented Mar 17, 2022

Uh oh!

Uh oh!

david-waltermire left a comment

Choose a reason for hiding this comment

Uh oh!

aj-stein-nist left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

david-waltermire left a comment

Choose a reason for hiding this comment

Uh oh!

Rene2mt commented Mar 24, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

wendellpiez Apr 28, 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!

Rene2mt May 3, 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!

david-waltermire commented Apr 28, 2022

Uh oh!

iMichaela Apr 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!

david-waltermire Apr 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!

Rene2mt May 3, 2022

Choose a reason for hiding this comment

Uh oh!

iMichaela Apr 29, 2022

Choose a reason for hiding this comment

Uh oh!

david-waltermire Apr 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!

Rene2mt May 3, 2022

Choose a reason for hiding this comment

Uh oh!

iMichaela Apr 29, 2022

Choose a reason for hiding this comment

Uh oh!

Rene2mt May 3, 2022

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

david-waltermire Apr 29, 2022

Choose a reason for hiding this comment

Uh oh!

Rene2mt May 3, 2022

Choose a reason for hiding this comment

Rene2mt commented Mar 24, 2022 •

edited

Loading

wendellpiez Apr 28, 2022 •

edited

Loading

Rene2mt May 3, 2022 •

edited

Loading

iMichaela Apr 29, 2022 •

edited

Loading

david-waltermire Apr 29, 2022 •

edited

Loading

david-waltermire Apr 29, 2022 •

edited

Loading