Merge Citation with Resource in Back Matter

[brian-ruf]

User Story:

This was discussed in #587. Opening a separate issue to provide better transparency and tracking.

As an OSCAL content creator, I find citation and resource to be similar enough that they can be merged into a single assembly.

Goals:

Simplify the OSCAL syntax by expanding the resource assembly, such that it can also serve to capture citations, thus eliminating the need for a separate citation assembly.

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.
• I am able to model citations using the resource assembly.

[brian-ruf]

Examples from FedRAMP

To meet FedRAMP's needs, I added extensions to citation and resource. Some may be useful as we merge these two assemblies.

To citation, I added the following prop name="" extensions:

• publication: Publication date
• version: Version number
• type: Document Type (law, regulation, standard, guidance, pii)

The above enabled me to fully model SSP Table 12-1 Laws and Regulations, as well as SSP Table 12-2 Standards and Guidance. Both tables have the following columns:

• Identification Number
• Title
• Date
• Link

To resource I added the following prop name="" extensions:

• title: Document Title
• publication: Publication date
• version: Version number
• type: Document Type (policy, procedure, guide, pia, rob, plan)

This enabled me to fully address various attachments needs for FedRAMP. For example, multiple policies are typically attached, and it helpful to differentiate policy attachments from other attachments when reviewing. Likewise for procedures and plans.

If we were to merge

Title already existed in citation. I needed to add it to resource.
The other three extensions are identical for both (version, publication, and type).

Recommendation

I believe a complete OSCAL resource assembly (after merging with citation) should look something like this:

<resource id="NCName">
   <title>markup-line</title> [0 or 1]
   <published>dateTime-with-timezone</published> [0 or 1]
   <version>string</version> [0 or 1]
   <descr>string</desc> [0 or 1]
   <doc-id type="string">string</doc-id> [0 to ∞]
   <prop name="NCName" id="NCName" ns="string" class="NCName">string</prop> [0 to ∞]
   <rlink href="uri-reference" media-type="string"> [0 to ∞]
      <hash algorithm="string">string</hash> [0 to ∞]
   </rlink>
   <base64 filename="uri-reference" media-type="string">base64Binary</base64> [0 or 1]
   <remarks>Markup multiline</remarks> [0 or 1]
</resource>

[brian-ruf]

30-Jan-2020 Status

Metaschema updated in @david-waltermire-nist branch.
@wendellpiez will need to address data alignment issues before this can be pulled and merged.

[wendellpiez]

Work to consolidate the models is almost but not quite complete:

• back-matter still permits citation, although the latter has been remodeled to work instead in the context of resource (which now also permits it)
• It also still has an id flag, implying it should be addressable on its own
• But citation without resource has no way to capture a link without going into the 'any' extension

If citation is to be permitted outside resource maybe it needs an href or target after all.

Alternatively, if it is not to be permitted outside resource, we should remove it from back-matter, and probably also remove its id flag.

For now, I am assuming the latter as I think that is in line with yesterday's work.

Yet I also note that the data will be more heavyweight if every citation is also wrapped as a resource. If this seems like a problem we should revisit. Will discuss with @david-waltermire-nist.

[david-waltermire]

This is addressed by PR #619.