Rename JSON customization elements in the Metaschema

[david-waltermire]

User Story:

As an OSCAL model developer, I need to be able to customize the JSON model to produce more concise JSONbased on my Metaschema-based model.

Goals:

There are two major goals in this issue:

• In previous work, the key and value-key elements were added to the Metaschema. These elements drive customization of the resulting JSON models. Since these customizations are specific to JSON, the elements need to be renamed to json-key and json-value-key respectively. This change will require updates to the Metaschema schema, and to the schema generation, content converter generation, and documentation generation XSLTs.
• Although the json-key and json-value-key elements have been added to the Metaschema. Their use has not been documented in the Metaschema documentation. The use of these elements needs to be documented there.

Dependencies:

None.

Acceptance Criteria

• All generated XML and JSON schema are updated to reflect these changes. Content instances are checked by the CI/CD workflow.
• XML and JSON documentation generated by the CI/CD workflow correctly represents the use of json-key and json-value-key defined by the Metaschema instances.
• The Metaschema definitions are updated in a way that result in no changes to associated content.
• Documentation on the use of Metaschema is updated to fully document use of the json-key and json-value-keyfeatures.
• A single PR is approved that contains the above changes.

[wendellpiez]

I very much think we should also consider refactoring the design, not only the names. I could sketch out one or two alternatives.

[wendellpiez]

Dynamic key assignment

This functionality makes it possible to use a dynamic value as the key of a JSON object, with the result that an object can be promoted from an (unlabeled) member of an array, to be an object (or string) with the given value as its label (key). This implies that key values are unique within the scope of the parent, a constraint that can be validated in XSD and JSON Schema, or via Schematron.

Design A.

<define-assembly name="param" json-key-flag="id">
  <flag name="id" datatype="ID" required="yes"/>

Works on either field or assembly. Has the effect of assigning the 'name' flag the role of the key in the JSON, Validation must ensure that such name values as represented in the XML are distinct. The Metaschema is validated to see to it that the value of Metaschema define-field/@json-key matches the name of a required flag on the same field or assembly.

Design B.

<define-assembly name="param">
  <flag name="id" datatype="ID" required="yes" role="json-key"/>

(@role can be named something else.)

Dynamic value-key functionality

Permits assigning a flag to carry a dynamic label for the field value in the JSON.

Example in XML

<prop name="status">DRAFT</prop>

Example in JSON with no value key:

{"name": "status",
 "STRVALUE": "DRAFT" }

Example with 'name' flag assigned as JSON value key:

{"status": "DRAFT" }

Design C

<define-field name="prop" as-type="simple-markup" json-value-key-flag="name">
  <flag name="name" required="yes"/>

Design D

<define-field name="prop" as-type="simple-markup">
  <flag name="name" required="yes" role="json-value-key"/>

Static value-key assignment

Instead of designating a flag to carry the value key, a literal value key is assigned. This literal will be used to replace the fallback key value (label) on JSON strings representing (unlabeled) element values in the XML.

This enables the assignment of a flag to carry, in the data, the value that will serve as the key of the string (or markup) value of a field. So it may not be used on assemblies.

Design E (parallels A and C)

<define-field name="prop" as-type="simple-markup" json-value-key-literal="property-value">
  <flag name="name" required="yes"/>

Design F

A design to go with B and D instead of A and C could look like E, except with a shorter name:

<define-field name="prop" as-type="simple-markup" json-value-key="property-value">
  <flag name="name" required="yes"/>

Example from above, except with this feature:

{"name": "status",
 "property-value": "DRAFT" }

In this case, validation must ensure not that the @name value is unique and exclusive of other flag names, but only that the literal value designated does not clash with a declared flag name. So Metaschema validation and not instance validation would suffice.

[david-waltermire]

@wendellpiez I don't see any rationale as to why we need to change the overall construction of these features. Honestly, I prefer the original construction, since the markup is oriented relative to the subject that is being customized.

Dynamic key assignment

Given the following construction:

<define-assembly name="set" group-as="settings">
  <json-key flag-name="param-id"/>
  <flag name="param-id" datatype="NCName"/>
  ...
</define-assembly>

And the XML:

<set param-id="param1">
  ... set contents ...
</set>

The resulting JSON would be:

{
  "param1": {
    ... set contents ...
}

Use of <json-key/> as above is justified, since the json-key modifies (and promotes) the flag param-id for the object. Using an attribute on the assembly, such as what is described in "design A", does not use a child element to describe the customization, which I don't like very much. I also don't like @role="json-key", as describe in "design B", as this form is less descriptive, IMHO. As a matter of practice, I'd like all of the format-specific customizations to be child elements of the object being customized.

Dynamic value-key functionality

Given the XML:

<prop name="status">DRAFT</prop>

The default behavior produces the following JSON:

{"name": "status",
 "STRVALUE": "DRAFT" }

My preference is to use the define-field construction:

<define-field name="prop" as-type="simple-markup">
  <json-value-key flag-id="name"/>
  <flag name="name" required="yes">
</define-field>

Which would result in the JSON:

{"status": "DRAFT" }

I prefer this construction over "design C", since this customization modifies the behavior of how to render the field's value in JSON. As a result, the cusomization should be a child of the field. I don't like "design D" for the same reason.

Static value-key assignment

Keeping with the previous constructions, my preference would be for the following to handle the static label case:

<define-field name="link" group-as="links" as="mixed">
  <json-value-key>text</value-key>
</define-field>

Given the XML:

<link>The quick brown fox...</link>

This would result in the following JSON:

{"text": "The quick brown fox..." }

Again, in this case we are modifying the behavior of how to render the field's value in JSON. As a result, the cusomization should be a child of the field. I don't like "design E" or "design F" for the same rationele as above.

[iMichaela]

7/11/2019

This issue and the related ones (noted in #435 ) for the metaschema need to be reviewed together and unitested. However more unit tests need to be created for the other features.

[david-waltermire]

@wendellpiez thinks there might be a bug still in the json-value-key functionality. We need to create a unit test with a pathological example and then fix this issue if it exists.

[david-waltermire]

This has been completed in PR #464.