Re: PROPOSAL regarding JSON-LD material

On Feb 11, 2016, at 9:24 AM, Dave Longley <dlongley@digitalbazaar.com> wrote:
> 
> 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.

On this thread I would like to stay focused on my goal of decoupling specs,
and not delve into the content of the companion spec or the overall organization
of specs.

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

(That’s a separate topic.)

> 
> We need two things:
> 
> * Make it clear to API implementers how to ensure extensibility is
> possible. (Do not touch unrecognized properties and their values).

(Yes, previously agreed to.)

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

The place to say “must” and “need to” is in the companion spec.

[snip]

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

That outcome is possible. I do not support making the decision today.
We need more experience and discussions with other stakeholders.

Ian

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