Parameter insertion JSON template syntax

[anweiss]

User Story:

As an OSCAL producer, I can leverage a pre-defined template syntax for embedding parameter values into JSON-formatted OSCAL artifacts. This syntax would be analagous to the existing <insert param-id="paramId"/> inline element construct currently used in XML prose. As an OSCAL consumer, I can interpret, both pre-processed and post-processed, JSON-formatted OSCAL artifacts with parameters that are inserted using this syntax. Pre-processed artifacts would contain raw template text and post-processed artifacts are those whose template syntax has been parsed and substituted with the actual values referenced by the block.

The idea would be to take a condensed subset of existing template languages (e.g. Jinja, Handlebars, Go, etc), and allow for it to be used for parameter insertion in JSON. If warranted, this could also be extended to enable co-occurrence constraints via expressions and conditionals, and other capabilities deemed applicable; albeit not required for acceptance of this user story.

Goals:

Parameter insertion in JSON cannot work the same way as it does in XML with inline elements. Instead, prose in JSON can only be a JSON string type, where special characters are appropriately escaped. The goal of this issue is to document in the metaschema a solution for embedding parameters into JSON-equivalent prose strings and that which can be used to cross-reference parameters in the same (or external) JSON-formatted OSCAL artifact. (@wendellpiez @anweiss)

Dependencies:

Can be done in parallel to #125, #193, #186, and #153.

Acceptance Criteria

An appropriate template syntax has been agreed upon, has been documented in the metaschema, and can be used to cross-reference and insert parameters into JSON-equivalent prose strings. Furthermore, when a set of parameter data is provided, the proposed syntax is processed and the actual values are inserted into the final artifact.

[anweiss]

A simplistic approach would be to support JSON Pointer (RFC 6901) surrounded by double curly braces. For example:

{
  "params": {
    "param4": {
      "value": "paramValue"
    }
  },
  "parts": {
    "part5": {
      "prose": "Some prose with parameter {{ #/params/param4/value }}"
    }
  }
}

#/params/param4/value is a JSON pointer that references the string "paramValue" in the same document. This could be condensed in a few ways too by making the fragment identifier, #, and/or the params/ and value/ accessors implicit (which assumes params is in the same JSON document and adheres to the parameter data model). {{ #/params/param4/value }} would simply become {{ param4 }}

Another approach could be to use a dot/bracket notation accessor syntax which is common amongst the various template languages that are out there. It is also the native mechanism for accessing object properties and their values in JavaScript. For example:

{
  "params": {
    "param4": {
      "value": "paramValue"
    }
  },
  "parts": {
    "part5": {
      "prose": "Some prose with parameter {{ .params.param4.value }}"
    }
  }
}

{{ .params.param4.value }} would reference the current document's params object, and subsequently its param4 object; thereby returning the "paramValue" string from its value key.

Bracket notation could also be supported as follows: {{ .params["param4"]["value"] }}.

Assuming that this syntax only applies to the params object and associated data model, the .params accessor could even be made implicit as such: {{ .param4.value }}. Condensing this even further with an implicit value accessor would result in: {{ .param4 }} or simply {{ param4 }}.

[wendellpiez]

Andrew, this is pretty sweet.

Syntactically, the mapping to XML (where we have <insert param-id='param4'/>) is one-to-one (since param-id is the only attribute permitted on the element). Whether it's the declared or assigned value that comes back from the call, or something else, I think should be up to the application.

But note how this means also that there will be strong dependencies on validation, for example we will really have to validate the uniqueness (across catalog scope) of those id values @anweiss !

[wendellpiez]

Sprint 11 Progress June 7 2018

This issue depends on #186. Conversion from the XML syntax to the embedded-in-JSON syntax is straightforward. The conversion the other way will be part of the mardown->XML conversion that will be needed to support (complete) conversion back into XML.

Progress to date: design 100% (see above); implementation 0%

[david-waltermire]

While not specific to this issue, some early thoughts on HTML/markdown translation are here: https://github.com/usnistgov/OSCAL/blob/master/docs/schema/html-markdown-format-mapping.md.

[anweiss]

Flagging related issue #200

[anweiss]

June 21 Status: The discussions in #200 will result in a foundation on which this particular issue can be addressed.

[david-waltermire]

6/21/2018 Status

• Need to document this approach as part of the larger JSON/Markdown syntax (Define an allowable subset of markdown syntax for prose #200).
• Consensus is around using the {{ param4 }} form. Need to document how to use this form and how to escape the "{{" characters when this literal string needs to appear in text.

[iMichaela]

June 28 Status Meeting Update

This will be discussed again during the June 29 meeting. A decision will be made then.

[anweiss]

August 9 Status: No updates. This is still dependent on #224.

[iMichaela]

Status Meeting: 8/23/2018

No updates. This is still dependent on #224

[iMichaela]

Status Meeting: 8/30/2018

No updates. This is still dependent on #224

[anweiss]

09/27/2018

No updates at this point. This will be addressed by ongoing fine-tuning of the metaschema.

[david-waltermire]

@anweiss and @wendellpiez Is JSON parameter insertion on par with XML? Has this been addressed fully?

[wendellpiez]

I believe we are aligned for now. Parameter insertion points should be included in our testing for #283 and #343 (XML/JSON bidirectional conversion).

{{ param.id }}

where param.id is the identifier of the parameter whose value is to be provided.

To escape: represent one or both braces as \{ or \}\ to be documented in the coverage of OSCAL Markdown.

If this looks good I propose that when we close #343 we consider this one closable as well. To capture the documentation requirement, I have made #357.

[david-waltermire]

This has been completed. Follow-on issues have been created.