The JSON schema should not require 2 items for Array notation

[trevor-vaughan]

Describe the bug

While developing a component JSON file, I found that editing was made difficult due to the schema requiring two items for Array notation.

This meant that refactoring was made more difficult when I went down to a single item in the Array and then failed schema validation. Allowing Array notation for any number of items would be ideal for ease of use.

Who is the bug affecting?

JSON file content creators.

What is affected by this bug?

Schema validation and refactoring in a timely manner.

[david-waltermire]

I don't think this is a bug, as this is an intentional design feature. Changing this issue to an enhancement request instead.

We use a convention in JSON for multi-object property values that allows a single object to be used for a singleton, and an array to be used for when two or more objects are proved. The JSON schema instances for the OSCAL models enforce this. This is parsing logic supported by many commodity JSON parsers.

If we relaxed the above by allowing an array containing a single value, then a parser would face two possibilities for a singleton object value. 1) a singleton object, or 2) an array containing a single object. This complicates parsing more than the current state.

@trevor-vaughan Can you live with the existing behavior?

[smichelotti]

I'd actually like to go one step further than @trevor-vaughan and propose that object syntax not be allowed at all. This is causing major headaches for us.

Let's take a concrete example: the profile imports property. In the NIST SP 800-53 profiles, this is an object and in the FedRAMP profiles this is an array. This is forcing us to litter our code with IF statements like this:

if (_.isArray(this.profile.imports)) {
  _.forEach(this.profile.imports, i => this.doSomething(i));
} else {
  this.doSomething(this.profile.imports);
}

We have the exact same problem with the controls property of the groups in the catalog document.

catalog.groups[i].controls //<- at run-time need to check if this is object or array

This is a problem both for server-side languages (e.g., C#) as well as in the browser (JavaScript).

I see theoretical discussion about JSON parsers above, but I'm struggling to understand a concrete Use Case where the current behavior is desirable or advantageous. Would like to explore if this can be changed, or understand if there is a better suggestion for developers handling this than the type of IF statements identified above.

[david-waltermire]

@smichelotti This was a requested optimization to make the JSON more concise. As you point out, this is at the cost of implementation complexity and as @trevor-vaughan has pointed out can cause problems with hand-editing. Given these factors it might be good to change to consistent use of arrays. I plan to bring this up on the next lunch with the devs to get more input and gauge consensus before we make a decision.

[wendellpiez]

@david-waltermire-nist as I understand it, removing in-json='SINGLETON_OR_ARRAY" from the OSCAL metaschemas will address this issue in OSCAL.

However, it also applies to other schemas defined by Metaschema, and I am now looking at this part of the code. (usnistgov/metaschema#39)

Should I relax the rule that an assembly defined as "SINGLETON_OR_ARRAY" must require two members as an array? (Should it require any?) This issue is likely to come up again for anyone trying to use this feature....

[david-waltermire]

Yes. PR #627 removes the use of the single object for multivalued arrays with a single instance. Arrays will be consistently used. I hope to merge this PR by CoB Wednesday.

[wendellpiez]

Cool. In order to forestall the issue coming up again in a future (Metaschema application) context, I will (also) adjust the JSON Schema production as @trevor-vaughan requests here.

[smichelotti]

@david-waltermire-nist you mentioned were you hoping to merge this PR by CoB Wednesday - any update on status? We're actively waiting on this merge. Thanks.

[SParekh]

@david-waltermire-nist /content/fedramp.gov/json/FedRAMP_catalog.json still has old schema