Link to registry of W3C-published short strings

[ianbjacobs]

The PMI spec says:

"W3C expects to publish a small number of payment method specifications that define abstractions across similar payment methods (such as credit card payments, tokenized payments, or credit transfers)....W3C expects to mint these strings in payment method specifications published by the Web Payments Working Group."

I propose that we include a link to a WG-managed registry of W3C-published short strings. That might be as simple as a listing on the WG home page.

[zkoch]

Ian, can you take a stab at this?

[ianbjacobs]

At the FTF meeting Marcos proposed an alternative:

• Include the list of short strings dynamically in the specification in an informative note.

I like that idea because I think it will be easier to maintain the list over time if it is near the specification itself (in the same directory on w3.org). There might be some concern about dynamically changing specification content, but the concern is minimized by the fact that this would be in an informative note. Here is some text for consideration (not focused on respec markup) that would follow the intro paragraph of section 4:

Informative Note: As of , the Working Group has formally published the following payment method specifications: * Basic Card Payment with short string "basic-card". This list may be updated in place from time to time.

(Include the list itself via JS.)

Does that work?

Ian

[adrianhopebailie]

The note should also list specs in progress that the WG has agreed to work on (like the tokenization spec). These should be marked as experimental.

[ianbjacobs]

I am not enthusiastic about linking to pre-published specs.

Ian

[adrianhopebailie]

I am VERY enthusiastic 😄

If we publish the spec with no indication that there will be more than one browser supported PMI or even a hint at where to find information on what is being developed then we are knowingly withholding valuable information from developers.

What is the risk of providing this information?

[ianbjacobs]

I don't want to start to advertise short strings that people might start to use based on pre-published work. Our current experience is a great example. We are working on tokenized card payment. The spec as-is makes sense and people could start to use it. EXCEPT that as soon as we shared it with the WG, the WG said "Let's do something completely different!".

I think that if we are confident enough to publish a FPWD of a Note, then I'm ok to advertise the short string. But before that I think the risks are too great of accidental deployment.

Ian

[adrianhopebailie]

I think that if we are confident enough to publish a FPWD of a Note, then I'm ok to advertise the short string. But before that I think the risks are too great of accidental deployment.

Agree this should be a curated list and not include any and all work we are doing only those the WG has consensus to take up. Minimum requirement should be that the WG has created a dedicated repo for the spec so that developers can convene around the work and hopefully contribute to it.

Publishing a list of experimental short strings with links to the in-progress specs seems like a very effective way to get wide input on these.

As a sidenote, this is another mechanism by which the WG is unintentionally making itself a gatekeeper for new payment methods that wish to be published in this way. If we're going to be overly restrictive about how PMIs get published in this spec then we should not publish them in the spec and stick to simply registry as discussed previously.

[ianbjacobs]

While I like mechanisms to get input, I don't believe this will be an effective one. Published W3C specifications by design do not change. I do not think this will be a place people go to learn about up-and-coming payment method specs. We should be advertising that work on the WG site.

Why, then, you may ask, put this list there at all? Because of the persistence policy associated with W3C specifications. We can give people a reliable URL and assure some maintenance of the data over time. But that doesn't mean this place needs to be the only place we talk about up-and-coming payment method specs.

So I would like to address your requirement for advertising and getting input through some other mechanism, and where that other mechanism gives us a lot more room to be explicit about status of specs, etc.

Ian

[marcoscaceres]

Started working on this. @ianbjacobs, will use your proposed structure from https://github.com/w3c/webpayments-method-identifiers/issues/26#issuecomment-295483513

[marcoscaceres]

@ianbjacobs we have a few options... we can make this dynamically update via XHR or we can get ReSpec to include the registry on each generation... If we go the ReSpec path, we can set up auto publish, like we do with the Payment Request spec.

[ianbjacobs]

If I understand correctly, the ReSpec option has the slight advantage of being static (since the list won't change often).

[marcoscaceres]

err... Payment Request spec, I mean. Fixed above.

Of course, the drawback with the ReSpec approach is that we need to update both a JSON file and republish the spec... with the JSON only solution, we still need to find a way of keeping the JSON file in sync on the w3c server... so, both solutions are almost the same. Problem is when we reach REC, and if we want to keep auto-publishing or not. The XHR solution, as you pointed out, gets around the problem.

Correct about the ReSpec solution - it is static.

[marcoscaceres]

Anyway, think about it and let me know... both solutions basically use the same code so happy to do either.

[ianbjacobs]

My gut suggests it is better to optimize for performance than maintenance here. We just need to document clearly what has to happen when we add a shortname + link to the JSON.

Thanks!

Ian

[adrianhopebailie]

Please can we use the latter approach.

These are specifications that people are developing against. Nobody wants them to change under their feet or have weird things happen when they download the spec to use offline.

A little extra effort from the editors seems the right choice vs a spec that COULD change due to external factors.

[ianbjacobs]

@adrianhopebailie wrote:

"Please can we use the latter approach."

I think you mean "republish a static version after edits" which I agree with.

However, it occurs to me that if we republish other parts of the spec at the same time, that might lead to unexpected other changes, so that's a disadvantage to this approach.

Ian

[marcoscaceres]

Ok, I was thinking about this some more, and if we are just going to go the static-autopublish route, then we might as well just add things directly to the document without any JSON file (as the JSON file would just be transformed into HTML anyway... no need for any indirection then).

I'll add basic card, allowing us to close this.

[marcoscaceres]

This is now in the spec