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

> I don't quite understand what you mean by "logical message schema".

As @vkuntz points out, ISO20022 defines a very good way of going from a business model to a well defined message syntax. Part of this process is defining the *logical message schema* or the *message model*. (More info in the [ISO20022 for Dummies](http://www.sepahungary.hu/uploads/ISO20022_fordummies.pdf) around page 12).

The logical message schema/model is usually designed in UML. Based on the model, syntax specific schemas can be generated (like a JSON-LD context, JSON Schema or XSL document that is representative of the model).

I would agree with @ianbjacobs that the the different use cases for the payment request message require a different technical schema (encoding). The use of the messages as API parameters in the browser API is a specific use case that is different to the ones you have listed.

I don't believe we have consensus that all use cases MUST share the same *logical message model* but I think we all agree that they SHOULD if they can.

My assertion is that even though we haven't agreed on the logical message model/schema yet, that shouldn't prevent us from deciding what technical message syntax(es) we consider appropriate (especially for the browser API spec).

In attempting to get closer to consensus @dlongley asked if we can agree on the following: 

> Implementers of the Browser API (browsers) must not have to do any JSON-LD processing.

+1

> It must be possible to interpret messages passed into the Browser API as JSON-LD

My interpretation of this is that if the next point holds then this is implied because someone expecting or requiring JSON-LD can simply take the JSON object and add a "@context" and "@type" to get a JSON-LD object

> Implementations must ignore (and pass through) unrecognized message data.

+1

So if we focus on the question at hand, specifically for the browser API:
* Browser APIs consume JSON objects. 
* All W3C specs I have seen that define browser APIs use WebIDL to define the schema of those objects. (By WebIDL also mean the accompanying type descriptions like the one in @msporny's example).
* Like @ianbjacobs I'm not convinced of the value in putting any mention of JSON-LD in the browser API spec.
* If a JSON-LD context is defined such that the JSON objects that will be defined as the parameters for the browser API can be converted to be JSON-LD by simply adding a "@context" (and possibly "@type") attribute(s) then this can be documented in the messaging specification.

Put another way, implementors of the API (browsers) will have a familiar spec format with WebIDL and type descriptions to assist them. Developers of websites and payment apps will use the same schema description to build their API parameters, or their payment apps to consume the requests that they receive via the API. 

Anyone that wishes to use JSON-LD will be able to easily convert the JSON object to JSON-LD with a known (default) "@context" and "@type". 

Likewise I'd expect a website developer to be able to submit a JSON-LD object to the API as long as the form matches the schema defined in the browser spec (i.e. the JSON-LD document hasn't been compacted or normalised etc) and for the browser to simply ignore the JSON-LD stuff it doesn't care about (like any other elements it doesn't recognise) and pass these along.

The decision to use JSON-LD will ultimately sit with anyone that wants to define a payment method (and therefor the custom data they wish included in requests and responses). 

@ianbjacobs and @dlongley : If we agree on these points then I don't think we need to concern ourselves with error handling or adding custom data right now. JSON is very flexible and the only conformance criteria for browsers should be to support all of the mandatory elements and ignore and pass through anything unknown (which i believe to be a common pattern). If, as we develop a more concrete scheme for the objects, we discover that we need to set more rigorous processing rules then we can do that but I don't think that's required yet.

To illustrate my proposal, the browser API spec might define the required JSON object to look like this:
**This schema is nonsense, it's just for illustrative purposes so it's nice and small.**

```javascript
{
  "total" : {
    "currency" : "USD",
    "amount" : "10.00"
  },
  "methods" : ["https://paypal.com/", "https://bitcoin.org/"],
}
```
The following should still be considered valid by a conformant browser and the object passed to the payment app (i.e. out the back of the API) should look exactly the same.

```javascript
{
  "@context" : "http://w3.org/payments/",
  "@type" : "PaymentRequest",
  "total" : {
    "currency" : "USD",
    "amount" : "10.00"
  },
  "methods" : ["https://paypal.com/", "https://bitcoin.org/"],
}
```

The same applies for this:

```javascript
{
  "total" : {
    "currency" : "USD",
    "amount" : "10.00"
  },
  "methods" : ["https://paypal.com/", "https://bitcoin.org/"],
  "bitcoin_address" : "145b3dEskk1a7Uw4gWBdpa8NFEwbfz2MgT"
}
```
However, the following flattened version of the same object, although valid JSON-LD and equivalent (I think), would not be a valid API parameter.
```javascript
{
  "@context" : "http://w3.org/payments/",
  "@graph": [
    {
      "type" : "PaymentRequest",
      "total" : {
        "currency" : "USD",
        "amount" : "10.00"
      },
      "methods" : ["https://paypal.com/", "https://bitcoin.org/"],
    }
  ]
}
```

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