Current OSCAL model documentation approaches are suboptimal

[aj-stein-gsa]

Risk Summary

As it stands, NIST and FedRAMP have an ever-increasing quantity of documentation for OSCAL model information and the constraints that enforce them.

Below summarize the current NIST and FedRAMP approach at the time of this writing.

1. The current NIST approach is to embed the OSCAL documentation directly into source Metaschema files and use the metaschema-xslt project to process the model assemblies, fields, flags, and their relationships to generate HTML that can inserted into a static site generator. This approach can reduce scaling issues, but there are longstanding bugs, especially around more complex completeness and integrity checks with constraints that are not immediately inlined, that lead to documentation errors with missing or incorrect data. One such prominent example is Incorrect Allowed @name values for @prop in documentation  usnistgov/OSCAL#1972.
2. FedRAMP currently generates their extension and model-specific documentation manually with developers updating the Markdown prose and embedded OSCAL content in code fence blocks on a case by case basis in the automate.fedramp.gov repository. Although it does not scale as well as NIST's current approach in 1, fixing more systemic issues with Metaschema processing and automated documentation generation facing 1 do not pose the same risks with complexity and resource requirements. The manual effort still requires significant resources.

FedRAMP staff are cognizant that a new alternate approach, transitioning from 2 to an automated approach like 1 but with a different architecture and design, could vastly improve the process of documentation maintenance.

Risk Mitigation Strategy

Strategy: Accept

At this time, the FedRAMP Automation Team is accepting this risk until achieving key milestones in constraint development and goals in the Digital Authorization Pilot before revisiting a different mitigation strategy.