Generation of format specific model maps from Metaschema instances

[david-waltermire]

User Story:

As an OSCAL content creator or tool developer, I need to be able to quickly find documentation for the OSCAL model I am using.

Goals:

The Metaschema-based schema generation pipeline provides schema documentation for users; however, unless the user knows exactly what to look for by name, the navigation is less than useful. Instead, it would be useful to provide a format-specific map that shows all of the supported model objects for each model and format.

The XML model could look like this:

<profile id="string">
   <metadata>
      <title>simple-markdown</title>
      <last-modified-date>date-time</last-modified-date>
      <version>string</version>
      <oscal-version>string</oscal-version>
      <role id="ncname">
        <title>simple-markdown</title>
      </role>
   </metadata>
   <import href="uri">
      <include>
         <call control-id="id"/>
         <call subcontrol-id="id"/>
      </include>
   </import>
   <merge>
      <as-is>boolean</as-is>
   </merge>
   <modify>
      <alter control-id="id">
         <add position="string">
            <prop name="ncname">string</prop>
         </add>
      </alter>
   </modify>
   <back-matter>
      <resource id="id">
         <desc>string</desc>
         <rlink href="uri" media-type="string"/>
      </resource>
   </back-matter>
</profile>

While the JSON model might look like this:

{
  "profile": {
    "id": "string",
    "metadata": {
      "title": "simple-markdown",
      "last-modified-date": "date-time",
      "version": "string",
      "oscal-version": "string",
      "roles": [
        {
          "id": "string",
          "title": "string"
        },
      ],
    },
    "imports": {
      "href": "uri",
      "include": {
        "id-selectors": [
          { "control-id": "ncname" },
          { "subcontrol-id": "ncname" }
        ]
      }
    },
    "merge": {
      "as-is": boolean
    },
    "modify": {
      "alterations": [
        {
          "control-id": "ncname",
          "additions": {
            "position": "string",
            "properties": {
              "name": "ncname",
              "priority": "string"
            }
          }
        }
      ]
    },
    "back-matter": {
      "resources": {
        "id": "ncname",
        "desc": "string",
        "rlinks": {
          "href": "uri",
          "media-type": "string"
        }
      }
    }
  }
}

In each case the element, attribute, or item name would provide a link to the corresponding documentation for that object.

These "model maps" should be generated during the schema documentation generation process as seperate web pages. These pages can then be linked to by each respective schema documentation page. They can also be added as subnavs on the left navigation.

Dependencies:

Issue #337 provides some early design for this feature.

Acceptance Criteria

• All generated XML and JSON schema documentation created by the CI/CD pipeline include a link to their respective model map, which is also generated by the same pipeline.
• A single PR is approved that contains the above changes.

[wendellpiez]

Now in PR #450.

[david-waltermire]

This has been completed in PR #464.