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

[david-waltermire]

User Story:

As an OSCAL content creator or tool developer, I need to understand what behavior a tool should exhibit when encountering conflicting role, location, party, and reference definitions with the same identifier.

For example:

An OSCAL SSP might define:

--- 
system-security-plan:
  uuid: ...
  metadata:
    …
    roles:
    - id: custom-role-id
    - title: Custom Role
--- 

An OSCAL assessment plan might define:

--- 
assessment-plan:
  uuid: ...
  metadata:
    …
    roles:
    - id: custom-role-id
    - title: Adjusted Custom Role
  import-ssp:
    href: link-to-ssp

What is the correct behavior?

Goals:

• Document correct behavior in OSCAL model documentation
  • Write general documentation in the "concepts" section of the website
  • Integrate general documentation as links in relevant model documentation
• Define follow-on issue(s) for implementing this using constraints to consistently enforce the best-practices.

Dependencies:

None.

Acceptance Criteria

• All OSCAL website and readme documentation affected by the changes in this issue have been updated. Changes to the OSCAL website can be made in the docs/content directory of your branch.
• A Pull Request (PR) is submitted that fully addresses the goals of this User Story. This issue is referenced in the PR.
• The CI-CD build process runs without any reported errors on the PR. This can be confirmed by reviewing that all checks have passed in the PR.

[david-waltermire]

This was discussed during the 5/27 model review. @david-waltermire-nist presented slides identifying possible options. There was a consensus around option 4, which is to disallow identifier clashes in content both importing a role from another OSCAL document and defining a role with the same identifier. These cases should result in a content validation error.

Documentation needs to be updated to make this default behavior more clear. Metaschema constraints need to be developed to enforce these errors. This work will be completed as part of #1066 (PR #1263).

There was also discussion around identifying a policy-driven behavior that could be used to allow other behavioral options to be "turned on". This will be explored separately as an additional feature in a future revision of OSCAL.

[aj-stein-nist]

As Dave rolled off the project, we will move this to the next sprint and one of us will take it on.