Reviewer: Christian Amsüss Review result: Almost Ready My review was focused on IoTdir topics (as it was requested through that channel). Those look largely fine, there's a bit of by-catch. As a whole, the document is well structured and readable in a cover-to-cover way (where any questions that would be excessive to treat at their introduction are clarified later). There are some areas that, despite being editorially sounding good, mismatch what I understand to be IETF best practices, namely around their use of URIs and internationalization. IoT specific comments --------------------- * WoT interactions: Many concepts described here overlap with the W3C Web of Things specification (events, actions, properties). That is to be expected working in the same space, and AIU, interactions with WoT as one model to convert to and from have been explored and discussed. Nonetheless, a reader coming from an IoT background will likely be familiar with WoT, and their perception of whether this is a document they can work with could easily be improved by referencing WoT (for example in 2.2.1 where three other thing desscription methods are listed as aligned, possibly together with them in the introduction, clarifying their relation; listing the ecosystems for which the sdf-mapping draft provides mappings could serve the same purpose). This might also work against receiving copies of https://xkcd.com/927/. * The IETF ecosystem already describes SenML (RFC8428), which to some extent exposes properties (which are self-described in terms of their units). Any referencable mapping effort to tie this back in would help make the IETF specification shape more well-rounded. * 7.3: This is not perfectly clear as to what is supposed to be escaped; 'is required for any characters in unit names as required by ABNF rule "pchar"' can be read as either 1. "The URI syntax makes requirements on this, and thus some have to be escaped (and pchar is part of those rules)" -- that'd mean that there is a <urn:ietf:params:unit:/>. 2. "The names need to be in pchar" -- that'd mean that there is a <urn:ietf:params:unit:%2f>. I'd think (and hope) you mean the 2., also because it works way better with core-href (maybe even perfectly), and because that slash does not really delimit path components, and because it does not pull in a rule that is not *precisely* what is meant, but the absence of "/" in the "specifically" section would indicate you might mean 1. If it is 2, text could instead say: > Index value: Percent-encoding (...) is required of any characters in unit > names except unreserved, sub-delims, ":" or "@" (i.e., the result > must match the pchar rule). (Excluding the pct-encoded from the wording ensures that the unit measuring physique in similarity to fire fighters, "%FF", doesn't pass through to stay %ff, but becomes %25FF). General standardization practice -------------------------------- * I see why internationalization of given names is not done (they are more like URIs and not just designed for human consumption), but many text strings in the information block, and later in the common qualities, are designed for human consumption (title, description); Harald mentioned he'd come back to this in the ART review. * Extension feature names will need to be non-conflicting, but no registry or format is set up for them. Some ways of achieving this is to require them to be URI shaped, having an IANA registry, or both (as is done for link relations). * "it is probably wise to" is a neat way to avoid RFC6919 language, but however accurately that document captures our feelings, apparently, more is expected of standards track documents. So, SHOULD Given Names with such encoding be avoided, or SHOULD (or even MUST) implementations support this encoding (BUT WE KNOW THEY WON'T)? Names and URIs ~~~~~~~~~~~~~~ * 4. Names and namespaces Nothing about using JSON paths to contribute to the default prefix is formally wrong (just somewhat unclear, eg. 3.2 talking of "local"), but while from a high-level perspective it looks like it would work just by virtue of having the JSON path fragment interpretation of the media type and using URI semantics, it just appears to do that and really does something else: (I'm ignoring the full CURIEs here -- those are well understood to just be applied as text substitutions; this is about the references to the local document and the default namespace.) The sdfRef values look like they are URI references, and they even work that way for referencing items defined in the current document (because there the media type uses JSON paths), but not for referencing items contributed to the default namespace by other documents. The latter *would* work if defining a default namespace established a base URI embedded in the content per Section 5.1.1 of RFC3986 -- but this document does not do that. Declaring the default namespace an embedded URI would seemingly break the ability to reference local elements (just like in HTML, <base href="somewhere" /> breaks <a href="#foo">), but that is saved by virtue of all local elements being contributed to the default namespace (and thus once more available after setting a base URI). Note that none of this works because the *current* document's media type imports JSON Pointer fragment identifiers: The requirement is really on the default document to have those semantics, and that they match the local document after merging. (Conveniently, JSON merge patch retains that). The document as it is runs through a mix of using URIs a bit, sometimes using URI mechanisms, then again talking of strings that "look like" a URI or have a fragment identifier "attached". This is confusing, and deviates from the established practice of using URIs as data format components. (It doesn't help that sections like 4.1 repeat requirements of URIs, eg. that an absolute URI is a URI with a hier-part -- every URI is a URI and has a hier-part, and in https that can not even be empty). * Relatedly (but that is not the problem of *this* document), the way local references are used will also make it hard for deref-id to be used, for the JSON-path-style identifiers will need to work with the representation there. That will require that the dereferenced document is either a union representation of all SDF documents that contribute to a namespace, or to have some index format based on explicit links. That document could then create explicit links from some fragment references to the documents that really define them: <./extension-foo-v2025.sdf.json>;rel=see-also;anchor="./#/sdfData/extItem1", <./extension-foo-v2025.sdf.json>;rel=see-also;anchor="./#/sdfData/extItem2", <./index-v2025.sdf.json>;rel=see-also;anchor="./#/sdfData/switch" * 3.2 has concrete fall-out of this: delimiting by the fragment is more than just a convention here, it is a practical requirement at least for the default namespace, because names are only contributed by the document through fragment encoded JSON paths that necessarily replace the fragment. * sdfRequired introduces a short-hand notation (referenceable-name) for what is otherwise found in sdfRef. If(!) references are already not really URI references but just look like them, why not do that also for sdfRef? (in figure 4, currentTemperature could "sdfRef":"temperatureData" by the same rules). * 4.7 note 1: URIs in lieu of SenML units sound sensible enough to warrant a note to the SenML DEs to not register any new units containing a colon; an update to the registry might be considered. Alternatively, if we do *not* want keep that registry free of colons, making an exception of "URNs from this sub-namespace MUST NOT be used in a unit quality" would make sense for exactly those units as an escape hatch. But I think we should make a choice before this document goes out. Editorial comments ------------------ * Terminology: Three Conceptual Terms are defined using the term Grouping, even though this is a Specfication Language Term. If they are really conceptual, the term could be replaced with "set of affordances" here (or "affordance (or set thereof)"). * "when triggered, have more effect than just reading, updating, or observing Thing state": Yet that is precisely what the actions in the example do. Maybe "have an effect that can exceed just reading, updating or observing Thing state". * "qualities of idempotence and side-effect safety": I suppose those are planned but not specified here; any informative refrence to where they are planned? * 6.1: The example ns:/sdfObject violates the convention set up in 3.2 * 7.4.1 Instructions to the experts are not rendered as a list. * 7.4.1 "pattern" could use a reference into C.2 so that its consumers know which regexp language is being referred to. * 7.4.1 maxLength, minLength could use a reference to C.2, lest people keep asking about what is meant by "character". Frankly, I'd use "measured in Unicode scalar values" everywhere; "character" just misleads people to think they know what it means, and if they really do, they understand whata Unicode scalar value is. Curious questions ----------------- * Would a switch actually be modelled to have a boolean property "value", vs. an "on"/"off" enum? (The example in D.2 is clearer in that it says "powered", which is more clearly a yes/no question).
Attachment:
signature.asc
Description: PGP signature
-- last-call mailing list -- last-call@xxxxxxxx To unsubscribe send an email to last-call-leave@xxxxxxxx
