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

Update to Web Services Addendum (lucky rev 13)

Expand Messages
  • Dave Robin
    Data Modelers, (and cc: IT-WG) Here are the revisions suggested by the San Francisco discussions, along with some general cleanup/consistency changes, some of
    Message 1 of 1 , May 20, 2013
    • 0 Attachment
      Data Modelers, (and cc: IT-WG)

      Here are the revisions suggested by the San Francisco discussions, along with some general cleanup/consistency changes, some of which got pretty substantial.

      I'm sure some of this might change after I try to update my code to match because that always happens: code informs document informs code informs document.... but I won't make any code changes until after our Thursday call to see how these changes sound to others.

      But I just noticed that the email invitation for a 5/23 conference call actually says "June 6" inside, so I hope that's a mistake and that we're actually going to have a call on 5/23, 6/6, and 6/13 like the subject lines say.  Looking forward to your thoughts.


      Rev 13: Changes since San Francisco meeting 2013-05-06:
      • Simplified (hopefully) the use of scopes: provided support for standard scopes, extended (proprietary) scopes, and "application scopes" all in a single mechanism, so that the "normal" cases are very simple. Keeps the server side simple by making any concepts of hierarchies and roles up to the clients.
      • Changed subscriptions to track discussions with SubscribeCOVMultiple service:
        • The subscription applies to a list of subscribed values which can be changed but when that list is cleared, the subscription is cancelled.
        • Creating or refreshing the subscription causes all cov items to be sent.
        • TBD: the "frequency" and "stagger" belong to the subscription as whole, not individual entries.
      • Got rid of the term "psuedo-attribute" and "pseudo-node" by admitting that the "on the fly" computed things like @count and @multi, and .history and .multi, were really more like function calls and not part of the data model.  Therefore this rev now calls them "computed attributes" and acknowledges the fact that these are more like services than resources (but they still do not persistently create or delete data)
      • Changed the plaintext @history to a more description @historyPeriodic and changed the .history "pseudo-node" to be the new @history "computed attribute".
      • Made a "/.sysconfig" node to represent the "configured" data, as opposed to the "boiler plate" data in the fixed "/.sysinfo".
        • Gathered in one place all the static lists that clients might want to make filtered queries on:
        • Moved the  "/.histories" node and created an analogous "events" node.
        • Moved the "/.interfaces" and "/.bacnet/.objects"  and changed the object list back to protocol-neutral "objects"
        • Added an incrementing "version" for when any of these lists change.
      • Added back the <Reference> base type since using <String> for URLs finally became too awkward when making rules for filtering "interfaces", "objects", etc.  Now those are defined as Lists of Reference and the rules for 'filter' and 'select' can be consistent everywhere without special cases.
      • Added the @descendants computed operation as a generalized query mechanism - using 'depth', 'filter', and 'select' to find anything below a given location.
      • Put back the physical modeling for "/.bacnet" from rev 4, with modifications:
        • Removed the "by name" option for devices and objects, but...
        • Allow object types and properties to be identified by either number or Clause 21 name. 
        • Servers shall support names for properties but are not required to support unknown or proprietary properties
        • Made the "uet" prefix part of the device identifier portion, e.g., /.bacnet/{uet},{device-instance}/...
      • Even though @descendants can search for interfaces, kept the concept of an "interfaces" collection because that is needed by xdd files to statically answer the question "what interfaces do you have?".
      • Gave up on trying to have a XML format that was "as powerful" as BACnetLogRecords, only slightly different.  The new proposal is to just use BACnetTrendLogRecords for the "raw" trend records like we were doing for event records. Other protocols just map into that superset as appropriate.  (The "processed" @historyPeriodic is still simple, though)
      • Made explicit mention of the fact that a node could have multiple histories (different sampling criteria), and that a TLM could be providing histories for multiple nodes, and defined the linkages between them all.
      • Changed the JSON format to be language mapping friendly:
        • use the 'name' attributes directly as javascript member names (defined reversible escaping for 'name' characters that are not allowed as javascript names)
        • put attributes and children as peers, distinguishing attributes with $ prefix, instead of the awkward "children" array.
        • shortens JSON and enhances readability (hopefully) eliminating the mixture of JSON objects and arrays - everything is now an object.
        • Most importantly: allows dot navigation in javascript clients. e.g.,  "myresult.foo.bar.$value"
      • Made JSON "$base" attribute (equivalent to XML element name) optional for clients that already know the types.  This trims JSON verbosity to a bare minimum. It's required for definitions, obviously, but optional for runtime queries of values.
      • Added filter functions startswith() and endswith() and alternate short forms for tag() and link() rather than using wildcard arguments.
      • The use of the GData term "start-index", which was confusing with our 1-based arrays, so that has been changed to OData's equivalent and unambiguous term 'skip'.
      • Questions: 
        • Because we have {prefix}, do we really need "." in front of "sysinfo", "auth", "trees", etc.?
    Your message has been successfully submitted and would be delivered to recipients shortly.