Re: PROPOSAL regarding JSON-LD material

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.

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

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.

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

Point of Order

This issue is creating a great deal of noise despite the fact that at this
point everyone appears to agree that the API should be defined (like all
other W3C APIs) using WebIDL. We are debating the wording of a minor
section of the spec which we can haggle over later, it has no baring on the
rest of the work.

I'd prefer to not exercise any veto as chair but I'm inclined to put this
issue aside (so we can focus on getting out a FPWD) at least until:

   1. There is more input from the rest of the group
   2. There is a proposal for what the JSON-LD guidance document will look
   like
   3. The actual data model of the API parameters has stabalized

I support the replacement of the extensibility section with an issue marker
that indicates there is parallel work being done to define how the API
parameters may be extended for use outside the API using JSON-LD as long as
we don't create an impression that there will be a normative reference to
this work until such time as the group agrees this is necessary.

@ianbjacobs: Can I ask you to put this proposal forward in today's call? I
have logged it on GtHub: https://github.com/w3c/webpayments/issues/83


On 11 February 2016 at 04:52, Ian Jacobs <ij@w3.org> wrote:

>
> > On Feb 10, 2016, at 8:23 PM, Manu Sporny <msporny@digitalbazaar.com>
> wrote:
> >
> > On 02/10/2016 02:22 PM, Ian Jacobs wrote:
> >>> * To extend interfaces in this API using JSON-LD, the rules in
> >>> COMPANION_SPEC MUST be used to ensure proper message
> >>> interoperability with this API and systems that use JSON-LD-based
> >>> payment messages.
> >>
> >> David and I drafted this text yesterday:
> >>
> >> “The ‘JSON-LD Payment Extension’ specification explains how to
> >> extend this API using JSON-LD.”
> >
> > -1 - that's effectively saying nothing. Given no normative guidance in
> > the extensibility section, and pointing informatively to an informative
> > spec in that section is effectively worthless to implementers seeking
> > interoperability. It's a failure to standardize.
>
> It is not the job of the reference in the base spec to establish how
> normative the
> companion spec is. That is especially true at this time when we don’t have
> consensus
> on the answer.
>
> Please note that I did not say that the companion spec would necessarily
> be informative.
> I said we need to do more work so that we can determine how normative it
> should be.
>
> (In the first email on this thread I wrote: “...and thus how normatively
> we express the material.”)
>
> > The WG needs to have a much better extensibility story (e.g. how are we
> > going to support offers, invoices, and receipts?), and the proposal
> > above isn't it.
>
> As I said at the beginning of the thread, I support the group developing an
> extensibility story with JSON-LD.
>
> There is currently no consensus on that story. It is therefore premature to
> speak of any extensibility mechanism as “the one mechanism” for this API.
>
> >
> > Add to this that the only active participants in this extensibility
> > discussion have been you, myself, Longley, and AdrianHB. I don't support
> > us settling on any language at this point because there is clearly still
> > disagreement on the extensibility mechanism and the WG is not engaging
> > in the discussion.
>
> The disagreement on the mechanism is precisely why we cannot include
> any normative-sounding language at this time.
> >
> > So, how about this instead - an ISSUE marker in the extensibility
> > section that states:
> >
> > """
> > ISSUE: The Working Group is actively seeking guidance on the best set of
> > extensibility mechanisms for Web Payments messages and objects. One such
> > proposal is <link to JSON-LD Web Payments Messages>. If your
> > organization prefers a certain extensibility mechanism for Web Payments,
> > such as JSON-LD or some other mechanism, please send your comments to
> > public-payments-wg-comments@w3.org.
> > """
> >
> > Then, we push the FPWD out there and actively seek input.
>
> We have a deadline of the end of March for FPWD. In my view we need to
> decouple the base specification from the extensibility story. We need to
> focus
> now on the most pressing issues directly related to the base spec.
>
> I support the idea of an issue marker and propose this language:
>
>   "The <a>JSON-LD Payment Extension specification</a> explains how to
> extend this API using JSON-LD.
>    NOTE: The Working Group seeks feedback from the community on that
> specification and how well it
>    furthers interoperability needs in the payments ecosystem. To provide
> feedback, see the <a>status section above</a>."
>
> Here are some comments on the difference from your proposal:
>
>  * I have not heard a lot of discussion within the WG about extensibility
> mechanisms other than the JSON-LD proposal.
>    Therefore, I think at this time people should focus their feedback on
> that proposal. If we have another one on the table at
>    some point, we will point people to that one as well.
>
>  * The status section should include the full instructions for feedback
> (e.g., email, github, etc.). So I prefer to point people
>     to the status section for info on providing feedback.
>
> Ian
>
> --
> Ian Jacobs <ij@w3.org>      http://www.w3.org/People/Jacobs
> Tel:                       +1 718 260 9447
>
>
>
>