Basic HTML rendering capability for catalogs and SSPs

[wendellpiez]

User Story:

As an OSCAL user, I need to be able to browse and review OSCAL catalog and SSP contents without having to look at code.

I need to do the same for profiles, but their close relation to catalogs makes them more problematic, so they are out of scope for this Issue. A tailored catalog that has been produced by resolving an OSCAL profile, however, is in scope, so profiles are included in that sense.

Goals:

A useful off-the-shelf piece of software that can convert OSCAL catalogs and SSPs into a browsable HTML version for proof and preview (not final production, 'publishing' or submission).

This software must meet the following requirements:

• The outputs are 'human readable' and intelligible, as OSCAL, to an informed OSCAL user, while also being reasonably legible to SMEs not comfortable with code (either syntax or any very specialized notation).
• The software operates on OSCAL generally: it makes minimal assumptions regarding source data beyond conformance to applicable schemas and documented constraints.
• In addition to delivering a passable preview rendering of OSCAL catalogs and SSPs, the software must be extensible and customizable to support local adaptation.
  • The HTML results work tolerably well in major current (maintained) browsers including Mozilla FF, Chrome, Safari, MS Edge.
  • (Optionally, for discussion) the software must be configurable with a runtime switch so that HTML can be provided with CSS either embedded in the file <style>, or externally by reference <link> to support external maintenance of CSS targeting the OSCAL-flavored HTML.
  • Otherwise, process outputs (HTML) are easy to package and move without breaking, with minimal dependency (ideally none) on linked resources - no external Javascript or images, only a single CSS when wanted (see previous items).

We focus on OSCAL XML for a pilot, with an XSLT implementation. We can consider a more direct JSON pathway once OSCAL semantics have stabilized further (in part, through this exercise).

In the best case, the HTML delivered by this transformation will be clean and well-tagged enough to serve as both an OSCAL (HTML) microformat for downstream processors, and the first step for more exacting rendering pathways including "production" outputs in PDF or other formats.

Dependencies:

More realistic sample data is probably called for, especially SSPs.

Additionally, we need a model for maintenance and extension of this capability, addressing longer-term strategic questions such as where this should be maintained (tools repo?), how its scope of development should be managed, and how both users and others including emulators can be supported.

Earlier XSLT stylesheets in the repo for rendering catalogs and profiles into HTML can be mined for useful templates.

The fact that models will also be changing introduces dependency on issues addressing modeling (especially SSP modeling) including usnistgov/OSCAL#478, usnistgov/OSCAL#498, usnistgov/OSCAL#535, usnistgov/OSCAL#568.

Acceptance Criteria

• [ ] One or more XSLT transformations have been developed that deliver functionality and address requirements as described above.
• [ ] Modular code supports sensible reuse across layers (e.g. consistent handling of metadata and back matter).
• [ ] Documentation (web site and/or readme files) has been provided describing both how to use the appliance, and how to extend it (XSLT+CSS and CSS only).
• [ ] 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.

[wendellpiez]

Sprint 26 Update Jan 30 2020

This Issue should probably be split into two, as work on the Catalog rendering is now near complete at least for demo purposes, while work on the SSP rendering (or any implementation layer) cannot proceed much further while those models (and examples) are soft.

The second issue -- generic implementation-layer handling -- is related to Issue usnistgov/oscal-xslt#10, which specifically targets a single SSP template.

The first issue regards both generic and NIST-emulation catalog rendering. Work proceeds in my branch here: https://github.com/wendellpiez/OSCAL/tree/publishing-v0dot1

It is now about feature complete, and requires only some more refactoring of interfaces for ease of use. Also documentation.

Additionally, to complete the work (including deploying the capability) there is a dependency on usnistgov/oscal-xslt#6

[wendellpiez]

usnistgov/OSCAL#630 now tracks work on the catalog side of this work item.

We still do not have a separate Issue for the (longer-term) Implementation Layer side (SSPs etc.)

[wendellpiez]

Since the catalog presentation logic is stable (see usnistgov/OSCAL#630), this Issue should be rewritten or replaced with one that scopes work only to the SSP.

Note that work for FedRAMP (see https://github.com/GSA/fedramp-automation) includes SSP rendering as well.

[aj-stein-nist]

Per discussion with the team today during backlog review, I am moving this to the appropriate repository per our guidance, oscal-xslt.