Re: Checkout API spec published

[snip]

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

My suggestion is that @context be explicit in the data that is passed to the API (and thus HTTP info not necessary).

I am hearing you say you have use cases where the @context cannot be stated explicitly. Can you say more about those use cases?

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

Your proposal only allows one value of @context. Therefore, there is only possible way to interpret the JSON-LD sent through the API.

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

I agree clarity is required. Currently the text says “Implementations” which is not as specific as what you have just written.

What is “compacting it to the proper context’? My assumption (please correct me if this is wrong) is that the caller just sends the right JSON-LD (with the right @context) through the API.

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

The browser doesn’t need to understand anything. The browser just needs to ignore @context and other JSON-LD specific bits.

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

I do not yet understand why that is a requirement. See above comment for understanding of use cases.

> 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?

Assume that the JSON-LD going in is “the right JSON-LD” and is left unmodified by the browser.

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

I don’t yet understand why any transformation is required, as opposed to just sending the data through the API.

If the payment request API takes (for example) these parameters:
 * supported methods
 * payment details
 * payment options,
 * optional object data

could you send the JSON-LD bits through one or more of the parameters?

In other words:
 * The caller sends the bits according to the API params
 * The bits include JSON-LD bits.

I may be misunderstanding something, but that’s how I am thinking about it.

> 
>> 
>>  * 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?

Suppose I am experimenting and want to try out a draft of version 2 of the JSON-LD data. So I want to use as a context URI <http://example.org/payments/v2>.
If I send that URI, it will be modified by your processor to become <https://w3id.org/payments/v1>. That’s not what I want to happen. I want the processor to
leave the URI alone so I can experiment.

As an aside, I have concerns about using a domain name for this proposal that is not under the management of W3C. Furthermore, it is not clear that W3C
would want to use a domain other than w3.org for this purpose.

> 
>> 
>>  * 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)?

Any entity that wants to use the data (whether sender or receiver).
> 
> 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 there is conformance to the JSON-LD companion spec, then future conformance will require compacting to the v1 URI, which means that deployed software that
doesn’t do that (e.g., because it now wants to accept v2) will no longer conform to the v1 spec.

Ian




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


[1] https://wicg.github.io/web-payments-browser-api/
--
Ian Jacobs <ij@w3.org>      http://www.w3.org/People/Jacobs
Tel:                       +1 718 260 9447