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

On Mon, Sep 7, 2015 at 1:44 PM, Kis, Zoltan <zoltan.kis@intel.com> wrote:
> 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.

Could you only say you "have added this" when either it's merged to
https://github.com/w3c/web-nfc/blob/gh-pages/index.html or you include
a link to the commit that includes it? I take "I have added this" as a
sign I should look at the spec again to check the new wording, and
right now it's not there.

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

The problematic uses of MUST, SHOULD, and MAY are in the definitions
of a couple terms, in https://w3c.github.io/web-nfc/#web-nfc-id and
https://w3c.github.io/web-nfc/#web-nfc-record-format.

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

Nonsense. :) The NFC content contains the ascii serialization of an
origin (https://html.spec.whatwg.org/multipage/browsers.html#ascii-serialisation-of-an-origin).
The web page can't assume that a server with a certificate for that
origin wrote the NFC content, but the content still contains the
origin.

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

I don't understand what you mean here. In the previous sentence, you
worried that pages can't assume that NFC content was written by a
page, but now you're assuming that NFC content was written by a page?

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

What do you mean by "generic" here?

The permission API defines some terms and algorithms that you can use
to interact with its storage, but the Web NFC API has to actually use
those terms.

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

If the only use of the term "Web NFC record" is in pushMessage(), you
should remove the definition from section 7 and just write an NDEF
record with a particular format, in the pushMessage() algorithm. If
you intend to use the term elsewhere, you need to give it a complete
definition where you define it.

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

Yep, although again you should be clear that the whole contents of the
NDEF ID consist of that URL.

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

Not if the Web NFC message was written by non-web code.

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

When I'm reading the spec, and I want to see what watch() does, I
expect clicking on "watch()" to get me there. I might need to then
cross-reference terms like "URL pattern" or "match pattern", but that
should be a digression from the main algorithm, not imposed before I
get there. The definition of the watch() method especially shouldn't
digress to two completely different IDL terms (even if they're used in
the watch() algorithm) before getting to the algorithm it executes.

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

Try to optimize the spec for people reading it. The IDL is far away,
so it's hard to remember exactly what was passed to watch().
Cross-linking can help, but it's better to just repeat the list of
function arguments.

Jeffrey

Received on Monday, 7 September 2015 21:50:12 UTC