Allow Metaschema remarks to target one or more formats

[david-waltermire]

User Story:

As an OSCAL model developer, I need to be able to target documentation to a specific resulting data model (e.g., XML, JSON) to discuss data model specific considerations.

Goals:

The Metaschema allows for documentation to be described as part of the a given Metaschema using the remark element.

For example:

<define-field name="title" as="mixed">
  <formal-name>Title</formal-name>
  <description>A title for display and navigation.</description>
  <remarks>
    <p>A title for the containing object as it should appear in a formatted document.</p>
  </remarks>
</define-field>

It would be useful to target a remark to a specific data model format.

For example:

<define-field name="title" as="mixed">
  <formal-name>Title</formal-name>
  <description>A title for display and navigation.</description>
  <remarks format="xml">
    <p>This is an XML remark.</p>
  </remarks>
  <remarks format="json">
    <p>This is a JSON remark.</p>
  </remarks>
  <remarks format="yaml">
    <p>This is a YAML remark.</p>
  </remarks>
</define-field>

The Metaschema schema, and schema and document generation processes needs to be updated to support this.

Dependencies:

This issue will also partially address issue #390, by providing for validation of valid values.

Acceptance Criteria

• All generated XML and JSON schema include the documentation targeted at them.
• All generated XML and JSON website documentation include the documentation targeted at them.
• Documentation on the use of Metaschema is updated to fully document this feature.
• A single PR is approved that contains the above changes.

[david-waltermire]

@wendellpiez I don't know of a good way to verify that this is working. Any ideas?

[wendellpiez]

The best way to confirm this is to try it out. We could do that in the lab.

One way to approach this would be to tie it to Issue #478, where we are reviewing the current models. There, we could find a use case where we could actually take advantage of this feature.

But we also have to document this. Which raises the larger question of documenting Metaschema in general. Possibly that warrants an entire Issue of its own.