Create XML and JSON code examples for all commonly used OSCAL catalog and profile features

[akarmel]

User Story:

As an OSCAL consumer, I have access to XML and JSON code examples for all commonly used OSCAL catalog and profile features.

Goals:

• Create XML and JSON code examples (@anweiss @wendellpiez)
• Link code examples to pages.nist.gov/OSCAL (@kscarf1)
• Code examples are usable for regression testing against OSCAL schemas (None)

Dependencies:

None.

Acceptance Criteria

• Ensure clear, concise, simple XML and JSON code examples exist for features used in 800.53 catalog and baselines
• Code examples are linked to pages.nist.gov/OSCAL

[wendellpiez]

A lower-overhead, lower-maintenance approach to this would be to maintain a canonical set of complete examples, include them in regression testing (to guard against obsolescence), and point into them from the documentation for code examples.

However, this doesn't necessarily meet the requirements for display / integration into the docs. Would like some clarification as to what those are.

[wendellpiez]

4/26/2018 - Sprint 10 Progress Report

GOAL: 1/all

PROGRESS TO DATE: Some groundwork, that is all

PERCENTAGE COMPLETE: 0%

OUTSTANDING ISSUES:

1. For examples, we require a stable and correct data set. This must be either fictional, or real. Real data (for now) presumably depends on Cleanup NIST SP800-53 R4 catalog and low/moderate/high profiles #143 especially. Fictional data needs to be produced by someone.
2. On the JSON side, this is complicated if the JSON format itself is not yet stable cf Merge changes into Sprint 9 #145.
3. Even on the XML side, how these examples are to be maintained in the docs, is tbd. Presumably the fastest way to get something in there is to include literal code samples in the markdown. As a stopgap, these could be manually copied from extant examples and maintained by hand. This fails to address Goal 3, but it means we can skip the engineering for now -- plus, producing a handmade mockup is a solid first step toward Goal 3 anyway.

If we take the approach "Karen does it by hand" to no 3 here, then she could proceed (with help and guidance from me) if only she knows where to go for examples (no 1). Need to discuss w/ @kscarf1, @david-waltermire-nist and @anweiss.

[wendellpiez]

As soon as SP800-53 data is cleared cf #143, that can be an input here.

[david-waltermire]

@wendellpiez @kscarf1 Since these examples are intended to support the pages.nist.gov documentation, I'd like the examples to be simple and synthetic. Each example should be sufficient to demonstrate the use of each element/object in the respective XML and JSON models. I am good with @kscarf1 creating the examples. What we need to work out is a way to validate the examples to make sure they align with the model, and a method to insert them into the documentation pages.

[kscarf1]

5/17/2018 - Sprint 10 Progress Report

Goal: Create XML and JSON code examples
Progress: I have written several synthetic XML catalog code examples and provided these to Dave and Wendell for feedback. I expect to complete the examples for the XML catalog and profile schemas during this sprint.
% Complete: 15%
Open Issues: None

[kscarf1]

5/24/2018 - Sprint 10 Progress Report

Goal: Create XML and JSON code examples
Progress: I have drafted XML examples for most catalog elements in the schema documentation, and a few of the profile elements.
% Complete: 30%
Open Issues: Will need this work to carry this forward to another sprint.

[wendellpiez]

5/24/2018 - Sprint 10 Progress Report

Meanwhile I have been working on the metaschema tech, one goal of which (external to Issue #125) is integrating the tagged examples into the docs, to facilitate both correctness (including validation) and maintenance. There are actually three different approaches to maintenance (on the XML side) that we can discuss: inline escaped XML (what we now have); inline XML; and pointers to out-of-line XML. Depending on our choice we have different choices on the JSON side. We could do any or all.

[anweiss]

June 21 Status: Updated 800-53 catalog and profile JSON examples are up in PR #195. Updated FedRAMP profile JSON examples have yet to be pushed (dependent on #144).

[anweiss]

August 9 Status: This is dependent on refinements to the metaschema to clean up JSON schema and documentation outputs per #186 and #202.

[iMichaela]

Status Meeting: 8/23/2018

@anweiss will take a lead in addressing it.

[iMichaela]

8/30/2018 Status Meeting

@anweiss suggests we should focus more on the metaschema (new ticket to be created by @anweiss) to automatically translate the examples from XML to JSON. @anweiss and @wendellpiez and @david-waltermire-nist will continue working on it.

[anweiss]

09/27/2018

Discussed metaschema nuances with @wendellpiez. Refactoring oscalkit to automatically generate its own types based on the metaschema. This will enable oscalkit to generate code examples per the requirements of this issue; in addition to the XSLT being crafted to do the same.

[david-waltermire]

@anweiss What is the status of this issue?

[anweiss]

@david-waltermire-nist it's been quite a while since I looked at this issue. However, @smichelotti and his team might have some samples that may shareable.

[david-waltermire]

This is being addressed by #592 and #593. Closing.