How should the message schemas for the payment request and response be defined? What is the extensibility story for the messages? #27
Comments
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). |
+1 |
|
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).
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.
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
changed the title
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.
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. |
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. |
|
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 |
That is exactly the goal. |
|
@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 |
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. |
|
@dlongley, I am not sure I expressed myself clearly. Would this work for you:
Ian |
|
@ianbjacobs wrote:
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 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. |
|
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 |
|
@ianbjacobs, here's a proposal that might work:
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). |
|
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 |
|
(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:
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."
Yes, that sounds consistent with my note above.
I don't think I agree with that because it requires something of processors
Then, if the custom data includes context and the application knows how to consume JSON-LD, Ian |
|
@ianbjacobs wrote:
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.
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. |
|
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 Here is a my proposal:
Ian |
|
Ian, Can you attempt to characterize what such a message would look like and why On Tue, Feb 2, 2016 at 1:20 PM, ianbjacobs notifications@github.com wrote:
-Shane |
|
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. |
@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:
I propose the following:
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 |
|
On Tue, Feb 2, 2016 at 2:39 PM, Adrian Hope-Bailie <notifications@github.com
Clearly APIs need some structure, and the W3C uses WebIDL for that most of Beyond this, I in general I think I can work with your conclusions. I will -Shane |
|
Can we get agreement on these points?
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? |
Ok.
I don't agree with that requirement because that would place an obligation on entities
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 |
|
@adrianhopebailie wrote:
+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).
-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, 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
+1
-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). |
|
I feel like I am in some weird debate from the 80s. Seriously. I swear we On Tue, Feb 2, 2016 at 3:52 PM, ianbjacobs notifications@github.com wrote:
Umm... I am not sure what sort of an onus/burden you think this is, but in
Error handling where? If the API has defined parameters, then those are
Hmm. I would object to that pretty strongly. We don't need to be —
-Shane |
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. |
|
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:
I do not feel strongly about this, but it seems to me safer to distinguish those two cases 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 Ian |
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 A compromise might be to say -- if you're extending via JSON-LD, then a |
|
You wrote:
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?
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? |
Yes, that's all that's needed. |
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. |
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): |
|
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 |
They are not.
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.
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. |
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.)
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."
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 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.
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?
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.
Perhaps that's an idea worth discussing more broadly:
Ian |
|
@ 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.
We agree that's a goal.
Yes.
Yes (at least I take your word for it).
I do not support requiring JSON-LD at this time in the Web Payment API for at least these reasons:
Instead, I support:
|
In my view, saying that all of the extensions go under a special "custom" property would do just that.
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.
This has to do with the next point...
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?
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 |
|
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.
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 was thinking rather organizing the JSON-LD as a layer on top of the others, like this:
Thus, if we have JS and HTTP specs that require JSON, the companion spec could say Ian |
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.
What errors are you worried about? Can you provide some use cases?
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'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. |
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:
+1
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
+1 So if we focus on the question at hand, specifically for the browser API:
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: {
"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/"],
}
]
} |
|
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 |
|
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. |
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. |
|
Thank you for providing whatever data you thing would be helpful to our discussion of API development. |
|
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 |
|
@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:
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? |
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
changed the title
|
Migrating to #27. |
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
The text was updated successfully, but these errors were encountered: