Encodings for OBIX: Common Encodings Version 1.0
Committee Specification 01
14 September 2015
Specification URIs
This version:
http://docs.oasis-open.org/obix/obix-encodings/v1.0/cs01/obix-encodings-v1.0-cs01.pdf (Authoritative)
http://docs.oasis-open.org/obix/obix-encodings/v1.0/cs01/obix-encodings-v1.0-cs01.html
http://docs.oasis-open.org/obix/obix-encodings/v1.0/cs01/obix-encodings-v1.0-cs01.doc
Previous version:
http://docs.oasis-open.org/obix/obix-encodings/v1.0/csprd02/obix-encodings-v1.0-csprd02.pdf (Authoritative)
http://docs.oasis-open.org/obix/obix-encodings/v1.0/csprd02/obix-encodings-v1.0-csprd02.html
http://docs.oasis-open.org/obix/obix-encodings/v1.0/csprd02/obix-encodings-v1.0-csprd02.doc
Latest version:
http://docs.oasis-open.org/obix/obix-encodings/v1.0/obix-encodings-v1.0.pdf (Authoritative)
http://docs.oasis-open.org/obix/obix-encodings/v1.0/obix-encodings-v1.0.html
http://docs.oasis-open.org/obix/obix-encodings/v1.0/obix-encodings-v1.0.doc
Technical Committee:
OASIS Open Building Information Exchange (oBIX) TC
Chair:
Toby Considine (toby.considine@unc.edu), University of North Carolina at Chapel Hill
Editor:
Markus Jung (mjung@auto.tuwien.ac.at), Institute of Computer Aided Automation, Vienna University of Technology
Related work:
This specification is related to:
Abstract:
Encodings for OBIX: Common Encodings v1.0 specifies different encodings for OBIX objects adhering to the OBIX object model. OBIX provides the core information model and interaction pattern for communication with building control systems.
Status:
This document was last revised or approved by the OASIS Open Building Information Exchange (oBIX) TC on the above date. The level of approval is also listed above. Check the Latest version location noted above for possible later revisions of this document. Any other numbered Versions and other technical work produced by the Technical Committee (TC) are listed at https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=obix#technical.
TC members should send comments on this specification to the TCs email list. Others should send comments to the TCs public comment list, after subscribing to it by following the instructions at the Send A Comment button on the TCs web page at https://www.oasis-open.org/committees/obix/.
For information on whether any patents have been disclosed that may be essential to implementing this specification, and any offers of patent licensing terms, please refer to the Intellectual Property Rights section of the Technical Committee web page (https://www.oasis-open.org/committees/obix/ipr.php).
Citation format:
When referencing this specification the following citation format should be used:
[OBIX-Encodings]
Encodings for OBIX: Common Encodings Version 1.0. Edited by Markus Jung. 14 September 2015. OASIS Committee Specification 01. http://docs.oasis-open.org/obix/obix-encodings/v1.0/cs01/obix-encodings-v1.0-cs01.html. Latest version: http://docs.oasis-open.org/obix/obix-encodings/v1.0/obix-encodings-v1.0.html.
Notices
Copyright © OASIS Open 2015. All Rights Reserved.
All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual Property Rights Policy (the "OASIS IPR Policy"). The full Policy may be found at the OASIS website.
This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to OASIS, except as needed for the purpose of developing any document or deliverable produced by an OASIS Technical Committee (in which case the rules applicable to copyrights, as set forth in the OASIS IPR Policy, must be followed) or as required to translate it into languages other than English.
The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns.
This document and the information contained herein is provided on an "AS IS" basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
OASIS requests that any OASIS Party or any other party that believes it has patent claims that would necessarily be infringed by implementations of this OASIS Committee Specification or OASIS Standard, to notify OASIS TC Administrator and provide an indication of its willingness to grant patent licenses to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification.
OASIS invites any party to contact the OASIS TC Administrator if it is aware of a claim of ownership of any patent claims that would necessarily be infringed by implementations of this specification by a patent holder that is not willing to provide a license to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification. OASIS may include such claims on its website, but disclaims any obligation to do so.
OASIS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on OASIS' procedures with respect to rights in any document or deliverable produced by an OASIS Technical Committee can be found on the OASIS website. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this OASIS Committee Specification or OASIS Standard, can be obtained from the OASIS TC Administrator. OASIS makes no representation that any information or list of intellectual property rights will at any time be complete, or that any claims in such list are, in fact, Essential Claims.
The name "OASIS" is a trademark of OASIS, the owner and developer of this specification, and should be used only to refer to the organization and its official outputs. OASIS welcomes reference to, and implementation and use of, specifications, while reserving the right to enforce its marks against misleading uses. Please see https://www.oasis-open.org/policies-guidelines/trademark for above guidance.
Table of Contents
2.6 Namespace Prefixes in Contract Lists
4.1 Object and value encoding rules
Table of Tables
This document specifies the encodings for OBIX.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC2119.
RFC2119 Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. http://www.ietf.org/rfc/rfc2119.txt.
OBIX OBIX Version 1.1. Edited by Craig Gemmill. Latest version. http://docs.oasis-open.org/obix/obix/v1.1/obix-v1.1.html.
EXI Efficient XML Interchange (EXI) Format 1.0 (Second Edition) , J. Schneider, T. Kamiya, D. Peintner, R. , Editors, W3C Proposed Edited Recommendation (work in progress), 22 October 2013, http://www.w3.org/TR/2013/PER-exi-20131022/ . Latest version available at http://www.w3.org/TR/exi/
RFC4627 Crockford, D., "The application/json Media type for JavaScript Object Notation (JSON)", RFC 4627, July 2007
RFC768 Postel, J., "User Datagram Protocol", STD 6, RFC 768, August 1980. http://www.ietf.org/rfc/rfc0768.txt
REST Fielding R.T., Architectural Styles and the Design of Network-based Software Architectures, Dissertation, University of California at Irvine, 2000, http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm
EXI MR Y. Doi, EXI Messaging Requirements, IETF Internet-Draft, 25 February 2013
EXI BP Efficient XML Interchange (EXI) Best Practices , M. , D. , Editors, W3C Working Draft (work in progress), 19 December 2007, http://www.w3.org/TR/2007/WD-exi-best-practices-20071219/ . Latest version available at http://www.w3.org/TR/exi-best-practices/
This chapter specifies how the OBIX object model is encoded in XML.
Since there are many different approaches to developing an XML syntax, it is worthwhile to provide a bit of background to how the OBIX XML syntax was designed. Historically in M2M systems, non-standard extensions have been second class citizens at best, but usually opaque. One of the design principles of OBIX is to embrace vertical domain and vendor specific extensions, so that all data and services have a level playing field.
In order to achieve this goal, the XML syntax is designed to support a small, fixed schema for all OBIX documents. If a client agent understands this very simple syntax, then the client is guaranteed access to the servers object tree regardless of whether those objects implement standard or non-standard contracts.
Higher level semantics are captured via contracts. Contracts "tag" an object with a type and can be applied dynamically. This is very useful for modeling systems which are dynamically configured in the field. What is important is that contracts are optionally understood by clients. Contracts do not affect the XML syntax nor are clients required to use them for basic access to the object tree. Contracts are merely an abstraction which is layered cleanly above the object tree and its fixed XML syntax.
The OBIX XML syntax maps very closely to the abstract object model. The syntax is summarized:
The object model figure in Chapter 4 of the OBIX core specification [OBIX] illustrates the valid XML elements and their respective attributes. Note the val object is simply an abstract base type for the objects which support the val attribute - there is no val element.
The following rules apply to encoding OBIX documents:
The following rules apply to decoding of OBIX documents:
The basic rule of thumb is: strict in what you generate, and liberal in what you accept. OBIX parsers are required to ignore elements and attributes which they do not understand. However an OBIX parser MUST never accept an XML document which isnt well formed (such as mismatched tags).
XML namespaces for standards within the OBIX umbrella should conform to the following pattern:
http://docs.oasis-open.org/obix/ns/{short-identifier and version}
The XML namespace for OBIX version 1.1 is:
http://docs.oasis-open.org/obix/ns/201410/schema
All XML in this document is assumed to have this namespace unless otherwise explicitly stated.
XML namespace prefixes defined within an OBIX document may be used to prefix the URIs of a contract list. If a URI within a contract list starts with string matching a defined XML prefix followed by the ":" colon character, then the URI is normalized by replacing the prefix with its namespace value. This rule also applies to the href attribute as a convenience for defining contract themselves.
The XML namespace prefix of "obix" is predefined. This prefix is used for all the OBIX defined contracts. The "obix" prefix is literally translated into "http://docs.oasis-open.org/obix/ns/201410/def". For example the URI "obix:bool" is translated to " http://docs.oasis-open.org/obix/ns/201410/def/bool". Documents SHOULD NOT define an XML namespace using the prefix "obix" which collides with the predefined "obix" prefix if it is defined, then it is superseded by the predefined value of " http://docs.oasis-open.org/obix/ns/201410/def". All OBIX defined contracts are accessible via their HTTP URI using the HTTP binding (at least they should be one day).
An example OBIX document with XML namespace prefixes normalized:
<obj xmlns:acme="http://acme.com/def/" href="acme:CustomPoint"
is="acme:Point obix:Point"/>
<obj href="http://acme.com/def/CustomPoint"
is="http://acme.com/def/Point http://docs.oasis-open.org/obix/ns/201410/def/Point"/>
Full fidelity with OBIX object model is maintained with the binary encoding. All object types and facets are preserved. However XML extensions such as custom namespaces, elements, and attributes are not address by the binary encoding. The OBIX binary encoding is based strictly on the OBIX data model itself, not its XML InfoSet.
The OBIX data model is comprised of 16 object types (elements in XML) and 19 facets (attributes in XML). The OBIX binary encoding is based on assigning a numeric code to each object type and to each facet type. We format these codes using a byte header with the bits structured as:
7654 3210
MCCC CCVV
The top most bit M is the more flag, it is used to indicate more facets follow. Bits 6 through 2 are used to store a 5-bit numeric code for object types and facet types. The bottom 2 bits are used to indicate a 2-bit numeric code for how the value of the object or facet is encoded.
The binary grammar is defined according to the following BNF productions:
<obj> := <objHeader> [objVal] (facet)* [children]
<facet> := <facetHeader> [facetVal] |
<facetHeader> <string> <value>
<children> := (<obj>)*
All documents start with a one byte objHeader structured as a MCCCCCVV bitmask. The 5-bit C mask indicates an Obj Code specified in Binary Constants table. If the object type contains a value encoding (specified in the Obj Value column), then the 2-bit V mask indicates how the following bytes are used to encode the "val" attribute. If the objHeader has the more bit set, then one or more facet productions follow. Facets are encoded with a one byte header using the same MCCCCCVV bitmask, except the 5-bit C mask indicates a Facet Code (not an Obj Code). The facet value is encoded using the 2-bit V mask. If one of the facets includes the hasChildren code, then one or more child objects follow terminated by the endChildren object code.
The following table enumerates the Obj Codes and Facet Codes which are encoded into 5-bits in the MCCCCCVV bitmask. The Obj Value and Facet Value columns specifies how to interpret the 2-bit V code for the value encoding.
Numeric Code |
Constant |
Obj Code |
Obj Value |
Facet Code |
Facet Value |
1 << 2 |
0x04 |
obj |
none |
hasChildren |
none |
2 << 2 |
0x08 |
bool |
bool |
name |
str |
3 << 2 |
0x0C |
int |
int |
href |
str |
4 << 2 |
0x10 |
real |
real |
is |
str |
5 << 2 |
0x14 |
str |
str |
of |
str |
6 << 2 |
0x18 |
enum |
str |
in |
str |
7 << 2 |
0x1C |
uri |
str |
out |
str |
8 << 2 |
0x20 |
abstime |
abstime |
null |
bool |
9 << 2 |
0x24 |
reltime |
reltime |
icon |
str |
10 << 2 |
0x28 |
date |
date |
displayName |
str |
11 << 2 |
0x2C |
time |
time |
display |
str |
12 << 2 |
0x30 |
list |
none |
writable |
bool |
13 << 2 |
0x34 |
op |
none |
min |
obj specific |
14 << 2 |
0x38 |
feed |
none |
max |
obj specific |
15 << 2 |
0x3C |
ref |
none |
unit |
str |
16 << 2 |
0x40 |
err |
none |
precision |
int |
17 << 2 |
0x44 |
childrenEnd |
none |
range |
str |
18 << 2 |
0x48 |
|
|
tz |
str |
19 << 2 |
0x4C |
|
|
status-0 |
status-0 |
20 << 2 |
0x50 |
|
|
status-1 |
status-1 |
21 << 2 |
0x54 |
|
|
customFacet |
facet specific |
Table 3‑1 Binary Constants
Each obj type and facet type MAY have an associated value encoding. For example, to encode the precision facet we must specify the facet code 0x40 plus the value of that facet which happens to be an integer. The object types bool, int, enum, real, str, uri, abstime, reltime, date, and time have always their value encoded (equivalent to the val attribute in XML).
The following boolean encodings are supported:
Constant |
Encoding |
Description |
0 |
false |
Indicates false value |
1 |
true |
Indicates true value |
Table 3‑2 Bool Encodings
The boolean encodings are fully specified in the 2-bit V mask. No extra bytes are required. Examples:
<bool val="false"/> => 08
<bool val="true"/> => 09
The obj code for bool is 0x08. In the case of false we bit-wise OR this with a value code of 0, so the complete encoding is the single byte 0x08. When val is true, we bitwise OR 0x08 with 0x01 with a result of 0x09.
The following integer encodings are supported:
Constant |
Encoding |
Description |
0 |
u1 |
Unsigned 8-bit integer value |
1 |
u2 |
Unsigned 16-bit integer value |
2 |
s4 |
Signed 32-bit integer value |
3 |
s8 |
Signed 64-bit integer value |
Table 3‑3 Int Encodings
Integers between 0 and 255 can be encoded in one byte. Larger numbers require 2, 4, or 8 bytes. Numbers outside of the 64-bit range are not supported. Examples:
<int val="34"/> => 0C 22
<int val="2093 "/> => 0D 08 2D
<int val="76000"/> => 0E 00 01 28 E0
<int val="-300"/> => 0E FF FF FE D4
<int val="12345678901"/> => 0F 00 00 00 02 DF DC 1C 35
The obj code for int is 0x0C. In first example, the value can be encoded as an unsigned 8-bit number, so we mask 0x0C with the value code 0x00 and then encode 34 using one byte. The second example is a u2 encoding, so we mask 0x0C with value code 0x01 to get 0x0D and then use two additional bytes to encode 2093 as a 16-bit unsigned integer. The other examples illustrate how values would be encoded in s4 and s8. Encoders SHOULD select the encoding type which results in the fewest number of bytes.
The following real encodings are supported:
Constant |
Encoding |
Description |
0 |
f4 |
32-bit IEEE floating point value |
1 |
f8 |
64-bit IEEE floating point value |
Table 3‑4 Real Encodings
Examples:
<real val="75.3"/> => 10 42 96 99 9A
<real val="15067.059"/> => 11 40 CD 6D 87 8D 4F DF 3B
The following str encodings are supported:
Constant |
Encoding |
Description |
0 |
utf8 |
null terminated UTF-8 string |
1 |
prev |
u2 index of previously encoded string |
Table 3‑5 Str Encodings
String encodings are used for many obj and facet values. Every time a string value is encoded within a given document, it is assigned a zero based index number. The first string encoded as utf8 is assigned zero, the second one, and so on. If subsequent string values have the exact same value, then the prev value encoding is used to reference the previous string via its index number. This requires binary decoders to keep track of all strings during decoding, since later occurrences in the document might reference that string.
Simple example which illustrates a null terminated string:
<str val="obix"/> => 14 6F 62 69 78 00
Complex example which illustrates two strings with the same value:
<obj>
<str val="abc"/>
<str val="abc"/>
</obj> => 84 04 14 61 62 63 00 15 00 00 44
The first byte 0x84 is the obj code masked with the more bit The next byte 0x04 is the hasChildren marker which indicates that children objects follow (covered further in section 3.5). The next byte is the 0x14 str obj code masked with the 0x00 utf8 value code followed by the 61 62 63 00 encoding of "abc". The next byte 0x15 is the str obj type 0x14 masked with the 0x01 prev value code, followed by the u2 encoding of index zero which references string value zero "abc". The last byte 0x44 is the end of children marker.
The following abstime encodings are supported:
Constant |
Encoding |
Description |
0 |
sec |
signed 32-bit number of seconds since epoch |
1 |
ns |
signed 64-bit number of nanoseconds since epoch |
Table 3‑6 Abstime Encodings
The epoch for OBIX timestamps is defined as midnight 1 January 2000 UTC. Times before the epoch are represented as negative numbers. Encoding with seconds provides a range of +/-68 years. The nanosecond encoding provides a range of +/-292 years. Timestamps outside of this range are not supported. Examples:
<abstime val="2000-01-30T00:00:00Z"/> => 20 00 26 3B 80
<abstime val="1999-12-01T00:00:00Z"/> => 20 FF D7 21 80
<abstime val="2009-10-20T13:00:00-04:00"/> => 20 12 70 A9 10
<abstime val="2009-10-20T13:00:00.123Z"/> => 21 04 4B 10 30 8D 78 F4 C0
The first example is encoded as 0x00263B80 which equates to 29x24x60x60 seconds since the OBIX epoch. The second example illustrates a negative number seconds for a timestamp before the epoch. The last example illustrates a 64-bit nanosecond encoding.
The following reltime encodings are supported:
Constant |
Encoding |
Description |
0 |
sec |
signed 32-bit number of seconds |
1 |
ns |
signed 64-bit number of nanoseconds |
Table 3‑7 Reltime Encodings
Consistent with the abstime encoding, both a second and nanosecond encoding are provided. No support is provided for ambiguous periods such as 1 month which dont map to a fixed number of seconds. Examples:
<reltime val="PT5M"/> => 24 00 00 01 2C
<reltime val="PT0.123S"/> => 25 00 00 00 00 07 54 D4 C0
The following time encodings are supported:
Constant |
Encoding |
Description |
0 |
sec |
unsigned 32-bit number of seconds since midnight |
1 |
ns |
unsigned 64-bit number of nanoseconds since midnight |
Table 3‑8 Time Encodings
The time encoding works similar to reltime using a number of seconds or nanoseconds since midnight. Examples:
<time val="04:30:00"/> => 2C 00 00 3F 48
<time val="04:30:00.123"/> => 2D 00 00 0E BB E2 93 A4 C0
The following date encodings are supported:
Constant |
Encoding |
Description |
0 |
yymd |
u2 year, u1 month 1-12, u1 day 1-31 |
Table 3‑9 Date Encodings
Dates are encoded using four bytes. The year is encoded as a common era year via a 16-bit integer, the month as a 8-bit integer between 1 and 12, and the day as an 8-bit integer between 1 and 31. Examples:
<date val="2009-10-20"/> => 28 07 D9 0A 14
The following status encodings are supported:
Constant |
Encoding |
Description |
0 |
status-0-disabled |
disabled status |
1 |
status-0-fault |
fault status |
2 |
status-0-down |
down status |
3 |
status-0-unacked-alarm |
unackedAlarm status |
0 |
status-1-alarm |
alarm status |
1 |
status-1-unacked |
unacked status |
2 |
status-1-overridden |
overridden status |
Table 3‑10 Status Encodings
The status facet is encoded inline to avoid consuming an extra byte. Since there are eight status values, but only 2-bits for the value encoding we use two different facet codes to give us the required range. The ok status is implied by omitting the status facet. Examples:
<obj status="ok"/> => 04
<obj status="disabled"/> => 84 4C // 0x4C | 0x00
<obj status="fault"/> => 84 4D // 0x4C | 0x01
<obj status="down"/> => 84 4E // 0x4C | 0x02
<obj status="unackedAlarm"/> => 84 4F // 0x4C | 0x03
<obj status="alarm"/> => 84 50 // 0x50 | 0x00
<obj status="unacked"/> => 84 51 // 0x50 | 0x01
<obj status="overridden"/> => 84 52 // 0x50 | 0x02
The first example illustrates the ok status, the entire document is encoded with the one byte obj type code of 0x40. The rest of the examples start with 0x84 which represents the obj type code masked with the more bit. Status values from disabled to unackedAlarm use facet code status-0 and from alarm to overridden use facet code status-1. It is illegal for a single object to define both the status-0 and status-1 facet codes.
Facets are encoded according to the value type as specified in the Binary Constants section. The min/max facet value types are implied by their containing object which must match the object value with exception of str which uses integers for min/max. Some examples:
<list name="foo"/> => B0 08 66 6F 6F 00
<list name="foo" displayName="Foo"/> => B0 88 66 6F 6F 00 28 46 6F 6F 00
<int val="3" min="0" max="100"/> => 8C 03 B4 00 38 64
<obj href="p4.2"/> => 84 0C 70 34 2E 32 00
Note that a string of multiple facets is indicated by masking the 0x80 more bit into the object/facet headers.
The following extension encodings are supported:
Constant |
Encoding |
Description |
0 |
extension |
Facet name encoded as string value object, followed by value object containing value associated with facet. |
Table 3‑11 Custom Facets
Custom facets are facets which are not specified by this standard but rather supplied by a particular implementation. Custom facets will include two objects immediately following the header byte: a string object, specifying the name of the facet, and a value object, specifying the value associated with the facet.
Both the string and value objects associated with the facet must provide a value, and neither object may supply additional facets or contain any child objects. Additionally, the value object associated with the facet must be one of the following object types:
Other types for the value object are not supported.
Examples:
<int val="34" my:int="50"/> => 8C 22 54 14 6D 79 3A 69 6E 6F 00 0C 32
<bool val="false" my:bool="true"/> => 88 54 14 6D 79 3A 69 6E 74 00 09
<bool val="true" my:str="hi!"/> => 89 54 14 6D 79 3A 73 74 72 00 14 68 69 21 00
The special facet code hasChildren and the special object code endChildren are used to encode nested children objects. Lets look at a simple example:
<obj> <bool val="false"/> </obj> => 84 04 08 44
Lets examine each byte: the first byte 0x84 is the mask of obj type code 0x04 with the 0x80 more bit indicating a facet follows. The 0x04 facet code indicates the obj has children. The next byte is interpreted as the beginning of a new object, which is the bool object code 0x08. Since the more bit is not set on the bool object, there are no more facets. The next byte is the endChildren object code indicating weve reached the end of the children objects for obj. It serves a similar purpose as the end tag in XML.
Technically the hasChildren facet could have additional facets following it by setting the more bit. However, this specification requires that the hasChildren facet is always declared last within a given objects facet list. This makes it an encoding error to have the more bit set on the hasChildren facet code.
Lets look a more complicated example with multiple nested children:
<obj href="xyz">
<bool val="false"/>
<obj><int val="255"/></obj>
</obj> => B0 8C 78 79 7A 00 04 08 84 04 0C FF 44 44
<obj> => 84 // 0x80 | 0x04
href="xyz" => 8C 78 79 7A 00 // 0x80 | 0x0C | 0x00 + x + y + z
hasChildren => 04
<bool val="false"/> => 08
<obj> => 84 // 0x80 | 0x04
hasChildren => 04
<int val="255" => 0C FF // 0x0C | 0x00 + u1 of 255
endChildren </obj> => 44
endChildren </obj> => 44
The Java script object notation is a lightweight, text-based, language-independent data interchange format. It is derived from the object literals of JavaScript, as defined in the ECMAScript Programming Language Standard (ECMA) [RFC4627].
JSON uses two structures for representing information:
In JSON an object is an unordered set of name/value pairs and the encoding of an object starts with a left brace and ends with a right brace. A colon is used to separate the name and the value and a comma separates multiple name/value pairs. The JSON encoding of OBIX is inspired by JSONML, which provides a lossless two-way conversation between JSON and XML. A Java reference implementation can be found here[1].
The following grammar is used to represent OBIX objects:
element
= '{' obix-identifier ',' attribute-list ', "children":[' element-list ']}'
| '{' obix-identifier ',' attribute-list '}'
| '{' obix-identifier ', "children":['element-list ']}'
| '{' obix-identifier '}'
| string
;
obix-identifier
= "obix":type-name
;
type-name
= string
;
attribute-list
= attribute ',' attribute-list
| attribute
;
attribute
= attribute-name ':' attribute-value
;
attribute-name
= string
;
attribute-value
= string
| number
| 'true'
| 'false'
;
element-list
= element ',' element-list
| element
;
Objects MUST be encoded according to the grammar given above. The OBIX object is encoded as JSON object which an unordered list of name/value pairs. The object type which is used as element name in XML is encoded as a name/value pair using "tag" as name and the object type as string value.
The XML and JSON representation of a simple obj:
<obj/> à {"obix":"obj"}
The attributes of an object are mapped to name value/pairs:
<obj name="myName" href="/myHref"> à {"obix":"obj", "name":"myName", "href":"/myHref"/>
If objects have an extent, the children objects contained in this extend are mapped to a name/value pair using "children" as name and an ordered array of objects as value.
The XML representation of an object with extend is mapped to the JSON representation as shown in the examples below.
XML:
<obj href="/a/">
<obj name="b" href="b">
<obj name="c"/>
<ref name="d" href="d"/>
</obj>
</obj>
JSON:
{
"obix": "obj",
"href": "/a",
"children": [{
"obix": "obj",
"name": "b",
"href": "b",
"children": [{
"obix": "obj",
"name": "c",
}, {
"obix": "ref",
"name": "d",
"href": "d",
}]
}]
}
The xs:boolean val attribute of the bool object is mapped to the true or false literals of JSON.
<bool val="true"/> à {"obix":"bool", "val":true}
The xs:long val attribute of the int object is mapped to the number representation of JSON.
<int val="5"/> à {"obix":"int", "val":5}
The xs:double val attribute of the real object is mapped to the number representation of JSON.
<real val="5.5"/> à {"obix":"real", "val":5.5}
All other types and facets are mapped to name/value pairs using JSON string representation. Facets are mapped to name/value pairs as described by the rules above.
If namespace information should be preserved in the JSON encoding, namespace prefixes SHOULD be normalized before the object is encoded to JSON as shown in the examples below:
Object with namespace prefixes in use:
<obj xmlns:acme="http://acme.com/def/" href="acme:CustomPoint"
is="acme:Point obix:Point"/>
Object with normalized namespace information:
<obj href="http://acme.com/def/CustomPoint"
is="http://acme.com/def/Point http://docs.oasis-open.org/obix/ns/201410/def/Point"/>
JSON encoded object with normalized namespace information:
{obix:"obj", href:"http://acme.com/def/CustomPoint", is:"http://acme.com/def/Point http://docs.oasis-open.org/obix/ns/201410/def/Point"}
The following examples illustrate the JSON encoding:
Example OBIX About:
XML:
<obj name="about">
<str name="obixVersion" val="1.1"/>
<str name="serverName" val="obix"/>
<abstime name="serverTime" val="2006-02-08T09:40:55.000+05:00:00Z"/>
<abstime name="serverBootTime" val="2006-02-08T09:33:31.980+05:00:00Z"/>
<str name="vendorName" val="Acme, Inc."/>
<uri name="vendorUrl" val="http://www.acme.com"/>
<str name="productName" val="Acme OBIX Server"/>
<str name="productVersion" val="1.0.3"/>
<uri name="productUrl" val="http://www.acme.com/obix"/>
</obj>
JSON:
{"obix":"obj", "name":"about", "children":[
{"obix":"str", "name":"obixVersion", "val":"1.1"},
{"obix":"str", "name":"serverName", "val":"obix"},
{"obix":"abstime", "name":"serverTime", "val":"2006-02-08T09:40:55.000+05:00:00Z"},
{"obix":"abstime", "name":"serverBootTime", "val":"2006-02-08T09:33:31.980+05:00:00Z"},
{"obix":"str","name":"vendorName", "val":"Acme, Inc."},
{"obix":"uri","name":"vendorURL", "val":"http://www.acme.com"},
{"obix":"str","name":"productName", "val":"Acme OBIX Server"},
{"obix":"str","name":"productVersion","val":"1.0.3"},
{"obix":"uri","name":"prodctUrl","val":"http://www.acme.com/obix"}
]}
If a client wants to use JSON encoding it MUST use the JSON MIME type application/json according to [RFC4627].
The Efficient XML Interchange [EXI] format is a very compact representation for XML which aims at providing high performance and significantly reduced bandwidth requirements for XML based protocols. It uses a grammar driven approach based on entropy encoding which can be used with schema information but also without any schema information.
EXI provides several encoding options that communicating parties need to agree upon in order to ensure interoperability.
If EXI encoding is used for OBIX the following options MUST be used by a client and server implementation.
In contrast to XML EXI is by default bit-packed, which means the information is stored in the most compact representation as possible, regardless of possible byte boundaries. This allows for example to store 8 Boolean values into one single Byte, versus 8 Bytes with a single character representing the value, e.g. T or F. If a textual representation like true or false is used, 4 to 5 Bytes are used for representing the Boolean value.
EXI defines 4 options for alignment: compress, preCompress, byteAligned and bitPacked.
In order to have the best possible compression for OBIX bitPacked alignment MUST be used.
EXI implementation may provide preservation options specifying which type of XML information should be remained in the EXI representation, like comments, programming instructions, document type declarations and namespace.
For OBIX only name space declarations MUST be preserved. Every other non-relevant information MAY be omitted.
EXI can be used without any schema information about the XML infoset that shall be encoded. This has the advantage that no schema information is required at the decoders site, but comes with the disadvantage of being less efficient and providing only a limited compression for small payloads.
Schema-informed EXI allows making the encoding most efficient even for small payload sizes. Within constrained environments schema-informed EXI SHALL be used to in order to have the best compression effect. With object encoders and decoders even the performance penalty of processing XML structures in memory can be avoided.
For schema-informed the normative obix.xsd schema file representing the OBIX 1.1 object model MUST be used in order to provide interoperability among different vendor implementations.
For content negotiation and to determine if schema-informed or non-schema-informed EXI encoding should be used either an out-of-band agreement between a client and server need to be done or the EXI best practices [EXI BP] or the guidelines in [EXI MR] need to be followed.
If a client wants to use EXI encoding it MUST use the MIME type application/exi for EXI without schema information and the MIME type application/x-obix-exi for schema-informed representation.
An implementation is compliant with this specification if it implements all MUST or REQUIRED level requirements. An implementation MUST specify its supported encodings.
The following individuals have participated in the creation of this specification and are gratefully acknowledged:
Participants:
Ron Ambrosio, IBM
Brad Benson, Trane
Ron Bernstein, LonMark International*
Ludo Bertsch, Continental Automated Buildings Association (CABA)
Chris Bogen, US Department of Defense
Rich Blomseth, Echelon Corporation
Anto Budiardjo, Clasma Events, Inc.
Jochen Burkhardt, IBM
JungIn Choi, Kyungwon University
David Clute, Cisco Systems, Inc.*
Toby Considine, University of North Carolina at Chapel Hill
William Cox, Individual
Robert Dolin, Echelon Corporation
Marek Dziedzic, Treasury Board of Canada, Secretariat
Brian Frank, SkyFoundry
Craig Gemmill, Tridium, Inc.
Matthew Giannini, Tridium, Inc.
Christopher Kelly, Cisco Systems
Wonsuk Ko, Kyungwon University
Perry Krol, TIBCO Software Inc.
Corey Leong, Individual
Ulf Magnusson, Schneider Electric
Brian Meyers, Trane
Jeremy Roberts, LonMark International
Thorsten Roggendorf, Echelon Corporation
Anno Scholten, Individual
John Sublett, Tridium, Inc.
Dave Uden, Trane
Ron Zimmer, Continental Automated Buildings Association (CABA)*
Rob Zivney, Hirsch Electronics Corporation
Markus Jung, Institute of Computer Aided Automation, Vienna University of Technology
Revision |
Date |
Editor |
Changes Made |
wd01 |
26 Mar 13 |
Markus Jung |
Initial creation with XML and Binary encoding taken from the OBIX 1.1 WD07 working draft. |
wd02 |
24 Apr 13 |
Markus Jung |
First draft JSON and EXI encoding. |
wd03 |
22 May 13 |
Markus Jung |
Added JSON section on handling XML namespaces, shorter JSON names. |
wd04 |
13 Jun 13 |
Markus Jung |
Refined the use of examples (normative/non normative), EXI content negotiation. |
wd05 |
28 Jun 13 |
Markus Jung |
Updated reference section |
wd06 |
8 Jul 13 |
Toby Considine |
Updated acknowledgements |
wd07 |
2 Oct 13 |
Markus Jung |
Jira: OBIX-7, OBIX-56, OBIX-5, OBIX-6, OBIX-48 |
wd08 |
7 Nov 13 |
Markus Jung |
Namespace rules, using straight quotes within the document. |
wd09 |
12 Dec 13 |
Markus Jung |
Fixed minor error (JSON encoding for real). Update OBIX namespace to current policy. |
wd10 |
16 Dec 13 |
Markus Jung |
Updated namespace (including date), using uppercase for OBIX |
wd11 |
16 Dec 13 |
Markus Jung |
Minor fixes: OBIX-79 |
wd12 |
17 Apr 14 |
Markus Jung |
OBIX-209, OBIX-208 |
wd13 |
26 May 14 |
Markus Jung |
OBIX-153, OBIX-151, OBIX-149, OBIX-145, preparation for public review |
Wd14 |
5 Nov 14 |
Toby Considine |
Cleaned up template used, namespace |