-
Notifications
You must be signed in to change notification settings - Fork 180
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.
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
1062 ssp link semantics #1167
1062 ssp link semantics #1167
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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. 😆
fa417f6
to
e422a05
Compare
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 We still have some outstanding feedback. Can we talk about it later today? |
Yes, we can go over feedback later today. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This looks good. Thanks!
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
7ff253c
to
b0573ee
Compare
Agreed. Latest WIP commit made the following changes
We can do another round of review on these latest updates. |
|
||
- **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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Reworked this section, removing un-necessary hyphens and capitalization. Created subsection headers for instance, cross instance, and external with narrative scenario descriptions.
8472a99
to
c224ccc
Compare
@Rene2mt I just rebased this onto |
@@ -66,6 +66,46 @@ The figure below expresses represents the portion of the OSCAL stack as it relat | |||
|
|||
{{<partialCached "note-to-developers-uuid.html" >}} | |||
|
|||
### 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: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The locally defined references reside in OSCAL SSP content or Catalog/Profile/CDef content, and not in the mentioned models).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Use instance vs cross-instance terminology from the identifier scoping instead of "locally", etc.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
|
||
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Created subsection headers for instance, cross instance, and external with narrative scenario descriptions.
| [responsible-party/party-uuid](/reference/latest/system-security-plan/xml-index/#/party-uuid) | Local SSP | Party | UUID | A single target party must be found in the source. System-characteristics/responsible-party/party-uuid and inventory-item\*/responsible-party/party-uuid are the points of reference, so they are appropriate to enforce a local constraint. | | ||
| [responsible-role/@role-id](/reference/latest/system-security-plan/xml-index/#/@role-id) | Local SSP, leveraged-authorization | Role | Token | A single target role must be found by the ID. | | ||
| [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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
OSCAL is designed to allow the capture of relevant ...
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Fixed
|
||
The following table summarizes constraints for identifier references in an OSCAL SSP: | ||
|
||
| Reference | Target Scope | Target Element | Target ID Type | Referential Constraint Description | |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
In the table can you link to the data type definition? https://pages.nist.gov/OSCAL/reference/datatypes/
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Added
Co-authored-by: Alexander Stein <[email protected]>
Co-authored-by: Alexander Stein <[email protected]>
Co-authored-by: David Waltermire <[email protected]>
Co-authored-by: David Waltermire <[email protected]>
Co-authored-by: David Waltermire <[email protected]>
e9697b4
to
655c35a
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
LGTM. Thanks!
* Update SSP concepts page * Clarify link semantics in SSP model Co-authored-by: Alexander Stein <[email protected]> Co-authored-by: David Waltermire <[email protected]>
* Update SSP concepts page * Clarify link semantics in SSP model Co-authored-by: Alexander Stein <[email protected]> Co-authored-by: David Waltermire <[email protected]>
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:
Changes to Core Features: