Re: New Web NFC API draft - please review by Thu 10 Sep

Thanks for the update! I have some fundamental comments, and then a
partial list of more minor comments:

1) https://w3c.github.io/web-nfc/#the-nfcadapter-interface describes a
watch() method with a 'callback' argument, but nothing else in the
specification uses that callback. That means watches have no effect.
Please go through the whole spec and make sure the communication flow
is specified in both directions, all the way through.

2) You're using RFC2119 keywords (must, should, may) to talk about the
content of NDEF messages, but this is a specification for *browsers*,
not for NFC peers or tags. You can't constrain the NFC device's
behavior; you can only specify how the browser must react to arbitrary
NDEF messages. Every "must X" in your descriptions of Web NFC messages
should instead be reflected as "if not X, fail in Y way" in an
algorithm the browser runs. You can also define a "Web NFC Message"
and then use "if this NDEF message is not a Web NFC message, Y", like
I do with "valid UUID" in Web Bluetooth:
https://webbluetoothcg.github.io/web-bluetooth/.

3) In https://w3c.github.io/web-nfc/#dfn-ndef-id,
https://w3c.github.io/web-nfc/#dfn-web-nfc-origin, and
https://w3c.github.io/web-nfc/#web-nfc-id, you talk about a "browsing
context" that wrote the NFC data, but no such browsing context exists
for tags that are pre-programmed with a particular Web NFC message.
Instead, I think you should just talk about these as origins, maybe
non-normatively mention that this is the origin that the tag trusts,
and then use the origin in algorithms. It's the algorithms that ensure
the browsing context matches the tag's origin.


* In https://w3c.github.io/web-nfc/#permissions-and-user-prompts,
"i.e. expressed permission for for using" has a duplicate "for".

* In https://w3c.github.io/web-nfc/#permissions-and-user-prompts, "The
Permissions API should be supported" is probably not enough detail.
What exactly happens in response to a call to each function in the
Permissions API?

* In https://w3c.github.io/web-nfc/#web-nfc-record-format,  "The
payload must contain the Web NFC Id of the Web NFC message." doesn't
pin down the format of the Web NFC record. Do you mean that the entire
record must be the ascii encoding of the Web NFC Id (which is a URL)?
Or is there some other undescribed data in there too?

* At https://w3c.github.io/web-nfc/#dfn-web-nfc-id, don't say it's a
"special" URL. It's just a URL.

* In https://w3c.github.io/web-nfc/#web-nfc-id, I believe the Web NFC
ID *is* a URL; it doesn't "contain" a URL. "Should" also doesn't make
any sense here.

* https://w3c.github.io/web-nfc/#dfn-ndef-record is confusing. I think
it would be clearer if you listed the parts of an NDEF Record ("An
<dfn>NDEF Record</dfn> consists of a <a>TNF field</a>, an optional
<a>NDEF Id</a>, and an array of payload bytes") and then went into
more detail on each of those components.

* In https://w3c.github.io/web-nfc/#dfn-web-nfc-message, a Web NFC
message shouldn't "represent" anything. Instead, a Web NFC message
with origin O *consists of* a sequence of NDEF Records with NDEF Id
fields containing O, followed by a Web NFC Record whose NDEF Id field
is also O.

* Does it make sense for
https://w3c.github.io/web-nfc/#web-nfc-record-format to say the NDEF
ID field "may" contain the origin? If it doesn't contain an origin,
there can't be a Web NFC message in the tag, and so nothing in Web NFC
will ever interact with that Web NFC Record.

* https://w3c.github.io/web-nfc/#features should be non-normative.

* The definition of the watch() function (the place the link from
https://w3c.github.io/web-nfc/#idl-def-NFCAdapter goes) should be the
"When the watch() method is invoked, the user agent must ..."
definition, not the descriptive "The watch() method enables listening
to incoming NDEF messages." You should also repeat the arguments to
watch() so you can use them in the algorithm, like I do with
https://webbluetoothcg.github.io/web-bluetooth/#dom-bluetooth-requestdevice.

I'll probably have more comments once you've fixed the fundamental
problems above.

On Mon, Sep 7, 2015 at 7:08 AM, Kostiainen, Anssi
<anssi.kostiainen@intel.com> wrote:
> Hi All,
>
> The Web NFC API editors have produced a new version of the spec [1] for your review:
>
> [1] https://w3c.github.io/web-nfc/
>
> The supplementary Security and Privacy document [2] has also been updated to match [1]:
>
> [2] https://w3c.github.io/web-nfc/security-privacy.html
>
> Please review [1] and let us know by Thu 10 Sep if you have concerns. At that time we plan to take another snapshot to be used as a basis for further implementation and experimentation.
>
> This is a significant update. Changes since the previous version [3]:
>
> [[
>
> * Changed data types and mapping to and from NDEF records.
> * Changed storage conventions of Web NFC content: changed Web NFC record, made it optional to store origin to the NDEF ID field.
> * Reworked the permissions and user prompting model.
> * Fixed terminology related issues.
> * Changed send() to pushMessage() and added more options.
> * Re-added watches/filters, in updated form.
> * Removed event handling for received data, and replaced with handling it in watches, to avoid side effects in adding event listeners.
> * Updated existing algorithms related to sending NFC content, and added new algorithms, related to receiving NFC content.
> * Updated the code examples.
>
> ]]
>
> This version address the following GH issues: #2, #3, #22, #26, #28, #30, #31, #32, #33, #35, #36, #38, #39, #40. Also fixes: #4, #29, #34.
>
> For further details, see the HTML diff [4] and PR [5].
>
> Thanks,
>
> -Anssi (CG chair)
>
> [3] https://w3c.github.io/web-nfc/releases/20150824/
>
> [4] http://services.w3.org/htmldiff?doc1=http%3A%2F%2Fw3c.github.io%2Fweb-nfc%2Freleases%2F20150824%2F&doc2=https%3A%2F%2Frawgit.com%2Fzolkis%2Fweb-nfc%2Fgh-pages%2Findex.html
>
> [5] https://github.com/w3c/web-nfc/pull/44
>
>

Received on Monday, 7 September 2015 19:19:18 UTC