Clarification on JSON types

[awoie]

When implementing a JSON-based Data Model using JWT proofs, we have some issues that we want to clarify:

• Is the @context always an array, even with a single context?
• Is the type attribute always an array, even with a single type?
• Is the credentialSubject always an array, even with a single credentialSubject?
• Is the proof always an array, even with a single proof?
• ...

If one of the answers is no (and I believe so), then a considerable amount of extra processing is necessary because of the ambiguity of types.

I would suggest to have at least a non-normative statement that says that it is not recommended to use compact-form in order to be compliant with JSON processors.

[msporny]

Is the @context always an array, even with a single context?

No.

Is the type attribute always an array, even with a single type?

No.

Is the credentialSubject always an array, even with a single credentialSubject?

No.

Is the proof always an array, even with a single proof?

No.

then a considerable amount of extra processing is necessary

For some definition of "considerable". It's a one line function to convert a non-array value into an array such that you can process it as if the right hand side was always an array.

To put it another way, some developer out there will mess this up, so the safest/best thing to do is write the function to convert every right hand value into an array if it isn't already an array.

We should put non-normative text in to that effect into the spec. We could also put something in the implementation guide.

[mirceanis]

What is the purpose of adding this layer of implementation complexity?
In typed languages this becomes a burden and can easily introduce either bloatware or vulnerabilities.
it is not a just a one-line function. It's a whole library behind that one line.

[awoie]

@msporny IMO, we have to change the following note "For other processors, the only processing necessary is to ensure that the order of the values in @context is what is expected for the particular application, but no JSON-LD processing of those values is required.". We also have to mention something in "5.3.1 Semantic Interoperability".

Although the output is valid JSON, JSON processors would usually need extra processing for ambiguous types.

[dlongley]

@mirceanis,

In typed languages this becomes a burden and can easily introduce either bloatware or vulnerabilities.
It's a whole library behind that one line.

I think this is consolidated at the serialization layer -- which means that that library is a JSON parser. You'll need one anyway if you're using the JSON syntax (which is what this applies to). That parser will already have to know how to construct objects, arrays, and JSON natives in arbitrary locations. Once parsed from JSON, you can represent the result however you'd like, normalizing to arrays, for instance.

[mirceanis]

@dlongley

That parser will already have to know how to construct objects, arrays, and JSON natives in arbitrary locations.

Right, but usually those locations and types are expected to be known in advance, based on business logic context or a protocol, not be deduced from an input stream. I'm questioning the needless complication of having to deduce whether types are arrays or not based solely on the input stream.

[dlongley]

@mirceanis,

Right, but usually those locations and types are expected to be known in advance, based on business logic context or a protocol, not be deduced from an input stream.

Understood, but this puts us back at essentially a one line requirement, rather than at a library, where that library is already needed to parse the JSON.

I'm questioning the needless complication of having to deduce whether types are arrays or not based solely on the input stream.

As an example for why we're allowing differences, we're doing it for features and interop (wrt. a W3C Recommended syntax that provides decentralized extensibility and that expresses data on millions of websites). We consider it a very minor sacrifice (one liner) to enable this.

[mirceanis]

@dlongley even with a library it's usually not a oneliner to handle shifting data types.
If it is, please share (in something other than JS)

[dlongley]

@mirceanis, if there's a popular language in which you think it's difficult, please indicate which language.

[mirceanis]

How about a Java project using Moshi?
or a Kotlin project using kotlinx.serialization

[msporny]

Add non-normative text to the data serialization section clarifying that implementers should note that values associated with properties may either be single values or arrays and suggest some mitigation strategies that implementations can use.

[mirceanis]

If an implementor is expecting a field to be an array and in some cases it is not then their implementation will most likely crash or at best fail.
That means that the mitigation strategy MUST be used.
It doesn't sound like a non-normative issue anymore.

[RorschachRev]

For some definition of "considerable". It's a one line function to convert a non-array value into an array such that you can process it as if the right hand side was always an array.

In Javascript.

To put it another way, some developer out there will mess this up, so the safest/best thing to do is write the function to convert every right hand value into an array if it isn't already an array.

But there are many languages that will be implemented, and maintaining alternate data structures in multiple languages adds a lot of unnecessary complexity. What is the advantage in non array values? I see no advantage, and a lot of disadvantages.

[msporny]

But there are many languages that will be implemented, and maintaining alternate data structures in multiple languages adds a lot of unnecessary complexity. What is the advantage in non array values? I see no advantage, and a lot of disadvantages.

Non-array values on the right hand side of property-value statements make sense when the arity of the value is a single property. For example, an individual only has ONE birthday.

Yes, we could force all developers to express birthdays like this: "birthday": ["1994-04-15"] ... but developers would find that very strange, and many wouldn't read the spec and would do "birthday": "1994-04-15" instead.

Given that that is most certainly going to happen, even if we say that all right hand values MUST be arrays, implementations will find themselves in the position of either rejecting the input... or, the more likely, and what has happened on a fairly consistent basis in programming and markup languages over the last 30 years or so: if there is a rational way of correcting input, the implementations that do that and don't throw errors will "win" (read: XHTML2 vs. HTML5).

We can put something non-normative in the spec to point this out to implementers if those that are concerned in this issue think that would be beneficial.

[dlongley]

Also, https://www.w3.org/TR/html-design-principles/#priority-of-constituencies:

In case of conflict, consider users over authors over implementors over specifiers over theoretical purity.

Here we expect authors to do "birthday": "1994-04-15" (or "credentialSubject": {"foo": "bar"}}) and implementors to deal with it.

[mirceanis]

Ok, but implementors should be aware, at least, of which fields can be expected to shift types, no?

[awoie]

@msporny @dlongley @mirceanis The spec should talk about which attributes could change their type. If this is too verbose, then we should mention that some attributes can change their type and add a note/reference to the implementation guide which should contain an exhaustive list of these attributes.

[msporny]

After discussion in the WG, add specification text detailing the arity of each property expressed in the specification.

We should state that the arity of all properties can be a single value or multiple values (an array), except for X, Y, Z. This should be a clarifying normative statement in the specification that is also non-substantive since it's clarifying what was always the intent of the specification.

[msporny]

The PR has been merged, marking 7 day close pending objections from the issue submitter.

[burnburn]

No objections received. Closing.