Re: [webpayments] How should the message schemas for the payment request and response be defined? (#27)

@adrianhopebailie wrote:
> 1. The group must still agree upon a **logical message schema** (i.e. irrespective of the encoding format) and therefor this proposal relates only to the way the group will express this schema when it publishes it's specifications

+0 - I don't quite understand what you mean by "logical message schema". Do you mean something like this (just a list of properties/attributes and what they should contain):

https://web-payments.org/specs/source/ld-signatures/#linked-data-signature-overview

It's effectively the same here (without the WebIDL):

http://wicg.github.io/paymentrequest/specs/paymentrequest.html#currencyamount

WebIDL defines stuff that goes beyond the "logical message schema" imho... it defines implementation details and encoding rules - for example, you have types for things like 'unsigned long long' in there - https://heycam.github.io/webidl/#idl-unsigned-long-long

Alternative proposal: The group must agree on how to express the properties and values that should go in each payment message (irrespective of the encoding format). 

 > 1. The group will define a payment request object and a payment response object using **WebIDL** and developers will pass plain Javascript objects to the API (and expect the same as return values)

-0.5 - WebIDL is engineering overkill. All you need to do is specify the expected object in JSON format. That means, define the property names, whether or not it's optional, and the range of the value (string, integer, boolean).

Counter-proposal: It will use plain JSON objects to do so with prose that explains the purpose and value range of each property.

 >  1. The definitions will specify appropriate optional attributes that can be used by developers to carry custom data such as payment method specific data.

-1, this presumes that we know what the extension points are. We don't. What are we doing for receipts? Invoices? coupons? digital offers? We shouldn't prescribe specific extension points. We should enable innovation at the leaves - let certain market verticals extend the base format (but to do this, you need to have a clear extensibility story, like JSON-LD or attribute registries or normative wikis).

 >  1. The conformance criteria for browsers implementing the API will be to accept and process these request objects appropriately and to return valid response objects that comply with the schemas defined by the group.

+1

 >  1. Conformant browsers will be expected to ignore and pass on any attributes that are not defined in the specification.

+1

 >  1. The group may define a JSON-LD context that aligns with the WebIDL definitions such that a POJO object that is compliant with the WebIDL definition will by virtue of that be valid JSON-LD by simply specifying this newly defined context and the appropriate type (payment request or payment response).

-0.5, I think this is a bit backwards.

We should define what we want the message to look like in a way that can go into a spec by itself (that can then be shared w/ the browser API and the HTTP API and other APIs).

If we do this in WebIDL, this is effectively what we're going to end up with throughout the entire document (note that you gain almost nothing from the WebIDL dictionary definition... the useful bits are below it - which could easily be shared across all the specs we may create... and, btw, is aligned with the way ISO20022 does it):

----------------------

```javascript
dictionary CurrencyAmount {
    DOMString currencyCode;
    DOMString value;
};
```

A CurrencyAmount dictionary is used to supply monetary amounts. The following fields must be supplied for a CurrencyAmount to be valid:

*currencyCode* - currencyCode is a string containing a three-letter alphabetic code for the currency as defined by [ISO4217]. For example, "USD" for US Dollars.

*value* - A string containing the decimal monetary value. The string must use a single U+002E FULL STOP character as the decimal separator. The string must begin with a sing U+002D HYPHEN-MINUS character if the value is negative. All other characters must be characters in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9).


---
Reply to this email directly or view it on GitHub:
https://github.com/w3c/webpayments/issues/27#issuecomment-178871826