OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

obix-comment message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: Comments on OBIX 1.1 PRD02


Comments on OBIX 1.1 PRD02

Toby Considine

 

 

CamelCase reference. Lines 43-44 and other locations. Recommend using less proprietary reference with a more permanent URI than an active MSDN reference. Recommend xml.coverpages.com/camelcase or similar. Also recommend reference be “CamelCase” not “casing”

 

 

 

Table 1-3, section 1.9, 133-134. “Changes from version 1.9. Suggest removing the “new” items that are then marked “moved to another document” unless it is part of a more general statement. Perhaps “All specific details about encoding have been moved to a separate specification: “Common Encodings for OBIX” which includes XML, EDX, Binary, JSON, and COAP”. Table also implies that HTTP content negotiation is *only* in REST document. Is this true?

 

 

 

Several areas of this specification are overly conversational—particularly topic sentences. I am presenting these as a single comment:

 

Line 161 is unfortunately conversational. Perhaps starting sentence similar to “OBIX addresses the need to normalize information from devices and present it in a standard way.”

 

Section 3.2, line 201: suggest first sentence replaced with “OBIX provides simple syntax rules able to represent the underlying object model.”

 

Section 3.3, line 231: “As the focus of OBIX is to make information available over the internet, it makes sense to use the Uniform Resource Identifier (URI) to identify OBIX objects. URIs, as defined in RFC3986, are the standard identifiers for resources on the internet.

 

245-246 URI references define a standard way to normalize the _expression_ of relative URIs.

 

252-254 The World Wide Web is in essence a distributed collection of documents hyperlinked together using URIs. Similarly,  OBIX presents controls and sensors as a collection of documents hyperlinked using URIs.

267: Remove “Probably” (redundant after “for example”)

 

9.2 1174-1187 needs a re-write using language that isn’t as impressed with itself for discovering the internet. Also see comments on URIs, above.

 

Line 1520: Suggest deleting “if that is important to the application”

 

Line 1876: recommended deleting “as possible”

 

2252-2254: “Now fictionalize the that”? Suggest: “The system next detects that the front door is closed, i.e., the alarm point transitions to the normal state. When the Client next polls the Watch, the Alarm would be included in the Feed.

 

 

 

 

276:279: This is an important transition and it is muddled. Suggestion follows, but it is worth discussing to make sure we get this introduction correct:

 

OBIX Contracts describe abstract patterns for interaction with remote systems. Contracts use the grammar of OBIX to create semantics for these interactions. Standard Contracts normalize these semantics for common use by many systems. Contracts are used in OBIX as class definitions are for objects or as tables and relations are for databases.

 

OBIX specifies a minimal set of contracts, which are described in later sections. Various vendors and groups have defined additional standard contracts which are out of scope for this specification. Sets of these contracts may be available as standard libraries. Implementers of systems using OBIX are advised to research whether these libraries are available, and if so, using them to reduce work and expand interoperation.

 

 

 

 

3.6 There is a lot of We Want here. Recommend (subject to discussion):

 

OBIX provides a foundation for developing new abstractions (Contracts) in vertical domains. OBIX is also extensible to support both legacy systems and new products. It is common for even standard building control systems to ship as a blank slate, to be completely programmed in the field. Control systems include, and will continue to include, a mix of standards based, vendor-based, and even project-based extensions.

 

OBIX extensibility is based on the principal that anything new…

 

 

 

Section 4: 296: The first sentence cannot decide whether it is a specification or not.

Suggest: “OBIX specifies a small…”

 

 

 

Multiple locations, the use of the word “Concept” in this specification is nearly always in muddled expressions of intent. Suggest searching for all occurrences and considering re-write for each. Instances of note include:

 

Section 4.1.1 Line 317: “Supports the concept of Null is awkward. Suggest “Any OBIX Objects may have the property Null.”

Section 4.2: This Concept is… Suggest: “In object-oriented terms, the base OBIX Val Object is an abstract class, and the Val subtypes are concrete classes that inherit from that abstract class.

Line 1700: This is the normative definition of Point. Delete “The concept of”

Line 1703-1704: “The Goal” language is distracting. Suggest:

OBIX allows an integrator to normalize the representation of Points without forcing an impedance mismatch on implementers…

 

 

 

 

Section 5.1: Should there be a general discussion of securing the lobby?

 

 

 

Line 642 uses a recursive definition of “batch”. Suggest: “The Lobby defines a Batch operation which groups together multiple network requests into a single operation.”

 

 

 

Consider whether each use of “Vendors” should be replaced by “implementers”, “systems” or similar words as appropriate. The language Vendors, while tied to OBIX’s legacy as a shim above several brand-name control systems, is often distracting or limiting. In particular:

 

Line 670: Perhaps “It is up to OBIX Clients to…”

 

Section 7 table 7-1. “It is likely that many vendors…”. Suggest: “OBIX will be used to interact with existing and future control systems based on statically-typed languages such as…”

 

 

 

Line 721-722: “it is recommended that servers SHOULD protect” is duplicative. Suggest “Servers SHOULD protect” or “It is recommended that Servers protect”

 

 

 

 

7.6.2 Lines 1009-1010. Mixins should either be more or less defined. Either lose the word “metaphor” or define more fully including a reference.

 

 

 

General Comment: The usage WebSocket is always preferred to WebSockets. Fix wherever it is found.

Includes: line 1488.

 

 

 

 

14.2.5 Compact Histories. Proper handling of missing time intervals is more implicit than explicit. Suggest adding language to make the behavior more clear. (This is all in lines 1909-1912) Perhaps these sentences should be elevated to a bullet point, but in any case, it requires more direct and explicit language.

Also, the bullet points are each important. Suggest converting to a numbered list.

Also, it is unclear how to indicate alternate delimiters, alternate quotes, etc.

 

 

 

2177-2178. Language for PointAlarm definition is muddy. Suggest:

An Alarm is often associated with a Point. A PointAlarm Contract defines a Contract which reports the value of a Point which caused the alarm condition.

 

 

 

16 Security: 2270-2273: Suggest:

OBIX does not define security protocols or security methods. Security is dependent upon the business process, the value of the data, the encoding used, and other issues that are out of scope for this specification. OBIX supports composition with any number of security approaches and technologies. User authentication and authorization are left to the implementer. The type and depth of encryption are dependent upon the bindings and transport protocols used. Although it is possible to define contracts for user management through OBIX, this committee does not define any standard Contracts for user management.

OBIX does define the messages used to report errors in security or in authentication. OBIX further defines how security is inherited within the hierarchy of a system. OBIX further makes a number of statements throughout this specification of areas or conditions wherein practitioners should consider carefully the security effects of their decisions.

 

 

tc

 


"Debugging is twice as hard as writing the code in the first place. Therefore, if you write the code as cleverly as possible, you are, by definition, not smart enough to debug it."

- Brian W. Kernighan


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

 



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]