Comments on oBIX 1.1 PR01

["Toby Considine" <Toby.Considine@gmail.com>]

Pre-grouped for easy Jira

 

(1)

General: Document should indicate more clearly what is normative, what is illustrative. For example, All examples are non-normative. Section 1 is non-normative. Etc. This also ties to the unfortunate shuffling in of REST at several sections. Perhaps if the introduction included something such as

 

“This specification describes an information model and the basic operations for oBIX-based services. For simplicity, it assumes XML encoding and RESTful interactions. The normative description of the XML is the associated schema (XSD). The formal description of the REST interactions is described in the document REST Bindings for OBIX (see version xx or later version). The use of REST within this document is purely illustrative, and practitioners should look to the appropriate Binding document for normative guidance.

 

Similarly, alternate encodings are specified in the specification “Common Encodings for oBIX” (see version xx or later version). Practitioners using creating any interactions in encodings other than XML should look to the document referenced above or other encodings specifications that may be developed”

This suggestion leads to moving some REST descriptions, described elsewhere, into the REST  document and out of this.

 

Replace Extendability with Extensibility throughout document. Extendability is the capability of reaching out, as in an arm can extend because an elbow provides for extendability.

 

Suggest making the use of lowerCamelCase in Names normative, and adding normative reference to CamelCasing.

 

Suggest that defined terms have their first letter Upercased, as in Object or Facet, to distinguish from discussion of a general object or XML facet.

 

 

(2)

 

Consider a table of tables, and a table of examples following the table of contents. Many of the bulleted lists in this specification should be re-cast as tables.

 

 

(3) Section 2 should be labeled non-normative.

101-103 Replace first two sentences with:

“The section provides a non-normative introduction to the purpose for and use of OBIX. For example, consider communications with a simple thermostat.”

 

 

(4) Simple editorial comments, Section 1-2

 

Line 4. Eliminate “But Now”

Line 16: Information Model

Line 17: Principal Requirement language is not right for a spec. Consider “oBIX defines a common information model to represent diverse M2M systems and an interaction model for their communications.” Change object model to information model throughout paragraph.

 

Section 1.1.2 Networking. SB: Interactions

Change paragraph to discuss encodings other than XML, and Bindings (which are not specified here). This specification should make no normative references to the encodings or to the bindings documents, but this paragraph should make it unambiguous how to assemble the specification we know and ones we don’t for a specific implementation

 

Consider Moving 1.1.4 to follow section 1.1.1

 

Line 58-66: Move REST, SOAP, and Encodings to Non-Normative. *This* specification should require no normative reference to either. Consider replacing with references to CRUD

 

Add PNG (Portable Network Graphics) to the Normative References

 

Add URI (RFC 3986) to Normative References

 

 

(5) Simple editorial comments, Section 3

 

155: replace with The oBIX design philosophy recognizes a commonality of functionality of the components of all control systems while hiding the underlying mechanisms and protocols. To that end, OBIX relies on the principles in Table [n].

 

156-161. Replace bullet points with a named table.

 

Should REST be replaced with CRUD? We can then add a sentence that suggests “For this document, we use REST operations as examples of CRUD operations in oBIX.”

 

158: A better definition of URI, including translation of acronym. Reference to RFC 3986 would be good.

 

164: Remove “cleverly”

 

208-209L “Since OBIX is used to interact with control systems over the web, we use the URL to identify each resource. Just as we assume an XML encoding and a REST binding for all examples in this document, so to we assume a URL using the hypertext transfer protocol (URLs beginning with http:) beginning with HTTP. This is not meant to forbid the use of secure transfer (https:) or of other protocols (ws:). Neither are the examples are meant to forbid the use of alternate ports. The URLs in examples in this document are for illustration only.

Or, see detailed comment on URLs. Below.

 

240-242: Consider replacing first 3 sentences with:

In oBIX, these patterns are modeled as a template object named the Contract.

 

244: Remove words “In Geek Speak”. Replace with “Formally” if desired.

 

 

(6) Detailed comment on URIs

207-218 See example of how the full use of a URI is described in Web Sockets:

Quoting:

The term "URI" is used in this document as defined in [RFC3986].

 

   When an implementation is required to _send_ data as part of the

   WebSocket Protocol, the implementation MAY delay the actual

   transmission arbitrarily, e.g., buffering data so as to send fewer IP

   packets.

 

   Note that this document uses both [RFC5234] and [RFC2616] variants of

   ABNF in different sections.

 

This specification defines two URI schemes, using the ABNF syntax

   defined in RFC 5234 [RFC5234], and terminology and ABNF productions

   defined by the URI specification RFC 3986 [RFC3986].

 

          ws-URI = "ws:" "//" host [ ":" port ] path [ "?" query ]

          wss-URI = "wss:" "//" host [ ":" port ] path [ "?" query ]

 

          host = <host, defined in [RFC3986], Section 3.2.2>

          port = <port, defined in [RFC3986], Section 3.2.3>

          path = <path-abempty, defined in [RFC3986], Section 3.3>

          query = <query, defined in [RFC3986], Section 3.4>

 

   The port component is OPTIONAL; the default for "ws" is port 80,

   while the default for "wss" is port 443.

 

   The URI is called "secure" (and it is said that "the secure flag is

   set") if the scheme component matches "wss" case-insensitively.

 

   The "resource-name" (also known as /resource name/ in Section 4.1)

   can be constructed by concatenating the following:

 

   o  "/" if the path component is empty

 

   o  the path component

 

   o  "?" if the query component is non-empty

 

   o  the query component

 

   Fragment identifiers are meaningless in the context of WebSocket URIs

   and MUST NOT be used on these URIs.  As with any URI scheme, the

   character "#", when not indicating the start of a fragment, MUST be

   escaped as %23.

 

   1.  The components of the WebSocket URI passed into this algorithm

       (/host/, /port/, /resource name/, and /secure/ flag) MUST be

       valid according to the specification of WebSocket URIs specified

       in Section 3.  If any of the components are invalid, the client

       MUST _Fail the WebSocket Connection_ and abort these steps.

 

 

Notice that the result  is clearer, and easier to code to. The commenter is *not* suggesting* these are the oBIX rules, merely stating that a form similar to this would be better for declaring what is expected.

 

(7) Detailed discussion of REST

220-234 Consider replacing REST with a discussion of CRUD. I would crib from the REST thesis for this, then finish with a renewed statement that this document non-normatively assumes a RESTful binding, while the details are left to the individual binding.

 

If followed, this would cause other changes throughout the document.

 

 

(8) Simple editorial comments, Section 4

266: “The OBIX object model illustrated below in Figure [x]. It consists of a common base Object (o:obj) and is built of 12 child objects. This section describes the structure of these elements and their attributes (“Facets”).

422: The language “All objects support the concept of null. Null is the absence of value” is opaque. Not sure what to suggest as a replacement.

 

445: Remove first sentence.

 

453: Add normative reference to PNG

 

Section 4.18.9 (520-538)

Avoid redefining common internet specification. Reference http://www.iana.org/time-zones . Use RFC6557 as a guide on how to discuss this.

 

Section 4.18.10. It would be helpful to reference the SI Units document when the term “SI Units” is forst used. http://physics.nist.gov/cuu/Units/units.html  Add as a normative reference.

 

 

(9) Simple editorial comments, Section 5

 

560-564: Avoid redefining URI and HREF. Define once and incorporate by reference at all other locations. Multiple discussions increase chance of incompatible interpretations. See “detailed comment on URI”

 

570-577. Consider making the use of lowerCamelCase normative.

 

591-593. Remover references to HTTP. URI works as well as HTTP URI and avoids creating confusion between normative statements here and those for other bindings.

 

 

(10) Simple editorial comments, Section 6

 

638-641: OBIX Contracts are used to define inheritance in OBIX points. A Contract is a template that is referenced by other objects. These templates are referenced using the “is” attribute”.

Contracts solve many problems in OBIX:

 

652-654: Eliminate first two sentences.

 

659-670: Do not use “a couple of” to introduce a list of four items. Consider:

“Common Terms useful for discussing Contracts” and then placing the terms in a numbered table captioned “Contract Terminology”

 

687: “Syntactic Sugar?

 

702-703 “Formally defined in XML”? consider other language that distinguishes between information model and encoding.

 

694-709: It is unclear what a coder should do when encountering “Implicit Contracts”

 

797: Are these the rules used for alternate encodings? Perhaps in

“In XML, flattening is done by….” Other encodings MUST either define the rules for expressing flattening or explicitly forbid flattening to conform with this specification.

 

804: Here we slide back from URLs to URIs. Pick one.

 

827 “Diamond Inheritance Pattern” may confuse more than enlighten without more words.

 

 

(11) Simple editorial comments, Section 7

“Akin to methods in OO”.

Suggest

OBIX Operations are the exposed methods of an OBIX Object, i.e., Operations are thing that you can invoke to “do” something.

 

(12) Simple editorial comments, Section 8

932-939: Entire section is verbose and distracting. Not sure how to fix.

 

962-963 appears to be redefining URL again.

964: Delete “As a matter of fact”

973-978: Remove explicit XML references

“Within any problem domain, the intra-model relationships can be expressed either by using containment or by references. The choice changes the semantics of the model _expression_ as well as of  accessing the elements within the model.

If the model is expressed through containment, then we use the term Extent to refer to the tree of children contained within that element. Only elements that have an HREF have an extent; objects without an HREF are included within the extent of one or more referenceable elements which we term its Ancestors.

 

Section 8.4 (992-997) appears to be XML encoding rules. If they are meant to be general model rules, please re-write.  If they are XML-specific rules, suggest moving to XML section of Common Encodings.

 

(13) Metatagging and Alternate Hierarchies

Section 8.5. Alternate Hierarchies does not represent the notion of metainformation well

Suggest We use “Tagging” as a title.

A server MAY present Tags that reference additional information about each OBIX object. If these Tags are part of a formal semantic model, i.e., Haystack, BIM, etc., then the tags will be identified by reference to its source semantic model. The identifier for such tags, along with the URI for the semantic model it represents, are declared in the lobby.

[example]

Insert after 1013.

OBIX Clients SHALL ignore information that they do not understand. In particular, a conformant client that is presented with Tags that is does not understand MUST ignore those tags. No OBIX server may require understanding of these tags for interoperation.

 

 

(13) Simple editorial comments, Section 9

 

Consider making 1018-1020 a table

Line 1018: consider replacing Software with server, system, interface or some other word.

Line 1020: consider replacing Software with server, system, interface or some other word.

Line 1022: change software to system.

 

Section 9.1: Here is the CRUD statement referenced numerous times in other comments.

1026: All service requests made against an OBIX server can be distilled down to 4 atomic operations

1033-1036: Consider making a table

 

1033-1036 Suggest removing possibly circular references to specific bindings.

 

 

(14) Simple editorial comments, Section 11

 

Line 1346 Change “Plus watches server…” to “Watches also serve…”

 

Section 11.2.1. Watch.add

Descriptions of naming a watch (1406-1411) should precede the watch methods.

Possible some of this is Encoding or binding specific and should be relocated accordingly.

 

 

(15) Simple editorial comments, Section 12

 

Line 1530: replace vendors  with some other word: systems / implementers / etc.

 

Lines 1568-1580

Consider placing in a named table,

 

 

(16) Format Values

 

The example in line 1692 indicates text/csv as a named value. Are there others? The value is apparently using a mime-type. Are other mime-types supported? Which ones?

Suggest instead specifying delimiters/quoters/etc in header field, with perhaps default to CSV. If so, specify CSV rules.

In any case, should reference https://www.rfc-editor.org/rfc/rfc4180.txt

 

 

(17) Simple editorial comments, Section 13, 14

 

Line 1888 “Whip out your calculator”?

 

Line 1928: delete word “Feature”

 

Lines 1948-1952. Consider using a named table.

 

---

"Energy and persistence conquer all things." -- Benjamin Franklin

---

Toby Considine TC9, Inc OASIS TC Chair: oBIX & WS-Calendar OASIS TC Editor: EMIX, Energy Interoperation SGIP Smart Grid Architecture Committee

Email: Toby.Considine@gmail.com Phone: (919)619-2104 http://www.tcnine.com blog: http://www.NewDaedalus.com