Re: Spec-Ops Comments on Web Payments Core Messages 1.0

On 04/28/2016 09:41 AM, Shane McCarron wrote:
> I do not require these comments to be resolved prior to migration
> into the web payments working group.

Hey Shane, thanks for the thorough review. These are responses to your
comments as I make changes to the document.

> As an aside, I appreciate the data modelling approach that describes
> the model in prose, then shows representations in multiple modelling 
> grammars.  There are A LOT of ways to express a data model.  With my 
> testing hat on, it would be good to have normative definitions for
> (at least) JSON Schema so that messages can be easily evaluated.

I have added an issue for this and added the issue marker into the spec.

https://github.com/w3c/webpayments-core-messages/issues/1

https://github.com/w3c/webpayments-core-messages/commit/4a5dbfc7c7b70bc920964477cfb394c4486fe7d9

> This document should currently be an unofficial draft (specStatus = 
> "unofficial" in ReSpec)

Spec status is now set to Editor's Draft since it's been picked up by
the group.

> Need github links in the header area

Fixed in both specs.

https://github.com/w3c/webpayments-core-messages/commit/4499426d75ef245fd905e4d0d08bea0d2132f845

https://github.com/w3c/webpayments-http-api/commit/a41ef91f51bd7e20dc0ae90cdc1a651abbdf535a

> Global: s/e.g. /e.g., /

Fixed in both specs.

https://github.com/w3c/webpayments-core-messages/commit/7a66151c44e923b630a6481ab2c32732831b50e4

https://github.com/w3c/webpayments-http-api/commit/568ea38bf2127674b22eefd5a1ee05940825b866

> How to Read this Document
> 
> Move the Data Model hello world stuff into a section 1.1.1 on Data
> Model Approach.  A primer on how data models work and how this
> document approaches them.

Done.

https://github.com/w3c/webpayments-core-messages/commit/3000ad77ad3aa7bc71d02f2f02c057f438001a8d

> What is [PSD]?

Payment Systems Directive - it's a European initiative and the [PSD] is
meant to signal that the definition came directly from PSD. I don't
think the readers care that it came from PSD, so I've marked it like so
in the markup:

    <!-- Definition from European Payment Services Directive -->

... and condensed the definition.

https://github.com/w3c/webpayments-ig/commit/cc0ef69339302026f1d9c9b09242afa2f113aa26

> Issue 2: I don’t have a problem with it, but move the content of
> this note into section 1.1.1 above.

Removed the issue marker as it duplicated the other content in the section.

https://github.com/w3c/webpayments-core-messages/commit/3000ad77ad3aa7bc71d02f2f02c057f438001a8d

> JSON Schema needs a normative or informative reference.

Done.

https://github.com/w3c/webpayments-core-messages/commit/5406a3d98da343827c26cc977a6aa5b6fd37c035

> There are references to the "expressing" sections. I think they
> should be in appendices but I am not married to the idea.

If we are going to make these sections normative, should they be in an
appendix?

I've added an issue marker:

https://github.com/w3c/webpayments-core-messages/commit/d7555fb5585ffc25eff5fdca0d8cc876658543f5

> AcceptablePaymentMethod
> 
> The paymentMethod / paymentAmount structure should be grouped into a 
> list of items offers…  one object per payment amount.   … in other
> works the acceptablePayment key should be able to take multiple
> items.

This is currently in the spec:

"One or more AcceptablePaymentMethods that the payee will accept as
payment."

I'm not certain we should force an array for single items. I realize why
this is beneficial from a developer perspective.

Perhaps the question is "should validation throw an error if the value
of "acceptablePayment" is not an array (even if that array only has one
item in it).

I've added an issue marker:

https://github.com/w3c/webpayments-core-messages/issues/3

https://github.com/w3c/webpayments-core-messages/commit/28a4afbafc437432e375a29bca21e3481cf77253

> PaymentResponse
> 
> 
> payment key: “may” should be in caps.

Fixed in two places. Is that what you wanted?

https://github.com/w3c/webpayments-core-messages/commit/ac57c68442d87a1d18b124c66229824cf99e21b7

> Examples
> 
> I would prefer that the content of the examples be inline. I
> appreciate that JSON Schema is a little verbose, and also that
> ReSpec's highlighting doesn't do a good job on JSON Schema.

How do you suggest we do this while not harming the readability of the
document. I remember you saying something about <summary> or <aside> or
something hide-able like that.

I'm out of time for today, but I'm adding an issue marker so we can
continue the discussion there:

https://github.com/w3c/webpayments-core-messages/issues/4

https://github.com/w3c/webpayments-core-messages/commit/d68138ed6fbb7284d67fdc2d95a342d2f3f3dec2

-- manu

-- 
Manu Sporny (skype: msporny, twitter: manusporny, G+: +Manu Sporny)
Founder/CEO - Digital Bazaar, Inc.
JSON-LD Best Practice: Context Caching
https://manu.sporny.org/2016/json-ld-context-caching/

Received on Saturday, 7 May 2016 19:52:30 UTC