XMLers, ITers, and nascent DMers,
Here is the post-Dallas update to the WS addendum. Sorry for the extra delay. This time I tried something different... I actually implemented what I wrote! Then didn't like the code, changed it, changed doc to match... didn't like doc, changed it, changed code to match... didn't like the code, changed it, changed doc to match... well you get the idea. In other words, this is "informed by code". That code includes: from-scratch XML and JSON parser/generators (no libraries), from-scratch HTTP server (no Tomcat, etc.), from-scratch OAuth resource server (did use a HASH lib). It does just about everything, metadata selection, length/depth limiting, etc., except the 'filter' function and periodic trend resampling. Supports GET, PUT & POST (with type validation) and DELETE for nodes and complex attributes in in XML, JSON, and plain text. It wasn't that bad! Took about two weeks.
The reason for all the "from scratch" above? I wanted to see just how small (i.e. embeddable) this could be. Using big frameworks makes prototypes faster but gives you no clue how big something will be it you try to port it somewhere other than a PC server. And I made it very low-cleverness: I avoided tricky java-isms with the idea of creating very transcribable code, to C#, python, ObjectiveC, VB(!?), etc.
So, how big? The answer: how much code can you write and test in two weeks? It's not that big.
So, here is the new version. As usual, I'll just cut and paste the doc's "committee notes" here rather than try to paraphrase it all again in this email.
Don't forget there's a conference call on Thursday where we'll be discussing this and possibly the Profile_Name/Profile_Location, CSML-for-Classic devices, Interface declarations, and other ideas. Don't miss it!
2013-03-10, Post-Dallas changes:
- Added a first cut at an OAuth 2.0 compatible security framework. Following the OAuth model, this separates authentication, authorization, and resource access into separate functions, and therefore possibly separate hosts. The OAuth "bearer token" mechanism really simplifies things and mirrors our Clause 24 "delegated authentication and authorization" capability and, most importantly, keeps "resource servers" (i.e. BACnet devices) simple and long lasting (not subject to changing IT authentication/ID schemes, and allows delegation of authorization decisions/policies). The inclusion of a "built-in basic authorization server" is certainly up for debate then as to whether that should be *required* for installation flexibility or *optional* to keep footprint as small as possible. But if we take it out, bootstrapping security would be undefined so most of that functionality that would have to be added back anyway. And doing the bootstrapping with OAuth seemed like a simple way to do it, rather than inventing a second method.
- The positive reception in and after Dallas to removing Atom (*adopting* the good ideas but removing the formal wrapper) has resulted in a leaner protocol. The absence of Atom <feed>s makes PubSusHubbub less attractive then, and reverting back to our own subscription mechanism from earlier drafts gives us finer control over things like subscribe-multiple and cov increments.
- Referring to "The data model in Annex Q", or worse, "the attributes from CSML" was awkward because it was tied too closely to the XML syntax, and things like <NamedValues> weren't obviously "attibutes" at all. So this version extracts the abstract data model into a separate annex and leaves Annex Q to be just an concrete syntax for that model.
- Having a common data model also allows other syntaxes, like JSON, to be defined cleanly, rather than trying to defining the JSON in terms of the XML.
- It was decided in Dallas to keep the SOAP services rather than replace them. Having a separate data model that is "close enough" to the original SOAP "nodes and attributes" allows us (if we want) to recast the SOAP services in terms of the new common data model, now shared by REST, XML, JSON, and SOAP. (the changes for this is actually "TBD" in this version)
- Therefore, this addendum has been split into five parts: REST, Data Model, XML, JSON, and SOAP.
- Changed "Categories" to "Tags" to be more descriptive of their use and to allow tags to optionally have a value ("parameterized tags" as opposed to only "marker tags"), which is something that the Atom <Category> element could not do.
- Removed the "Physical Modeling of BACnet Data" (i.e. the "/.bacnet" tree) for now, to avoid possible conflict with ASN services, gateway issues, naming of proprietary things, etc., etc., etc. We can bring it back later, or in a separate addendum.
- Lastly, a lot of this still says "required", but if we think about making 90% of the REST functionality optional, we might be able to profile out a bare bones subset here: common security mechanism + optionless GET-only "/.sysinfo" + POST-only "/.asn" = NTB?
For change tracking in this version, the existing text from Addendum Q, that is the basis of the new data model Annex YY, is shown as in Word's change tracking as original text to track the changes made to it as part of extracting it into an abstract model. Other than that, the change tracking shows changes made since Dallas.
Chair, ASHRAE SSPC 135 (BACnet)