Should payment method specifications contain WebIDL?

[adrianhopebailie]

I wonder if we need to use WebIDL in the payment method specifications.

This data is supposed to be passed through the user agent with no processing so I think we could simply use a JSON schema definition of some form or just examples and explanations?

WebIDL is over-kill in my opinion and may be a barrier to payments domain experts defining these specifications (which is what we desire).

[sideshowbarker]

I wonder if we need to use WebIDL in the payment method specifications.

I think we do not. When I first saw it I wondered why a choice has been made to use WebIDL for this.

This data is supposed to be passed through the user agent with no processing so I think we could simply use a JSON schema definition of some form or just examples and explanations?

I personally have no strong preference as far as how to express it without WebIDL. But as you point out, given that the UAs need to implement no parsing or handling of the parsed data, I can’t see any value to expressing it using WebIDL.

WebIDL is over-kill in my opinion and may be a barrier to payments domain experts defining these specifications (which is what we desire).

Yes. WebIDL is a necessary evil in cases where it can’t be avoided. In any cases where it can be avoided, it should be avoided. At least as far as web authors-developers go, WebIDL is an expression language completely foreign/unfamiliar to the experiences of anyone except browser-engine developers.

[adrianhopebailie]

The Web App Manifest specification describes pure JSON objects and their members.

Would anyone oppose using a similar format?

[dezell]

WebIDL is over-kill in my opinion and may be a barrier to payments domain experts defining these specifications (which is what we desire).

I probably have to take some of the blame the WebIDL shows up in various places. The reason for that has to do with the following:

1. the W3C NFC specification (written in IDL) and the fact that there was - at least early on - some hope of a more fully featured NFC edition that would include payment.
2. the general idea that software stacks that have components defined in IDLs (not necessarily WebIDL) tend to be stronger than those that are simply ad-hoc.
3. an IDL gives some idea - in a more formal way, of how responses align with requests, and some idea of how various features like "Promises" fit.

WebIDL is an expression language completely foreign/unfamiliar to the experiences of anyone except browser-engine developers.

That WebIDL was unsuitable in this area was not clear earlier. Michael is an expert, so no argument here.
I would recommend at least JSON Schema definitions for the objects in question, since I think that will make a better spec. We are, I guess, convinced that the choreography aspects of a definition in WebIDL (weak, admittedly) are not worth the frieght.

[adrianhopebailie]

There are at least two PR's against the Basic Card Payents spec and anther payment method spec has been proposed already. To avoid wasted effort we should solve this urgently.

It would be great if someone could take on the job of proposing an alternative format for this spec that does not use WebIDL.

I believe this is related to #146 so perhaps @dlongley or @msporny you could have a stab at this?

Proposal

• Define the request and response fields in a definition list <dl> and provide an example of their JSON representation.
• Optionally include a JSON Schema that can be used to validate the data.

[AxelNennker]

I propose to specify the payment API using WebIDL because most specs use it.
I think that not using WebIDL might prolong discussions and spec approval.
The gain from not using WebIDL is small and web-developers never see it.

[adrianhopebailie]

@AxelNennker - this issue relates to the payment method specifications like the Basic Card Payment spec [1] and proposed SEPA spec [2] not the API

[1] https://w3c.github.io/browser-payment-api/specs/basic-card-payment.html
[2] https://w3c.github.io/webpayments/proposals/basic-ct-dd-payment/basic-ct-dd-payment.html

[halindrome]

(with my Web Payments Test Czar hat on)

I would oppose using WebIDL to specify something that is purely a message structure. It is overkill and would only make the testing harder. Use JSON and a JSON Schema or a JSON-LD context to define its structure. This will permit the ready generation of tests and evaluation of responses.

[msporny]

@adrianhopebailie wrote:

I believe this is related to #146 so perhaps @dlongley or @msporny you could have a stab at this?

Sure, happy to... but before we do, I'd like more thoughts on the core messages spec as I think that's the right approach:

1. Define the messages in a very general way (using human readable text). For example: http://w3c.github.io/webpayments/proposals/core-messages/#paymentrequest
2. Point to where the messages are defined for use in more formal development environments. For example:
   • Point to Browser API for WebIDL - http://w3c.github.io/webpayments/proposals/core-messages/#expressing-messages-as-webidl
   • Point to JSON Schema for JSON - http://w3c.github.io/webpayments/proposals/core-messages/#expressing-messages-as-json
   • Point to JSON-LD Frame + JSON Schema for JSON-LD - http://w3c.github.io/webpayments/proposals/core-messages/#expressing-messages-as-json-ld

The core messages spec proposal already takes this approach:

http://w3c.github.io/webpayments/proposals/core-messages/

I think this addresses everyone's concerns and is more or less inline w/ @adrianhopebailie's proposal - thoughts @adrianhopebailie @dezell @ianbjacobs @AxelNennker @sideshowbarker @halindrome @mattsaxon @dlongley ?

[AxelNennker]

@halindrome Let's just agree we disagree. I think that keeping the WebIDL the right thing to do and don't see how this affects your testing because dictionaries are easily translated to json or back.

[AxelNennker]

@adrianhopebailie the objects are used in the Payment API

"The BasicCardResponse dictionary contains the response from the PaymentRequest API when a user accepts payment with a Basic Payment Card payment method."

so why no use WebIDL?

[dlongley]

so why no use WebIDL?

Web IDL is unnecessarily restrictive. You can't extend dictionaries as you see fit and preserve the data from the caller of the API through to the Payment App. The payment specific data (not things that the user agent specifically calls out) is sent as an object. This allows extensibility. That includes the stuff defined in the BasicCardResponse, so there's no reason to use Web IDL and force its restrictions onto the data. Web IDL is only being used for the stuff that the browser manufacturers have indicated that they want broken out separately.

[adrianhopebailie]

Migrated to w3c/webpayments#133