Re: PROPOSAL regarding JSON-LD material

On 02/09/2016 01:12 PM, Ian Jacobs wrote:
> My hope is that we will have resolved this in advance of the FTF 
> meeting. I believe that will allow us to focus on important 
> outstanding issues in the "base API” specification(s) at the FTF 
> meeting.

Or we could agree to back-burner the JSON-LD/extensibility discussion
and favor the API discussion at the face-to-face. There are other ways
to focus on the "base API" specification than go back and forth about a
few paragraphs at the end of a spec.

> ======== PROPOSAL
> * In the base API specification(s), JSON (1) is the message format 
> required for conformance.

Conformance in the Browser API specs (I'm assuming that's what you mean
by "base") require a ECMAScript Object matching the interface and/or
dictionary definitions. None of the current specification proposals
establish JSON as the message format required for conformance.

> I believe this requirement is uncontroversial.

I don't know if you're saying JSON is the base message format in the
Messages spec, or if you're saying JSON is the base message format in
the API spec. I'd be a -1 for either proposal.

I'd be a +1 for the use of WebIDL to express a message format in the
browser API specs as long as there is a clear extensibility story with
the use of JSON-LD. This is what the Web Payments CG proposal has been
modified to do at this point. We can tweak it here and there, but it's
good enough right now for us to focus our efforts on the high-level
Checkout API / low-level Payment API.

> Still for discussion within the WG:
> - What is the behavior of conforming processors when they encounter 
> unrecognized properties? I am hearing most support for "leave them 
> and their values untouched."


> - What is the behavior of conforming processors when they encounter 
> unrecognized values of recognized properties? Is the answer "throw
> an error" and we define that error handling? or ignore them?

Unfortunately, I think the only rational answer at this point is "it
depends, but throw an error for the cases where we clearly know there is
an error". So this is a case where we clearly know there is an error:

FinancialAmount {
  "amount": "4f.00",
  "currency": "USD"

but here, it's a bit fuzzier:

FinancialAmount {
  "amount": "0.0024",
  "currency": "BTC"

... and we may not want the browser throwing errors w/ financial amounts
at all, instead passing it through to the payment processor to handle.
In some cases, we may even want to pass it through to the payment
processor and in other cases we may not want to do that.

> * The Working Group SHOULD publish a companion specification that 
> explains how to use JSON-LD with the API.

That companion specification MUST contain normative language on how you
interpret the messages as JSON-LD in order to ensure interoperability.
There MUST be a normative link between the API spec and the companion

> * If the Working Group publishes a companion specification, the base 
> API specification(s) SHOULD include a short, informative reference to
> that specification. (e.g., with a sentence like "For information 
> about using JSON-LD with this API, see [OtherSpec].”).

-1 for informative. +1 for normative, with language like this:

If an object in this API is to be interpreted as JSON-LD, the rules in
COMPANION_SPEC MUST be used to ensure proper message interoperability
with this API and systems that use JSON-LD-based payment messages.

If you don't have that in there, there is no normative statement on how
you use the API objects w/ JSON-LD. I'd be strongly opposed to anything
that doesn't ensure interoperability. Clearly, we want to keep the
options open, but not so open that it prevents widespread interoperability.

> * It gives visibility to the use of JSON-LD with the API. I do not 
> yet have a sense of "how normative" that companion specification 
> should be, and therefore this proposal does not address the content 
> and normative status of that specification. By decoupling the
> JSON-LD specification, it can evolve independently as the group sees
> most fit.

My concern is that we're marginalizing the importance of JSON-LD to the
extensibility story without the group fully understanding why we're
suggesting JSON-LD is a good solution to the extensibility story. I'm
unconvinced that the group understands why this is important to the
interoperable/extensible ecosystem we're trying to build and we're going
to prematurely marginalize a key technology as a result of the group not
understanding what the proposal in front of them means.

> * It keeps the base API specification(s) focused on requirements for 
> implementers of the defined API. It will also shorten that 
> specification.

We're talking about the difference of a few sentences, I don't think
length is an issue here.

I'm fine w/ pointing to an external spec as long as:

* The link is specific and normative ("if you want to interpret as
  JSON-LD, follow these rules").
* The external spec is normative.

> * I would like to see work on the companion specification begin soon 
> so that we can start to engage with stakeholders in the ecosystem.

Is that companion specification the Messages specification? If so, we've
already started it here:

Also note that we can pull in ISO20022 much more easily if we use
JSON-LD (as the separation between data model and syntax is the same).
That is not true for JSON (where the data model is bound to the syntax).

> stakeholders in the ecosystem

We should note that Dan Brickley from Google has stated that they're
seeing JSON-LD published on millions of websites[1] and Omar Khan from
Wells Fargo has asked us[2] to keep JSON-LD in the spec as a recommended
extensibility mechanism (because they'd like to use it).

-- manu


Manu Sporny (skype: msporny, twitter: manusporny, G+: +Manu Sporny)
Founder/CEO - Digital Bazaar, Inc.
blog: Web Payments: The Architect, the Sage, and the Moral Voice

Received on Wednesday, 10 February 2016 05:03:04 UTC