Re: PROPOSAL regarding JSON-LD material

On 02/11/2016 04:36 AM, Adrian Hope-Bailie wrote:
> There is a lot of mention of requiring an "extensibility story". In
> my experience I have never come across a specification for an API
> that defines the format of the API parameters and then also some
> mechanism for how those parameters can be extended.
>
> I believe this is because, if the API parameters happen to be
> re-usable outside of the API and can be extended for these use cases
> then it's not the job of the API specification to describe how this
> is done.

I think what should really be done is we should have a messaging spec
(for things like payment request messages). That messaging spec should
specify extensibility mechanisms for those messages.

The low-level browser API spec should reference the messaging spec when
talking about the payment request message it accepts and make it clear
that it will accept extended messages by ignoring unrecognized
properties and their associated values in those messages.

We need two things:

* Make it clear to API implementers how to ensure extensibility is
possible. (Do not touch unrecognized properties and their values).

* Tell callers of the API that their extended messages will work with
the API and there's at least one well-defined extensibility mechanism
that they can use if they follow the advice found in another spec. (To
extend messages using JSON-LD you must follow this other spec).

That latter point doesn't say "You must use JSON-LD." It says, "JSON-LD
is a way to extend messages used in this API -- but to use it properly,
you need to follow this advice."

>
> Offer, invoices, receipts and any other elements of the ecosystem
> that are not in scope for this API should be dealt with outside this
> API spec.
>
> The browser API spec defines an implicit context for its JSON
> parameters. That context is the API spec itself (i.e. The fact that
> the objects are being passed to/received from the API defines their
> context).
>
> It is possible for ANYONE to define a JSON-LD context that happens to
>  define a JSON object schema that matches the one in the browser API
> spec.
>
> I believe it is desirable for the WG, for the sake of
> standardization, to define such a JSON-LD context and RECOMMEND that
> any processor of data passed to/from the browser API should assume
> the WG defined context IF no other context is defined (i.e.
> discourage a proliferation of new JSON-LD contexts for this
> purpose).

Agreed that we must recommend the appropriate JSON-LD context and any
other related advice so we have a clear path to interoperability.

>
> I don't believe any of this creates a requirement for a normative
> reference from the browser API spec (which has no dependancy on
> JSON-LD or the WG's JSON-LD context) to the JSON-LD extensibility
> recommendation.

I'm fine if we make the reference informational so long as this other
spec is recommendation track. I want to make it very clear how to
interoperate when extending via JSON-LD and that we have a well-defined
extensibility framework (it doesn't have to be the only one) that can be
used. Let's not reinvent the wheel.

>
> Therefore, as yet, I have still not heard a good rationale for having
> any normative language in the browser API spec that refers to
> JSON-LD, only hand wavy references to an "extensibility story" which
> is not required by the browser API but rather by the wider
> ecosystem.

Let's make sure that the other spec we're referencing is recommendation
track. I think that's the fear here. I think we are all saying it's
really important to specify how to interoperate properly with the API
and extend messages when using particular extensibility mechanisms, but
the details don't belong in the API spec. Let's not forget the first
part of that sentence. The solution here seems to be: Make a separate
REC track spec for this and then do not make it a normative requirement
in the API spec -- but make sure it's clearly linked to as a way to do
extensibility with an indication that there's another spec you need to
follow to interoperate properly.


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

Received on Thursday, 11 February 2016 15:25:19 UTC