Re: Checkout API spec published

On 02/09/2016 09:08 AM, Ian Jacobs wrote:
>
>> On Feb 8, 2016, at 11:36 PM, Dave Longley <dlongley@digitalbazaar.com> wrote:
>>
>> On 02/08/2016 11:55 PM, Ian Jacobs wrote:
>>>
>>>
>>> An approach that does not force a single @context value would allow
>>> experimentation while still providing a known set of semantics.
>>
>> I don't fully understand this comment. To my mind, the @context is what
>> provides that known set of semantics. Could you provide some different
>> examples?
>
> The current extensibility text [1] concerns me in several ways:
>
>   * It defines processing of JSON-as-JSON-LD which is not, in my view, the
>     purview of this group. That is the purview of the JSON-LD specification [2].
>     In doing so, it breaks JSON-LD interop because there is a risk that JSON-LD
>     processors will interpret the JSON differently (e.g., if @context is sent via an HTTP header,
>     and that @context conflicts with this spec, who wins?)

We haven't defined any place where the browser API transmits the JSON 
over HTTP. We have to indicate what the context is somewhere or the core 
vocabulary (terms defined in the spec) will not be expressed in JSON-LD 
in a way that the API can consume as regular JSON.

>
>   * It controls the @contact attribute in order to achieve this, meaning that others cannot
>     send JSON-LD with other semantics through the pipe. This to me is a show-stopper because it
>     prevents extensibility.

Why do you think that others would be unable to send JSON-LD with other 
semantics? How does it prevent extensibility in JSON-LD? I have to 
assume that when you say "other semantics" you aren't talking about 
interpreting the core vocabulary (the terms defined in the spec itself) 
in a different way. The @context would only express those terms.

>
>   * I believe the text itself has an inconsistency (or at least we want to double check that it doesn’t). On the
>     one hand it says "Implementations MUST preserve unrecognized properties and their associated values.”
>     On the other it says "If its value does not match, perform JSON-LD compaction on the object using that context.”
>     In other words, it says “If you don’t recognize the value, then treat it a certain way rather than preserving it.”

We need to clarify who we are talking to. In the former case, we're 
talking about implementers of the API itself. In the latter case, we're 
talking about callers of the API. So, browsers don't touch the data, 
they just pass it through. Callers of the API that represent the payment 
request as JSON-LD need to compact it to the proper context before 
passing the message to the API. This will transform the message to the 
context understood "by default" by the browser (so the browser can treat 
it like it's regular JSON, being totally agnostic with respect to the 
-LD bits).

>
> Another approach would be:
>
>   * Clearly state that JSON-LD can be used.
>   * Define a @context value that, when provided explicitly, gives rise to the semantics defined in the document.

We need to do at least two things for interoperability:

1. We need to define how callers of the API can ensure that a JSON-LD 
payment request is accepted by the browser. They must compact to the 
only context understood by the browser, because the browser does not do 
any JSON-LD processing.

2. We need to define how payment applications can receive a payment 
request from the browser API and "transform it" to JSON-LD if it did not 
already carry context. So we need to tell them what context to add to it.

The current spec tries to do both of these things. How would your 
suggestion be different in terms of spec language?

>
> That approach would:
>
>   * Be simpler.

So far, at least to me, it sounds the same. I'll need to see some spec 
language to try and tease out the differences more clearly.

>
>   * Enable the JSON-LD that is used is interoperable and can be reused out of this API with the same meaning everywhere, rather than
>     rely on processors to know this spec.

I'm not quite sure I follow this. If you want to use the API spec you 
have to know the spec because we're saying implementers of the API won't 
do any -LD processing. That means you need to ensure you perform a 
proper transform so that your message will be accepted by the API. We 
have to tell people what that transform is. In my view, the most 
appropriate place to tell people what that transform is for a particular 
API is in that API's spec.

>
>   * Support extensibility by people who want to use their own JSON-LD vocabularies.

I think the approach in the spec already supports this. Why do you think 
it doesn't? I didn't see anything above that would prevent 
extensibility, so it seems like there's a misunderstanding somewhere. 
Perhaps an example that you think wouldn't work would help?

>
>   * Allow processors to evolve over time and still conform to this specification. Otherwise, a “v1” processor would never be able
>     to upgrade to handle v1 AND v2 since it would always convert the v2 to v1 semantics.

Based on how you used "processors" in that sentence, do you mean a 
caller of the API (eg: website) or an implementer (user agent)?

If you meant a caller of the API, then perhaps I'm not following you, 
but they should be able to freely evolve over time and still conform 
just fine to this specification. If this specification requires a v1 
context, the caller can evolve however it wants -- as it can always 
safely compact back to the v1 context to use the specification.

If you're talking about user agents, they don't have to think about this 
at all. If the specification evolves overtime, we'll simply indicate 
that a different context should be used (and the spec's backwards 
compatibility support for non-JSON-LD callers would function the same 
way as it would for JSON-LD callers).


-- 
Dave Longley
CTO
Digital Bazaar, Inc.
http://digitalbazaar.com

Received on Tuesday, 9 February 2016 15:36:44 UTC