Re: Checkout API spec published

On 02/09/2016 12:11 PM, Ian Jacobs wrote:
> [snip]
>
> 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?

Applications are always written with some kind of context. For
applications that only understand regular JSON, the context is
*implicit* -- often derived from a human reading a specification and
then hard-coding the application to work with data expressed in a
particular way.

JSON-LD makes it possible to make that @context explicit and machine
readable. JSON-LD lets you express information from an unbounded set of
decentralized vocabularies. It also provides a mechanism, called
"compaction", that will transform messages so that they are expressed in
a way that a particular application can consume.

This means that you can author a JSON-LD message in whatever context you
want, using whatever vocabularies you want, and you can then transform
that message so it can be used by an application that may only
understand a small subset of what you've expressed. The way you perform
this transformation is by compacting the message using the @context that
will cause the data to be expressed in a way the target application
understands.

If API implementations are hard-coded to semantics that humans have to
read in a spec, but we want to allow them to pass through messages that
are fully extensible, what we need to do is transform those messages to
the context that the API implementation understands. The parts that the
API does not understand will remain in "JSON-LD expanded form" which can
be entirely ignored. Then the API can treat the data like regular JSON,
doing what it needs to with it and passing it through to a payment app.

Once the API implementation passes this message through, the payment app
at the other end can be assured that it is "in the context" understood
by the API implementation. That payment app doesn't have to speak
JSON-LD either. But, if it does, all it needs to do is know that the
@context matches the one that the API implementation "effectively"
understands (even though the implementation does no processing at all).
The payment app can apply that implicit @context and then compact the
data to whatever @context the payment app uses, which will transform the
data back to being expressed how the payment app desires.

Note -- here's the answer to your question -- the payment app also
doesn't have to assume that the originator of the payment request used
JSON-LD. Perhaps the payment app wants to wrap the payment request up in
another JSON-LD message (or who knows what). In this case, there may be
no @context present on the payment request -- and the payment app needs
to know the "default @context" by which to interpret the message.

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

We only want there to be one way to interpret the data. That's where the
interoperability comes from. I think what you're trying to say is that
people can't use their own vocabularies to add *additional* information,
properties, values, etc. to the message -- but that's just incorrect.
Hopefully the explanation above shows why.

> [snip]
>
> 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.

Hopefully I've explained this above.

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

The browser already understands something. It's just a hard-coded,
implicit context. Every application today already works this way.
JSON-LD just makes it possible to be explicit about it with a
machine-readable @context. We need to tell people what that @context is
so they know how to interpret what's coming out of the API (and so we
can convert to that context when sending something into the API so it
will be understood by it).

> [snip]
>>
>> 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.

Does the explanation at the top of this email help explain?

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

That's what we're specifying. We're telling people how to make it "the
right JSON-LD" by saying "this is the @context you compact to". Does
that make sense now?

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

Do you understand now?

>
> If the payment request API takes ... [snip] ...
>
> I may be misunderstanding something, but that’s how I am thinking
> about it.

I think we should wait to discuss this further until we're on the same page.

> [snip]
>
> 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.

That's not how JSON-LD works. Well, if you want to make it so API
implementations don't need to do -LD processing, that's not how it
works. In a perfect world, implementations would just do the -LD
processing and it would work like that. But we've got a situation where
there's an application that doesn't understand JSON-LD in between the
endpoints -- and that's ok. JSON-LD is designed to handle that.
Converting a message to another @context doesn't change its semantics,
it just changes how those semantics are expressed as JSON.

Applications need them to be expressed in a particular way because it's
easier to write code that way. If your app can do -LD processing, then
you can always compact incoming data into the @context your app is
written against and then work with it. You can similarly send that data
out in whatever @context you want (or in one that is requested).

If you are sending a JSON-LD message to an application that doesn't do
-LD processing, you just do the processing for it first, transforming it
into a @context it understands. The application can then just treat the
data like JSON, it doesn't care. The API implementations don't do -LD
processing, so we need to tell people who use JSON-LD which @context
their data must be in for the API to understand it.

> [snip]
>
> 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.

Do you understand now that the @context is for the API implementation,
not for the entities that send or receive data from the API? They can do
whatever they want.


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

Received on Tuesday, 9 February 2016 18:35:02 UTC