How should the message schemas for the payment request and response be defined? What is the extensibility story for the messages? #27

Closed
msporny opened this Issue Dec 6, 2015 · 48 comments

Projects

None yet

10 participants

@msporny
Member
msporny commented Dec 6, 2015

To accept a payment method, a merchant must know how to process the response from the Payment Request API. Should there be a base universal response format? If so, some payment instruments may need more information in the returned message to figure out if the payment was successful, how is this other information placed in there?

This is related to issue #25, Payment Method Identifier Registry.

Spec refs:
http://wicg.github.io/paymentrequest/specs/architecture.html#payment-request-api
http://web-payments.github.io/web-payments-messaging/#payment-instrument-registration

@msporny
Member
msporny commented Dec 6, 2015

Should there be a base universal response format

Yes, there should be a base request and response format for the Payment API. The base format should be in the Messaging specification. The base format should be JSON-LD to support a formal extensibility mechanism. The message format should not require special processing by the web developer or browser, and should avoid JSON-LD processing by the PSP and merchant unless some kind of significant data format validation/verification, like signature verification, is being performed.

The extensions to the request and response format should be documented in the payment method vocabulary/registry. The registry should be a living document under the control of the Web Payments IG. Optionally, JSON Schema could be linked from the registry and used to validate the messages and their extensions (this functionality would be optional).

@dlongley
Contributor
dlongley commented Dec 7, 2015

Yes, there should be a base request and response format for the Payment API. The base format should be in the Messaging specification. The base format should be JSON-LD to support a formal extensibility mechanism. The message format should not require special processing by the web developer or browser, and should avoid JSON-LD processing by the PSP and merchant unless some kind of significant data format validation/verification, like signature verification, is being performed.

+1

@adrianhopebailie
Collaborator

I would agree that the request and response message do need some standardized basic fields. They should provide a basic structure that payment method specific data can hang off.

It's debatable whether or not the response needs to be standardized since the content doesn't need to be interpreted by the browser or website and can simply be passed to whoever is able to interpret the responses that are sent for a specific payment method (probably the PSP).

The message format should not require special processing by the web developer or browser, and should avoid JSON-LD processing by the PSP and merchant unless some kind of significant data format validation/verification, like signature verification, is being performed.

Why use JSON-LD at all if the consumers don't need to process it as JSON-LD. That feels like a slippery slope where a developer, recognising that they are building a JSON-LD response, does so using features of JSON-LD that the PSP is not expecting and the PSP expecting a JSON with some specific characteristics gets something they can't process.

The extensions to the request and response format should be documented in the payment method vocabulary/registry. The registry should be a living document under the control of the Web Payments IG. Optionally, JSON Schema could be linked from the registry and used to validate the messages and their extensions (this functionality would be optional).

I worry about us proposing a system where an entity like the IG needs to maintain anything of significance over time. The basic message structure should be very simple and provide just enough for intermediaries in the flow (such as the payment mediator) to do their jobs.

Beyond that all of the message content will be specific to the payment method and has no need for standardisation.

@adrianhopebailie adrianhopebailie changed the title from Minimum necessary information for merchant to process payment to How should the message schemas for the payment request and response be defined? Feb 2, 2016
@adrianhopebailie
Collaborator

Yes, there should be a base request and response format for the Payment API.

There has been no opposition to this assertion, however there does not appear to be consensus on how this message schema should be defined. I have updated the title of the issue to focus on this question as it appears to be a fundamental difference between the two browser API proposals.

  • The Web Payments CG proposal defines the messages as un-typed objects and asserts that JSON-LD would be used to define the format of these messages.
  • The paymentRequest proposal defines the messages using WebIDL in the spec

There appears to be no precedent for a browser API to define un-typed parameters and I am not certain that the purported benefit of using JSON-LD, distributed extensibility, will be realized. (Browsers that implement the payments API will need to interpret the payment request object and will hard-code the expected message schema in their processing logic)

My suggestion would be for the payment request and response to be well-defined using WebIDL in either the browser API specification or a stand-alone message specification and for that schema to define extension points where custom payment method specific data is expected to be added.

The group may then decide to define a JSON-LD context or JSON Schema that aligns with the WebIDL message definition (alternative schema definitions for the same logical message object) which can be used for non-browser APIs or use cases (such as the HTTP API).

i.e. Define the payment request and response messages in WebIDL as the primary reference and then in other schema languages rooted in the WebIDL definition.

@dlongley
Contributor
dlongley commented Feb 2, 2016

The Web Payments CG proposal defines the messages as un-typed objects and asserts that JSON-LD would be used to define the format of these messages.
The paymentRequest proposal defines the messages using WebIDL in the spec

As long as we're not involving methods -- I see no reason why both of these can't be true. You could specify messages in JSON-LD format, limit them to a particular context for the browser API, and define the basic properties that are required for interop via WebIDL. I think we can get the best of both worlds without causing issues in either.

This sounds somewhat like what you propose, but I'm not sure if it's the same thing.

@ianbjacobs
Contributor

In my mind the question we need to answer is this: Do we have use cases where the data needs to live outside of the APIs we develop? If the answer is "no" then I believe the benefit of using JSON-LD is minimized and the cost of using it (lack of interest from developers that use of JavaScript APIs, and lack of support in browsers for the LD part) is predominant.

Another question I have is this: What if we defined a JSON format and then somebody send a blob of JSON-LD where the additional data that makes it JSON-LD would be ignored by a conforming processor and be treated as "private data" between the merchant and payment app. Would that work? Would it suffice for those who wish to send JSON-LD?

Ian

@dlongley
Contributor
dlongley commented Feb 2, 2016

Another question I have is this: What if we defined a JSON format and then somebody send a blob of JSON-LD where the additional data that makes it JSON-LD would be ignored by a conforming processor and be treated as "private data" between the merchant and payment app. Would that work? Would it suffice for those who wish to send JSON-LD?

That is exactly the goal.

@ianbjacobs
Contributor

@dlongley, if I understand you, you are saying "The standard doesn't need to require JSON-LD; it just needs to not forbid it." Can you tell me what changes would be necessary to the Google/Microsoft proposal so ensure that it does not "forbid" someone from passing JSON-LD?

Ian

@dlongley
Contributor
dlongley commented Feb 2, 2016

@ianbjacobs,

What if we defined a JSON format and then somebody send a blob of JSON-LD where the additional data that makes it JSON-LD would be ignored by a conforming processor and be treated as "private data" between the merchant and payment app.

I just wanted to point out that that format is JSON-LD. That's what it is and exactly what it was designed to do: be usable by developers who don't care about LD and also by developers that do.

There should be a basic message format that is reusable by different APIs. The Google/Microsoft proposal doesn't yet do this. If that message format is JSON-LD we can push innovation to the endpoints, as this is what has always worked for the Web. We don't want to force browsers to interpret LD or do anything with it if they don't want to. Again, that's the point of JSON-LD.

@ianbjacobs
Contributor

@dlongley, I am not sure I expressed myself clearly. Would this work for you:

  • To conform to the Web Payments API, one provides JSON.
  • The spec does not in any way prevent people from providing JSON-LD (which is JSON)
  • Therefore, parties can generate and consume JSON-LD when they want to.
  • But no conforming implementation of the API is required to recognize JSON-LD.

Ian

@msporny
Member
msporny commented Feb 2, 2016

@ianbjacobs wrote:

Do we have use cases where the data needs to live outside of the APIs we develop?

Yes, absolutely, here are a few from our use cases document (in the order that they appear):

https://www.w3.org/TR/web-payments-use-cases/#uc-pos-kiosk
https://www.w3.org/TR/web-payments-use-cases/#uc-email
https://www.w3.org/TR/web-payments-use-cases/#uc-machine-readability
https://www.w3.org/TR/web-payments-use-cases/#uc-vehicle

How will a kiosk present a machine-readable offer of sale? Certainly not only via a browser - in-store beacons, Bluetooth, NFC, are all possibilities here that require the "payment message / offer" to also exist outside of the browser environment. What extensible data model are we going to use to express offers? We can't go through and enumerate all of the bits that can be extended because by doing so, we're implicitly making the decision on which bits can't be extended.

https://www.w3.org/TR/web-payments-use-cases/#uc-subscription

How are the details of a subscription defined so that a software agent can remind you when a subscription is expiring? Certainly, a browsers isn't the only application that is going to do that subscription processing, is it? Don't we want to have a life agent that manages these subscriptions for us, reminding us when they're going to expire and auto-renewing them if we want to continue with the service? This data lives outside of the browser.

https://www.w3.org/TR/web-payments-use-cases/#uc-credentials

The Credentials CG work (along with 40+ organizations) are already well down the path of using JSON-LD because those messages /do/ live outside of the browser API and it's the only developer-friendly scalable mechanism. If our prediction is correct, and there will be significant interplay between the credentials and payments APIs in the future (loyalty card, coupons, proof of identity, etc.) then it would be good to align the data model and format of those messages with the payments messages. Both types of messages live outside of the browser API.

https://www.w3.org/TR/web-payments-use-cases/#uc-invoices

Invoices may be delivered/stored via the Payment API but processed via external software and systems like Quickbooks or Mint. We can't define what those invoices look like in the Web Payments WG, we have no idea what form they might take, but it's clear that there are certain corporate payment methods that would want to have invoices attached to payments, and where there payment messages would be archived outside of the browser for processing (via corporate accounting systems).

https://www.w3.org/TR/web-payments-use-cases/#uc-ubiquitous

We can't predict the way payment apps are expressed and some payment apps may include information in them that user agents may use in different ways. For example, some may take advantage of a secure element w/ a cryptogram/token embedded in the issued payment app description. This data may not live purely in the Browser API and may need to delegate some of the cryptogram data to a secure element or application (operating outside of the browser).

https://www.w3.org/TR/web-payments-use-cases/#uc-manual-selection

Websites could provide the payment instruments they accept as machine-readable data on a page before a purchase is started (they'll certainly do that for ecommerce offers). This would enable customers to narrow searches by the payment apps they want to use to make the purchase. This information would exist outside of the browser API.

https://www.w3.org/TR/web-payments-use-cases/#uc-kyc

KYC requirements vary from region to region, we can't specify every possibility in the WG and specifying this data should probably be undertaken by the regulators. A KYC credential may need to be attached to some payment messages and may be required to flow through the system, from the Browser API all the way to clearing and settlement (outside of the browser).

https://www.w3.org/TR/web-payments-use-cases/#uc-proofs

Proof of payments and proof of transaction would be included in the payment messages and would be sent to the merchant or PSP for processing. That is, most proofs would need to be transmitted outside of the Browser API to be processed by the merchant or PSP.

https://www.w3.org/TR/web-payments-use-cases/#uc-electronic-receipts

Some electronic receipts may be managed by the browser API but would eventually end up in a storage system deemed appropriate by the customer. navigator.payment.storeReceipt() would require the payment/receipt message to travel outside of the Browser API.

I hope this makes it clear that a number of the payment messages we are delivering will be affected by the use cases above and that those use cases clearly demonstrate that these payment messages will travel outside of the Browser API.

@ianbjacobs
Contributor

@ianbjacobs,

Thanks for the use cases list. I do not see that the above use cases relate to the scope of the current WG charter.

I realize I should have phrased my comment more carefully: what use cases for the browser API require the data to be reused by arbitrary processors outside of the browser API itself?

Ian

@msporny
Member
msporny commented Feb 2, 2016

@ianbjacobs, here's a proposal that might work:

  • The Web Payments API uses messages that look like JSON to the average Web developer (but are in-fact, JSON-LD - nothing is "undefined behavior" and the rules for extensibility are clear).
  • The spec does not require the browser to interpret the Web Payments API messages as JSON-LD (the behavior is hard-coded for the pieces that the browser has to process). This means that browsers can treat the bits of the JSON-LD that they use as plain 'ol JSON.
  • If a JSON-LD Context is not defined, one must be assumed (the Web Payments Version 1.0 JSON-LD Context).

This would mean that a web developer could express a payment request like this (for example):

var request = {
  type: 'PaymentRequest',
  description: 'Payment to ExampleMerch for widgets',
  acceptablePayment: {
    paymentMethod: 'https://visa.com/payment-methods#Visa',
    transfer: {
      amount: '4.35',
      currency: 'USD'
    }
  }
};

... it can be treated as regular JSON by Web Developers and the browser vendors (that is, they can hard-code to it without giving up on the extensibility story of JSON-LD).

@dlongley
Contributor
dlongley commented Feb 2, 2016

@ianbjacobs,

I think Manu's comment (#27 (comment)) should be the way we go about achieving JSON messages (which can really be JSON-LD) in the Browser API without Web developers or API implementers having to think about/do any LD processing at all. It is subtly different from your four points, but achieves the same higher level goals, IMO.

The main difference is that we'd be specifying how (if desired) you interpret a message as JSON-LD -- what you do is look for a @context and if not present, assume a default one. Otherwise we're saying the same thing: the message for the Browser API is JSON, it can definitely be interpreted as JSON-LD, but no conforming implementation of the API needs to do so.

@ianbjacobs
Contributor

@msporny,

(To clarify first: my goal on this thread is to focus on the JSON/JSON-LD question, not the details of the request message.)

You wrote:

The Web Payments API uses messages that look like JSON to the average Web developer (but are
in-fact, JSON-LD - nothing is "undefined behavior" and the rules for extensibility are clear).

I would rather it be: "The Web Payments API uses JSON. For some processors, it turns out it is also JSON-LD and those processors can consume it as such. But for conforming implementations of the API, it only needs to be known as JSON."

The spec does not require the browser to interpret the Web Payments API messages as JSON-LD
(the behavior is hard-coded for the pieces that the browser has to process). This means that browsers
can treat the bits of the JSON-LD that they use as plain 'ol JSON.

Yes, that sounds consistent with my note above.

If a JSON-LD Context is not defined, one must be assumed
(the Web Payments Version 1.0 JSON-LD Context).

I don't think I agree with that because it requires something of processors
related to JSON-LD. How about this instead:

  • The Web API spec defines the meaning of the terms that are used.
  • "Custom data" is designated as such explicitly; there is a well-defined way to designate "this is
    data for applications and must be left unchanged by conforming processors."
  • Everything else triggers an error. We need to look more closely at error handling in the sensitive
    case of payments.

Then, if the custom data includes context and the application knows how to consume JSON-LD,
then a conforming processor of JSON-LD will do the right thing.

Ian

@msporny
Member
msporny commented Feb 2, 2016

@ianbjacobs wrote:

I do not see that the above use cases relate to the scope of the current WG charter.

Some do, some don't. We need to make sure we don't /only/ look at the use cases in Phase I. The Web Payments IG has reviewed and agreed to place those use cases into our use cases document because they're an important part of the Web Payments ecosystem we're building. In short, just because something isn't in phase I doesn't mean it's a good idea to not design for it.

What use cases for the browser API require the data to be reused by arbitrary processors outside of the browser API itself?

Let me take the opposite approach that I took above and give a single example (there are more than just this one):

Take the Payment Request, for example. The assumption is that the browser API is going to send this message to a payment service processor web page of some kind. Let's assume the PSP is using HTTP. So, how does the PSP get the payment request message from the client-side code to the server-side code? I would hope that it serializes it as something JSON-like and sends it to the server-side code for processing. We could either require each PSP to create their own payment request serialization format, or they could re-use the JSON message that we have for the payment request.

The same holds for the payment acknowledgement. Where is that generated? It's probably generated on a server somewhere and then transmitted to the web payments browser API to be routed back to the merchant.

So, even in the most basic case, these messages travel outside of the Browser API.

@ianbjacobs
Contributor

@msporny,

Achieving broader interoperability is desirable, but is not free.

In your view, what is the degree of support by "regular Web developers" for JSON-LD in
Web applications?

Here is a my proposal:

  • Payment request data is JSON.
  • The API should not prevent parties that reach "private agreements" to use JSON-LD from doing so.
  • We continue to look for interoperability opportunities beyond the scope of this WG. It may be that
    parties are tired of reaching private agreement and want additional standards. For example, we
    have in our charter an optional deliverable to reach additional interoperability for data sent to
    credit networks. Let's work on that and then continue to pursue interoperability at other points
    in the flow.
  • If in the future we find that different parties agree to use JSON-LD specifically, then when those
    parties use the Web Payments API, they will no longer be using proprietary formats, they will
    be using open (JSON-LD-based) standards over the same Web API rails -- which don't themselves
    need to change to allow JSON-LD to flow over them.

Ian

@webpayments

Ian,

Can you attempt to characterize what such a message would look like and why
it would be superior to just using the existing dogfood that is JSON-LD? I
feel like you are just digging in your heels and saying no to JSON-LD as a
format when 1) it is well defined, 2) it is a W3C recommendation, and 3) it
would cost nothing to support for our current audience. I must be missing
something.

On Tue, Feb 2, 2016 at 1:20 PM, ianbjacobs notifications@github.com wrote:

@msporny https://github.com/msporny,

Achieving broader interoperability is desirable, but is not free.

In your view, what is the degree of support by "regular Web developers"
for JSON-LD in
Web applications?

Here is a my proposal:

  • Payment request data is JSON.
  • The API should not prevent parties that reach "private agreements"
    to use JSON-LD from doing so.
  • We continue to look for interoperability opportunities beyond the
    scope of this WG. It may be that parties are tired of reaching private
    agreement and want additional standards. For example, we have in our
    charter an optional deliverable to reach additional interoperability for
    data sent to credit networks. Let's work on that and then continue to
    pursue interoperability at other points in the flow.
  • If in the future we find that different parties agree to use JSON-LD
    specifically, then when those parties use the Web Payments API, they will
    no longer be using proprietary formats, they will be using open
    (JSON-LD-based) standards over the same Web API rails -- which don't
    themselves need to change to allow JSON-LD to flow over them.

Ian


Reply to this email directly or view it on GitHub
#27 (comment).

-Shane

@vkuntz
Collaborator
vkuntz commented Feb 2, 2016

All, I think that ISO 20022 could potentially solve this issue. Within ISO 20022, there are 3 levels of specifications: the business level, the logical level and the technical level. All discussion in this thread are at the technical level, which I believe is not the correct level of discussion today and is generated from the logical level in ISO 20022 through automated procedures. The most important aspect to a correct design is that the logical level contains all relevant information, which allows to generate in any format that you would like to: XML, ASN.1 as today already supported in ISO 20022, but the standard itself allows for the possibility of future technical implementations. JSON could be a good candidate. As said, the key to sucess is to have the correct logical design. The last step is up to the experts to agree on the correct translation from the logical layer to the physical/technical layer.

@adrianhopebailie
Collaborator

Can you attempt to characterize what such a message would look like and why it would be superior to just using the existing dogfood that is JSON-LD?

@halindrome We can't define a browser API that simply takes an untyped object as its parameter and then define the schema for that object in JSON-LD. Browser APIs take well-defined objects as parameters. Anything else is a non-starter. So, WebIDL is a bare minimum encoding. What Ian is suggesting is that taking a JSON object that conforms to a WebIDL definition and adding a context and type is a trivial and will produce compliant JSON-LD if the context is defined to align with the WebIDL definition.

@vkuntz 👍 - as you correctly point out we are defining the technical level (the encoding) because this is the level that will be required for the browser API. I think the group acknowledges that the logical message schema is yet to be finalized but that this issue is a lingering difference between the two proposals so it will help us progress if we can resolve it. (Correct me if I am wrong)

From the discussion I understand the requirements to be:

  • A request (and response) object (a Plain-Old-Javascript-Object) with a well defined schema that is passed to (and returned by) the browser API
  • Easy translation between the POJO object passed to (returned by) the browser API and a JSON-LD encoded message that may be passed outside of the browser's execution environment (example: via an HTTP API)
  • A mechanism for developers to extend both the POJO object and it's JSON-LD equivalent to add custom data for their needs (example: payment method specific extensions) without altering the elements of the message schema that are used by the browser internally.

I propose the following:

  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
  2. 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)
  3. The definitions will specify appropriate optional attributes that can be used by developers to carry custom data such as payment method specific data.
  4. 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.
  5. Conformant browsers will be expected to ignore and pass on any attributes that are not defined in the specification.
  6. 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).

I consider the definition of the JSON-LD context to be tightly tied to the definition of the HTTP API so I expect this to be done later, in conjunction with this work. I'd like to say the group WILL define this JSON-LD context but I don't want to confuse a discussion around encoding formats for the browser API with a discussion around other deliverables

@webpayments

On Tue, Feb 2, 2016 at 2:39 PM, Adrian Hope-Bailie <notifications@github.com

wrote:

Can you attempt to characterize what such a message would look like and
why it would be superior to just using the existing dogfood that is JSON-LD?

@halindrome https://github.com/halindrome We can't define a browser API
that simply takes an untyped object as its parameter and then define the
schema for that object in JSON-LD. Browser APIs take well-defined objects
as parameters. Anything else is a non-starter. So, WebIDL is a bare minimum
encoding. What Ian is suggesting is that taking a JSON object that conforms
to a WebIDL definition and adding a context and type is a trivial and will
produce compliant JSON-LD if the context is defined to align with the
WebIDL definition.

Clearly APIs need some structure, and the W3C uses WebIDL for that most of
the time. Perfect. But the title of this issue was "How should the
message schemas for the payment request and response be defined?" I
concluded from the title and from the initial issue description (written by
@msporny) that the topic was in relation to messaging, not exclusively to
parameters to the browser API. I agree that it is often the case that you
can find parameters to an API in a message (or transform API parameters
into a message). I assumed from the debate that we were discussing the
higher level nature of messaging, or of message encapsulation, not
exclusively how those messages and their parameters are sent into and
conveyed out of a browser API. If I misunderstood, I apologize.

Beyond this, I in general I think I can work with your conclusions. I will
study them further.

-Shane

@dlongley
Contributor
dlongley commented Feb 2, 2016

Can we get agreement on these points?

  • Implementers of the Browser API (browsers) must not have to do any JSON-LD processing.
  • It must be possible to interpret messages passed into the Browser API as JSON-LD.
  • Implementations must ignore (and pass through) unrecognized message data.

If so, I believe the remaining decisions have to do with what guidance the spec provides on how payment apps should interpret messages as JSON-LD (if desired). @msporny has proposed a "default context" mechanism. That mechanism makes sense to me, but @ianbjacobs suggested that it would "require something of processors related to JSON-LD". It seems like it shouldn't, so isn't this just a matter of getting the language right?

@ianbjacobs
Contributor

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

Ok.

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

I don't agree with that requirement because that would place an obligation on entities
who are not party to the API. Instead, I think that the API must not prevent the use of
JSON-LD. (It's not clear to me that the spec needs to be explicit about that point, but
by design it should not prevent the use of JSON-LD.)

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

I don't agree with that yet because I don't think we've had enough discussion about error handling.

I do think we should consider an attribute such as "custom" and require the processor to
leave custom data untouched.

@msporny
Member
msporny commented Feb 2, 2016

@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):


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

@webpayments

I feel like I am in some weird debate from the 80s. Seriously. I swear we
had this same discussion in the ANSI C (X3J11) work in 1986. Anyway, some
comments inline:

On Tue, Feb 2, 2016 at 3:52 PM, ianbjacobs notifications@github.com wrote:

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

Ok.

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

I don't agree with that requirement because that would place an obligation
on entities
who are not party to the API. Instead, I think that the API must not
prevent the use of
JSON-LD. (It's not clear to me that the spec needs to be explicit about
that point, but
by design it should not prevent the use of JSON-LD.)

Umm... I am not sure what sort of an onus/burden you think this is, but in
its basest form JSON-LD is JSON. Especially with, as @msporny suggested, a
default context. Surely JS objects are not too much work for developers?
And JSON is well understood. It is a descriptive, extensible, inclusive
grammar that maps most other languages and their datatypes with little
effort.

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

I don't agree with that yet because I don't think we've had enough
discussion about error handling.

Error handling where? If the API has defined parameters, then those are
the parameters that are processed. They have limits? Specify them.
Behaviors at the edges? Outside of the edges? Within the domain? Specify
that too. End of story. Additional data is cargo. The error handing is
only on defined parameters. Otherwise we say "Any data other than the
parameters defined here is passed through" or whatever. If you want to
allow vendor extensions that are NOT passed through, define a proprietary
extension point for that... e.g. "x_*". I won't object.

I do think we should consider an attribute such as "custom" and require
the processor to
leave custom data untouched.

Hmm. I would object to that pretty strongly. We don't need to be
proscriptive to be interoperable. Just be descriptive about the things we
care about, and permit the rest. Then it will grow / expand in subsequent
phases or organically in the wild or both. Everyone wins.

Reply to this email directly or view it on GitHub
#27 (comment).

-Shane

@dlongley
Contributor
dlongley commented Feb 2, 2016

@ianbjacobs,

I do think we should consider an attribute such as "custom" and require the processor to
leave custom data untouched.

I strongly recommend against trying to stuff everything we haven't thought of into a box marked "custom". There are a lot of things we haven't thought of. Instead, let's specify what we have thought of and leave the rest alone.

Furthermore, I think we should be specific about a best practice for extending: i.e. let's specify an extension mechanism that is machine-readable, has decentralized, self-discoverable semantics, has a syntax that already works as regular JSON, and is a W3C Recommendation: JSON-LD. We can be clear about how people ought to interpret messages as JSON-LD -- should they be interested in using this mechanism. If they aren't, that's fine too.

I realize this work is phased and we're trying to keep things narrowly scoped. That doesn't mean we shouldn't be clear about how to extend things so we can get to the future we want in later phases and beyond. For example, I'm imagining a future where people could publish payment request messages (or "offers") on websites using JSON-LD. Then search engines could consume this machine-readable data (Google is already doing this with JSON-LD). Then people could search for what they're looking for and click it -- which would drop that message right into the Browser API and they could complete their purchase.

They could similarly drop that same message into an app that uses the HTTP API and send it where it needs to go. Or into some other API. The point is that you can use the same message across many APIs and you can get these messages in a variety of different ways.

I think it's important that we provide some guidance on how this can be done -- even if that's an extremely minimal amount of guidance during Phase I, i.e. there's a "default" context for people who want to use messages as JSON-LD.

@ianbjacobs
Contributor

@halindrome,

I think there is a universal expectation to use JSON for messages. There is not, however, consensus to use JSON-LD. To foster adoption, I prefer a path that imposes the fewest constraints on the ecosystem. Therefore, I think we should define conformance to JSON, and allow that JSON to be JSON-LD where parties want to exchange JSON-LD.

The reason I mention an attribute like "custom" is to distinguish two cases:

  • Custom data that should be left alone in processing
  • Errors

I do not feel strongly about this, but it seems to me safer to distinguish those two cases
where we can. I would like to hear whether something like "custom" is a common pattern
in API design. I skimmed the API cookbook [1] but didn't see it there. (I didn't read the
document closely, so it might be in there somewhere.)

You wrote:

"Just be descriptive about the things we care about, and permit the rest. "

I agree. But "custom" says "We care enough to tell processors to leave this
data alone and not deal with it in some other way that might be processor-dependent."

Ian

[1] https://www.w3.org/TR/api-design/

@dlongley
Contributor
dlongley commented Feb 3, 2016

@ianbjacobs,

I agree. But "custom" says "We care enough to tell processors to leave this
data alone and not deal with it in some other way that might be processor-dependent."

I expect there to be more than one place where data can be extended. So we'd end up sprinkling "custom" bits just about everywhere. Either that, or people may end up having to duplicate bits of the payment message in the custom section, leading to bloat and potentially errors or confusion.

A compromise might be to say -- if you're extending via JSON-LD, then a @context must be present, which is also a trigger that means you can then extend however you want (with the obvious caveat that you can't stomp on well-defined properties). If no @context is present, you can throw errors for unrecognized properties.

@ianbjacobs
Contributor

@dlongley,

You wrote:

I expect there to be more than one place where data can be extended. So we'd end up sprinkling "custom" bits just about everywhere. Either that, or people may end up having to duplicate bits of the payment message in the custom section, leading to bloat and potentially errors or confusion.

Maybe. And we should keep discussing the use cases. As I said I don't feel strongly about that particular approach; I just think it's worth considering explicitly the case of "leave untouched" versus errors/mistakes. Also, is there some reason why all the custom bits can't be put in one place?

A compromise might be to say -- if you're extending via JSON-LD, then a @context must be present, which is also a trigger that means you can then extend however you want (with the obvious caveat that you can't stomp on well-defined properties). If no @context is present, you can throw errors for unrecognized properties.

It seems to me that if @context is present, then any app that handles JSON-LD will know what to do. Therefore, if you are extending with JSON-LD, the Web API specification doesn't need to say anything because the conformance requirement is on the app, not the API implementation.

I don't know JSON-LD well enough. How does any processor know that the payload is JSON-LD? Does encountering @context suffice?

@msporny
Member
msporny commented Feb 3, 2016

How does any processor know that the payload is JSON-LD? Does encountering @context suffice?

Yes, that's all that's needed.

@msporny
Member
msporny commented Feb 3, 2016

In your view, what is the degree of support by "regular Web developers" for JSON-LD in
Web applications?

To get some data behind the "level of support", I've asked @danbri (of Google's schema.org team - which uses JSON-LD) to comment on this particular item.

@msporny
Member
msporny commented Feb 3, 2016

I don't know JSON-LD well enough.

Watch the first three videos on this site if you want to get a basic understanding of JSON-LD (each one is roughly 12 minutes in length):

http://json-ld.org/learn.html

@ianbjacobs
Contributor

@msporny,

I think the use cases are different. If I understand correctly, schema.org is for people to publish data that can be discovered and processed on the open web, when you need to be able to distinguish vocabularies and avoid name conflicts. That is not the sort of scenario we are talking about in this browser API.

Ian

@msporny
Member
msporny commented Feb 3, 2016

I think the use cases are different.

They are not.

schema.org is for people to publish data that can be discovered and processed on the open web

Yes, like anything related to electronic commerce. For example, products for sale for a certain price (which is basically what a payment request is).

The online sales funnel typically starts with a Google search for a product (a payment request marked up as JSON-LD, for example), leading to the merchant website, and then the execution of payment. We can use almost the exact same common message for the starting step and the ending step to drive sales from search all the way through to payment.

That is not the sort of scenario we are talking about in this browser API.

The assertion in this thread is that there are common messages that can be used both in the browser API and outside of the browser API. The Web Payments CG specs demonstrate that it is possible to do so. schema.org shows us that it's then possible to take those common messages and drive search traffic to a merchant site and use that same message to execute the payment.

If we just stick to WebIDL trapped in a browser API, we don't get any of those benefits.

If, instead, we want those benefits, all we have to do is add a single @context line to a JSON/Javascript object.

@ianbjacobs
Contributor

@dlongley,

I strongly recommend against trying to stuff everything we haven't thought of into a box marked "custom". There are a lot of things we haven't thought of. Instead, let's specify what we have thought of and leave the rest alone.

I have a specific goal in mind: tell the processor to leave some data untouched, so that a processor does not treat it as an error. I am not trying to "stuff everything we haven't thought of in a box." I only am thinking of one scenario we should consider. (Again, "custom" may not be the right approach; I am looking for help to understand whether this is a pattern.)

Furthermore, I think we should be specific about a best practice for extending: i.e. let's specify an extension mechanism that is machine-readable, has decentralized, self-discoverable semantics, has a syntax that already works as regular JSON, and is a W3C Recommendation: JSON-LD.

It is one thing to say "You must use JSON-LD for extensions" and another to say "Please consider using JSON-LD if you want integration into the world of linked data."

We can be clear about how people ought to interpret messages as JSON-LD -- should they be interested in using this mechanism. If they aren't, that's fine too.

If the content is JSON-LD and can be recognized as such, conforming processors of the data will do the right thing. That is not something the Web API spec needs to say (at least I have not been convinced yet we need to say it since the data seems to be self-describing by virtue of the presence of @context).

I realize this work is phased and we're trying to keep things narrowly scoped. That doesn't mean we shouldn't be clear about how to extend things so we can get to the future we want in later phases and beyond.

I believe we should not today tell people there is only one way to extend the data. We should take pains so that we don't prevent people from trying different approaches. In the future we may find that further standardization on a particular approach will further interop. I do not support choosing a specific extension mechanism (other what what you get from plain JSON) without more experience.

For example, I'm imagining a future where people could publish payment request messages (or "offers") on websites using JSON-LD. Then search engines could consume this machine-readable data (Google is already doing this with JSON-LD). Then people could search for what they're looking for and click it -- which would drop that message right into the Browser API and they could complete their purchase.

It seems to me that a Web API spec requiring conformance to JSON would do the right thing (provided the payment app knows how to handle the data you feed it). Am I mistaken?

They could similarly drop that same message into an app that uses the HTTP API and send it where it needs to go. Or into some other API. The point is that you can use the same message across many APIs and you can get these messages in a variety of different ways.

As I've mentioned elsewhere on threads, I share the goal of avoiding divergence between the JS and HTTP APIs. I do not consider it a requirement that the APIs use the same data (and there may be good reasons not to, such different security requirements in different ecosystems). But I agree it would be good to avoid unnecessary divergence.

I think it's important that we provide some guidance on how this can be done -- even if that's an extremely minimal amount of guidance during Phase I, i.e. there's a "default" context for people who want to use messages as JSON-LD.

Perhaps that's an idea worth discussing more broadly:

  • The Web API spec requires JSON (not JSON-LD) but does not prohibit the data from being JSON-LD. (Let's assume for now that can be done.)
  • The WPWG publishes a companion spec that says "If you want to use JSON-LD, here's how you do it."

Ian

@ianbjacobs
Contributor

@ msporny,

I wrote: "schema.org is for people to publish data that can be discovered and processed on the open web"

You wrote: "Yes, like anything related to electronic commerce."

I don't believe that is the case. Some things (e.g., offers, as you point out) are published on the open Web. But initiating payment processing is not.

The assertion in this thread is that there are common messages that can be used both in the browser API and outside of the browser API.

We agree that's a goal.

The Web Payments CG specs demonstrate that it is possible to do so.

Yes.

schema.org shows us that it's then possible to take those common messages and drive search traffic to a merchant site and use that same message to execute the payment.

Yes (at least I take your word for it).

If we just stick to WebIDL trapped in a browser API, we don't get any of those benefits.

I do not support requiring JSON-LD at this time in the Web Payment API for at least these reasons:

  • It favors an extensibility mechanism without experience to understand whether the ecosystem wants to use that extensibility mechanism.
  • I do not foresee that we will get consensus in the W3C community to require JSON-LD, which will slow the progress of the group.

Instead, I support:

  • Conformance based on JSON, which is widely adopted and where I doubt there will be any strong disagreement.
  • The API allows (but does not require) JSON-LD (or any other JSON compatible format) so that those parties that wish to use it may do so.
  • Discussion to see whether there is interest in publishing a spec on best practice if you happen to use JSON-LD.
@dlongley
Contributor
dlongley commented Feb 3, 2016

@ianbjacobs,

I believe we should not today tell people there is only one way to extend the data.

In my view, saying that all of the extensions go under a special "custom" property would do just that.

We should take pains so that we don't prevent people from trying different approaches.

I agree, which is why I think the best approach is to simply define what is known and used by the API and leave the rest alone. We don't need to tell people that they have to put all of their extensions in a special spot -- as that creates limitations on a particular extension approach, namely the first suggested extension approach that is under consideration right here in this issue.

I expect people to want to be able to add their own properties to payment method information, to the top-level payment request, to ... whatever. Telling them that they can't decorate the payment request as they see fit and, instead, they must all use a special "custom" box is definitely limiting certain extension approaches.

It seems to me that a Web API spec requiring conformance to JSON would do the right thing (provided the payment app knows how to handle the data you feed it). Am I mistaken?

This has to do with the next point...

As I've mentioned elsewhere on threads, I share the goal of avoiding divergence between the JS and HTTP APIs. I do not consider it a requirement that the APIs use the same data (and there may be good reasons not to, such different security requirements in different ecosystems). But I agree it would be good to avoid unnecessary divergence.

Do you agree then that we should start from a point of convergence and then only diverge as needed? That is my view. The Web Payments CG spec also reflects this approach. Perhaps our most recent approach in this discussion has been a bit backwards -- why not restart by assuming we can use the same messages and then only deviate from that if we really need to?

The WPWG publishes a companion spec that says "If you want to use JSON-LD, here's how you do it."

I'm ok with that, in fact, I think that spec should be the messaging spec. The Browser API spec can reference that spec (as can the HTTP API spec). That's the design we've gone with in the Web Payments CG specs. For example, the Browser API could have a small section that says that you can "transform" the messages used in the Browser API spec to match the Messaging spec by adding the default @context.

@ianbjacobs
Contributor

@dlongley,

The goal of "custom" was not to tell people how to write their extensions. Only to tell browsers: "I am explicitly asking you to leave this untouched."

If you have processing rules that say "Leave everything you don't understand untouched" then I don't know how you detect error cases.

You asked: "Do you agree then that we should start from a point of convergence and then only diverge as needed? ". No, that's not how I would start. But I have not tried to do this so I don't know how my approach(es) would fare.

Perhaps our most recent approach in this discussion has been a bit backwards -- why not restart by assuming we can use the same messages and then only deviate from that if we really need to?

For the time being, we have resolved to serialize the development of the APIs, so my expectation is to come to ground first on the browser API, then apply what we've learned to the HTTP API. That's not the only way imaginable, but that's what we've decided.

I'm ok with that, in fact, I think that spec should be the messaging spec.

I was thinking rather organizing the JSON-LD as a layer on top of the others, like this:

  • Here are the specs that define the Web Payments API. (However that's done with 1 to N specs).
  • Here's a companion spec that says how you use the Web Payments API with JSON-LD.

Thus, if we have JS and HTTP specs that require JSON, the companion spec could say
how to use both of those with JSON-LD.

Ian

@dlongley
Contributor
dlongley commented Feb 3, 2016

@ianbjacobs,

The goal of "custom" was not to tell people how to write their extensions. Only to tell browsers: "I am explicitly asking you to leave this untouched."

I understand that's not the goal, but it has that effect. It says that an extender can't decorate the payment request as they see fit, essentially making "annotations"/adding properties along side various parts of the standard request. I consider having the freedom to do that to be a more powerful and developer-friendly/author-friendly extension approach.

If you have processing rules that say "Leave everything you don't understand untouched" then I don't know how you detect error cases.

What errors are you worried about? Can you provide some use cases?

For the time being, we have resolved to serialize the development of the APIs, so my expectation is to come to ground first on the browser API, then apply what we've learned to the HTTP API. That's not the only way imaginable, but that's what we've decided.

Yes. That doesn't meant that we shouldn't keep this stuff in mind as we go -- it just means that getting the alignment right may be more difficult and require more iterations. I got the impression that the parties that may benefit most from alignment (retail, merchants, banks, etc.) don't have adequate technical representation. Therefore, the decision seemed to be made more out of a desire to get along, keep momentum, and some indifference (for those parties only interested in the Browser API).

I was thinking rather organizing the JSON-LD as a layer on top of the others, like this:

  • Here are the specs that define the Web Payments API. (However that's done with 1 to N specs).
  • Here's a companion spec that says how you use the Web Payments API with JSON-LD.

Thus, if we have JS and HTTP specs that require JSON, the companion spec could say
how to use both of those with JSON-LD.

I'm not convinced that's the best way to do it, but I do see it as a potential fallback option. I'd rather us just use a format that can be used as regular JSON but also has a well-defined extension mechanism that can be safely ignored (JSON-LD). That mechanism is recommended for extensions as it will achieve the best interoperability, but it is not required (you can do anything provided you don't mess with well-defined properties). I would think that could be just as acceptable to those that don't care about LD and don't want to deal with any LD processing, but would give clearer guidance on how to best write extensions.

@adrianhopebailie
Collaborator

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

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

{
  "@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:

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

{
  "@context" : "http://w3.org/payments/",
  "@graph": [
    {
      "type" : "PaymentRequest",
      "total" : {
        "currency" : "USD",
        "amount" : "10.00"
      },
      "methods" : ["https://paypal.com/", "https://bitcoin.org/"],
    }
  ]
}
@danbri
danbri commented Feb 3, 2016

I will try to get some more detailed statistics published from Google, but as a first approximation I think I can reasonably share that we are seeing JSON-LD on several million sites. Prior to https://googlewebmastercentral.blogspot.co.uk/2014/09/improved-sitelinks-search-box.html it was relatively obscure, except for use in email e.g. see https://developers.google.com/schemas/formats/json-ld . Since JSON-LD only became a W3C Recommendation in January 2014 this is pretty healthy adoption.

I should also mention that while JSON-LD is increasingly favoured as a preferred syntax (over microdata/rdfa) for many Google features/products, there are some for which Microdata continues to be the preferred format. Since schema.org is defined in a syntax-neutral manner this is a relatively minor complication.

See also https://developers.google.com/structured-data/ -> https://developers.google.com/structured-data/rich-snippets/products -> https://support.google.com/merchants/answer/6069143?hl=en

danbri@google.com

@dprophet
dprophet commented Feb 3, 2016

Message formats should be decoupled from the API.

Payment data structures are already well defined in the industry. Message formats for financial services are ISO 20022 XML data structures.

The payment agent process should be responsible to construct the data structures and format from the API calls.

Model the work flow and API choreography of a payment request. If the browser community reinvents financial services data structures and message formats it will require 10's of 1000's of development man-years to adjust 30 years of legacy infrastructure to a different data structure.

Follow ISO 20022. Everything you need is already there.

Out of scope, but as I have mentioned many times, ISO 20022 are normally unsecured and travel over private pipes between institutions. Applying security required in an open hostile network like the internet will require changes to wire formats.

This security efforts should be more payment agent specific and not worried about at the W3C Browser API specification level. A Distributed Ledger Technology will require a very different payment agent.

@dlongley
Contributor
dlongley commented Feb 3, 2016

@msporny,

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

This is just another way of saying "data model". ISO 20022 follows the same layered approach that JSON-LD does -- JSON-LD is just a syntax that lets you carry the data model in JSON. With ISO 20022, there is a data model (logical message schema) that is typically carried using an XML syntax, but it could be carried via another syntax. JSON-LD is a natural fit for modeling ISO 20022 messages in JSON.

@ianbjacobs
Contributor

@danbri,

Thank you for providing whatever data you thing would be helpful to our discussion of API development.
Ian

@obkhan
obkhan commented Feb 4, 2016

@All

I work for Wells Fargo, this response is in my own personal capacity.

At Wells Fargo, we have been considering leveraging JSON-LD.

This great w3c standard can be used as reference to neatly structure a JSON entity from conceptual metadata management all the way through implementing end-to-end applications.

To that end, we plan on leveraging work products from EDM Council’s Financial Industry Business Ontology to have common vocabulary for interchange, not only for web payments but for various business entities. JSON-LD allows us to have context in our JSON and tie back these taxonomies so the data can be governed with defined lineage. There are no other JSON standards today that provide the same tie-in capability with enterprise schemas and ontologies.

This w3c standard supports this in a way that uses the existing web infrastructure as the widely popular JSON format by only adding context.

We are very interested and following work already done with JSON-LD with Web Payments, and look forward to seeing further evolution and refinement.

Omar Khan
TOG – Information Services
Innovation Group
omar.khan@wellsfargo.com
Office 804-398-6682 | Cell 804-405-1328
3829-3855 Gaskins Rd | Richmond, Va, 23233 | MAC R3485-010

@msporny
Member
msporny commented Feb 7, 2016

@adrianhopebailie @ianbjacobs @shepazu,

@dlongley and I have tried to formulate all of the discussion in this thread into a set of edits on the Web Payments CG Browser API. We just published a new version of the Web Payments CG Browser API with the following changes:

Hopefully, this demonstrates that:

  • @dlongley and I are monitoring the discussion and are responsive to changing the Web Payments CG specs based on the Web Payments WG discussion (even if we disagree with the direction).
  • The Web Payments WG actually does have editors that will make a best effort at making spec edits if we have consensus from the group. I believe @zkoch and @adrianba are trying their best as well, it's just that the group hasn't made many decisions yet, so the editor's and implementers are left to sort of stab in the dark based on input from a minority of group members and see what happens.

The latest spec can be found here (if you see 9 ReSpec errors in red at the top, reload - one of the Javascript libraries we pull in is loading from a site that's experiencing some issues right now):

https://wicg.github.io/web-payments-browser-api/

Are these changes enough to resolve this issue? If not, what further changes are required?

@melvincarvalho

lack of interest from developers that use of JavaScript APIs

FYI: I just wanted to add a data point that there is not a lack of interest from developers in wanting to use JSON LD with payments. At least not from some developers. Plain old JSON doesnt provide enough unexpected reuse, interoperability or extensibility, to get me excited enough to volunteer an implementation, but I will certainly be keen to create web payments implementations based on JSON LD.

@msporny msporny changed the title from How should the message schemas for the payment request and response be defined? to How should the message schemas for the payment request and response be defined? What is the extensibility story for the messages? Feb 18, 2016
@msporny
Member
msporny commented Mar 14, 2016

Migrating to #27.

@msporny msporny closed this Mar 14, 2016
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment