Re: PROPOSAL regarding JSON-LD material

[snip]

>> ======== 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.

The payment request spec has a dependency [1] on ECMA-262 6th Edition
that seems to refer to JSON objects, and I see statements that say “if not a JSOn
object then it’s an error.” There are also JSON-looking examples in that spec.

So that’s what I’m referring to. My main point is to say that there is strong
agreement to use JSON when we need to exchange relevant data, and
there is not strong agreement to use JSON-LD.

[1] http://wicg.github.io/paymentrequest/specs/paymentrequest.html#dependencies

> 
>> 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."
> 
> +1
> 
>> - 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.

It seems we need to have more discussion about error handling in the
spec; that’s fine.

> 
>> * 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
> specification.
> 
>> * 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.

I believe we do not have enough information to determine that a JSON-LD
specification will lead to interoperability. That is why I favor publishing material
to start that discussion, then taking the necessary time to work with the
ecosystem to develop that interoperability. That work should not affect
the timeline of the browser API.

I want that work to happy, but do not feel there is a benefit to stronger language
at this time.


> 
>> * 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 think everyone agrees that the API should enable the exchange of custom data.

I do not believe we have consensus today that there is only one way to exchange custom data.
It is therefore inappropriate to mandate a single approach at this time.

I do support saying “When you use JSON-LD for custom data, do so like this.” and describing
that in the companion spec.

> 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”).

I believe that level of mandate is premature.

> * The external spec is normative.

That can be determined later once we have more information.

> 
>> * 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:
> 
> http://web-payments.github.io/web-payments-messaging/
> 
> 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]

While I am thrilled to hear that JSON-LD has traction, I believe that the
use of JSON-LD in schema.org is a different use case from what we are talking
about in the browser API. I do not believe that the data from schema.org is
directly relevant, though it is certainly good to see adoption in other contexts.

> 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).

I have had several conversations with the people doing the FIBO work and they
do seem enthusiastic about semantic web technology. That is not a sufficient condition
to say that we should mandate JSON-LD today. It is definitely a piece of what
I believe is necessary work to understand the interoperability needs and expectations
of the ecosystem where this API will be used.

Ian


> 
> -- manu
> 
> [1]https://github.com/w3c/webpayments/issues/27#issuecomment-179207196
> [2]https://lists.w3.org/Archives/Public/public-payments-wg/2016Feb/0154.html
> 
> --
> 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
> https://manu.sporny.org/2015/payments-collaboration/
> 

--
Ian Jacobs <ij@w3.org>      http://www.w3.org/People/Jacobs
Tel:                       +1 718 260 9447