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

A few comments before putting myself away for a while:

On Mon, Sep 7, 2015 at 10:18 PM, Jeffrey Yasskin <jyasskin@google.com>
wrote:

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

I have added this (back) to the receiving steps - it was meant as a
separate algorithm,  and I deleted it at a certain point in order to move
it, which move didn't happen. Anyway, this was an epic omission, thanks for
noticing it.


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

At the receiving side you're right and we should not mandate any format - I
am not aware of such; if you notice any, please tell, or raise an issue.
At the sending side yes, we can mandate certain format for Web NFC content.


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

We need some thought on this. Because NFC content cannot be trusted, we
cannot speak about origins either.
I assumed (maybe erronously), that every Web NFC content is created by
pages (even when pre-programmed), and even when not, at least the Web NFC
record is written well formed, with the URL of the source being a parameter.
We don't yet have a correct and consistent vocabulary for describing this.


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

Thanks. A leftover :).


>
> * 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?
>

That is a generic sentence. Did you mean that in addition to that, in each
algorithm we specify in detail how the user agent should handle calls to
the Permission API? Does the spec need to go that low level, or is it
enough saying that the 'nfc' permission must be obtained?


>
> * 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?
>

I think that is described in
https://w3c.github.io/web-nfc/#steps-pushMessage


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


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

Yes you're right (likely I meant the NDEF ID contains that URL).


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

OK.


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

No, this is not correct, but I get what you meant. Will update.


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

There is a misunderstanding about origins and Web NFC message. The message
is the sequence of records, and they all are written the same time, i.e.
have the same "origin". There was an idea of a possibility to store
multiple different web messages in a single NDEF message, partitioned by
origin, but it's too complex for the first version, and not really
practical.

So IMO the sentence does make sense, the NDEF ID field as a container MAY
contain the origin, or not. It does not matter in this version whether the
origin is saved or not. Implementations can choose that, but does not
affect interoperability. The only mandated part is the Web NFC record. Now
if this is confusing, I remove all mentions to the NDEF ID field and it
will be not supported in this version of the spec.


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

OK.


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


Why is that? That text is description, followed by the dictionaries that
are used, followed by the watch algorithm, each in its own sub-section.


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

The arguments are defined in the IDL, so I assumed they are clear, and
methods are uniquely identified by their names in a given object. Anyway,
not a big deal.

Thanks,
Zoltan



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