Loading ...
Sorry, an error occurred while loading the content.

Re: [BACnet-XML-WG] Update to Addendum 2010am (BACnet Web Services) [1 Attachment]

Expand Messages
  • Dave Robin
    Oh, I forgot to mention one thing about this... Some of you might notice that I have *not* removed SOAP, as we talked about in Atlanta. This was only because
    Message 1 of 2 , Jan 16, 2012
    • 0 Attachment
      Oh, I forgot to mention one thing about this...

      Some of you might notice that I have *not* removed SOAP, as we talked about in Atlanta.  This was only because that would be a lot of editorial work and I was focusing on the changes to the REST stuff first.  And also, before I did all that ripping out, I wanted to reconfirm one more time that we want to do that.

      Dave


      On Jan 16, 2012, at 3:15 PM, Dave Robin wrote:

      XML and IT working groups, 

      After much delay caused by a many-month in-depth study of OData, prompted by discussions in some smart grid groups, here is the updated addendum.

      In summary: OData's rapidly growing popularity and developer ecosystem, and the possibility of implementing a BACnet/WS server with Microsoft's WCF Data Services, led to implementation experimentation and had much influence on the proposed changes here.  

      HOWEVER, in the end, OData's data model is still too immature to support BACnet data, so a COMPLETE implementation in WCF is just not possible.  

      BUT, an implementation using custom data serializers still seems in reach, so I made the BACnet protocol compatible in almost every way except the actual property values.

      STILL, keeping in mind that some of us will write this from scratch, with maybe just an XML library at our disposal, I kept things as simple as possible, always trying to "see the C code" behind each requirement.

      In the process, several nice things happened.  Changing the $filter syntax made it nicer to read and easier to implement by hand.  Using $filter to select objects and using $select for properties made a nice kind of ReadPropertyMultiple-like capability.

      Following OData's lead in fixing rules for when to use Atom, direct XML and plain text greatly simplified client and server optionality.  Removing options for obscure or academic use cases is always good.

      Here is a summary of the OData investigation:

      What works well:

      - Objects: representing BACnet objects as "entities" is a good level for addressing, naming, semantic tagging, and relationships.

      - Properties: concept of "properties" is consistent between BACnet objects and OData entities

      - Navigation Properties: properties that are pointers (i.e. relationships) are promoted to <link> elements on the object/entity and can be used naturally as path segments in the URI (but see caveat below)

      - RPM works naturally with OData properties, using $select

      - RP works naturally with URI ability to drill down to a single property, minus the verbose object wrapper

      - sub-property access URI defined to drill down to access parts of properties (with the exception of arrays and list members)

      - $value concept allows XML or plain text access to primitive fields

      What doesn't work well:

      - BACnet objects have a large number of defined optional properties.  OData only was "nullable", which means that all defined properties are required to be in the XML, with the "Absent" ones marked as null="true"

      , Some BACnet data can be "present but NULL" and OData is only nullable and so can't distinguish between absent and NULL..

      - No direct support for CHOICE, only nullable fields (all choices would be present with only one non-null?)

      - No support for ordered arrays.  OData only has unordered "bag" collections, and has no URI syntax for access individual members.

      - No support for ALE/RLE since bags are sub-property access only and are not addressable as a "feed" for POST/DELETE operations.

      - No concept of inheritance: "Open Types" are restricted to using the base type name only.

      - No polymorphism, so no "Any" datatype (would have to use a choice of all primitives and an "open" constructed type)

      - Navigation Properties can only point to entities (objects), while BACnet references can point to properties (with optional index).

      - Annoying: Namespaces and prefixes are comically long (assumes gzip): <link rel="schemas.microsoft.com/ado/2007/08/dataservices/related/OurPart" ... >

      - Scary: OData is a little too active: constantly expanding and changing - the assumption is that libraries are easily updated and are not limited by size or computing power.


      Therefore...

      Summary of Changes to Addendum:

      Simplfied the rules (i.e. no options) for when to use Atom vs XML vs plain text, following OData's model for using an Atom wrapper at the object level, where most metadata, semantics and relationships are defined, and using direct XML at property level and below, and using plain text for terminal facets like value, count, etc.

      A reviewer note from the "Objects and Properties" section sums up a lot of the changes: [Reviewer note: This distinction of returning objects as Atom entries and properties as unwrapped XML is consistent with OData's view of objects and properties.  In addition, BACnet is consistent with OData's further distinction of facets, returning them in plain text. (e.g. OData's $value and BACnet's :Value).   While many of the requirements here are intentionally compatible with WCF Data Services and OData, the actual property data in the Atom <content> does not use the OData <m:properties> format or "Edm:" data types because the data type and access requirements of BACnet (arrays, choices, extensible enums, list item manipulation, ANY, optional items, wild cards) cannot be handled by OData or the EDM at this time. Implementations based on WCF will have to provide custom data serializers for CSML formatted properties]

      Made filtering syntax match that of OData's $filter rather than a subset of XPath.  This is much more natural for working with property values and makes for much simpler/shorter expressions

      Adopted OData's $select to select which properties are returned.

      Brought back CSV format for efficient transfer of bulk trend data.

      Put in more language to indicate that localization is optional (it always was, but it didn't say so up front).

      To aid in discovery of things modeled as BACnet objects, standard feeds for objects, interfaces, and devices are more fully defined.

      Added explicit requirement for the use of an Atom Publishing Protocol "service document" which defines standard roots for collections like /.objects, /.interfaces, /devices, etc.

      Removed feature for .event-history feed on individual nodes.  While COV (.value-changes) was retained, individualized event history subscriptions on a single node was seen as too unusual to be defined at this time.

      Made more use of Atom <link> elements.  For example a .../.history feed can point to its BACnet Trend Log object source, if it has one, using the standard Atom "via" relationship, and to its subscribers with a BACnet-specific rel="http://bacnet.org/rel#subscriber" relationship.

      Allowed the concept of supporting multiple devices with objects associated to those devices. There is no concept of "primary device", they are all peers.  The /.sysinfo nodes are still there to identify the server itself.

      Specified how to access the Log_Buffer property of  BACnet Log objects.

      Got rid of dedicated published-min, published-max, updated-min and updated-max query parameters since the new $filter syntax can do that now.

      With the increased use of XML, changed the confusing "data model attributes" to "facets", borrowing the word and meaning from XML schema.

      Rewrote the path description in ABNF and added OData compatible aliases /$value and /$count.

      And, of course, addressed the public review comments.

      Enjoy!

      See you in Chicago.

      Dave



      <Add-135-2010am-PPR1-draft-1.docx>




    Your message has been successfully submitted and would be delivered to recipients shortly.