OBIX Version 1.

1
Committee Specification 01
14 September 2015
Specification URIs
This version:
http://docs.oasis-open.org/obix/obix/v1.1/cs01/obix-v1.1-cs01.pdf (Authoritative)
http://docs.oasis-open.org/obix/obix/v1.1/cs01/obix-v1.1-cs01.html
http://docs.oasis-open.org/obix/obix/v1.1/cs01/obix-v1.1-cs01.doc
Previous version:
http://docs.oasis-open.org/obix/obix/v1.1/csprd03/obix-v1.1-csprd03.pdf (Authoritative)
http://docs.oasis-open.org/obix/obix/v1.1/csprd03/obix-v1.1-csprd03.html
http://docs.oasis-open.org/obix/obix/v1.1/csprd03/obix-v1.1-csprd03.doc
Latest version:
http://docs.oasis-open.org/obix/obix/v1.1/obix-v1.1.pdf (Authoritative)
http://docs.oasis-open.org/obix/obix/v1.1/obix-v1.1.html
http://docs.oasis-open.org/obix/obix/v1.1/obix-v1.1.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:
Craig Gemmill (craig.gemmill@tridium.com), Tridium
Additional artifacts:
This prose specification is one component of a Work Product that also includes:
 XML schema: http://docs.oasis-open.org/obix/obix/v1.1/cs01/schemas/obix-v1.1.xsd
 Core contract library: http://docs.oasis-open.org/obix/obix/v1.1/cs01/schemas/stdlib.obix
Related work:
This specification replaces or supersedes:
 oBIX 1.0. Edited by Brian Frank. 05 December 2006. Committee Specification 01.
https://www.oasis-open.org/committees/download.php/21812/obix-1.0-cs-01.pdf.
This specification is related to:
 Bindings for OBIX: REST Bindings Version 1.0. Edited by Craig Gemmill and Markus Jung.
Latest version. http://docs.oasis-open.org/obix/obix-rest/v1.0/obix-rest-v1.0.html.
 Bindings for OBIX: SOAP Bindings Version 1.0. Edited by Markus Jung. Latest version.
http://docs.oasis-open.org/obix/obix-soap/v1.0/obix-soap-v1.0.html.
 Encodings for OBIX: Common Encodings Version 1.0. Edited by Markus Jung. Latest
version. http://docs.oasis-open.org/obix/obix-encodings/v1.0/obix-encodings-v1.0.html.
 Bindings for OBIX: Web Socket Bindings Version 1.0. Edited by Matthias Hub. Latest version.
http://docs.oasis-open.org/obix/obix-websocket/v1.0/obix-websocket-v1.0.html.
Declared XML namespaces:
 http://docs.oasis-open.org/obix/ns/201506
 http://docs.oasis-open.org/obix/ns/201506/schema/obix
obix-v1.1-cs01 14 September 2015
Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 1 of 79
Abstract:
This document specifies an object model used for machine-to-machine (M2M) communication.
Companion documents will specify the protocol bindings and encodings for specific cases.
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 TC’s email list. Others should
send comments to the TC’s public comment list, after subscribing to it by following the
instructions at the “Send A Comment” button on the TC’s 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 TC’s 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-v1.1]
OBIX Version 1.1. Edited by Craig Gemmill. 14 September 2015. OASIS Committee Specification
01. http://docs.oasis-open.org/obix/obix/v1.1/cs01/obix-v1.1-cs01.html. Latest version:
http://docs.oasis-open.org/obix/obix/v1.1/obix-v1.1.html.

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 2 of 79
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.

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 3 of 79
Table of Contents
Table of Figures ............................................................................................................................................ 7
Table of Tables ............................................................................................................................................. 7
1 Introduction ........................................................................................................................................... 9
1.1 Terminology ........................................................................................................................................ 9
1.2 Normative References ........................................................................................................................ 9
1.3 Non-Normative References ................................................................................................................ 9
1.4 Namespace ....................................................................................................................................... 10
1.5 Naming Conventions ........................................................................................................................ 10
1.6 Editing Conventions .......................................................................................................................... 10
1.7 Language Conventions ..................................................................................................................... 11
1.7.1 Definition of Terms .................................................................................................................... 11
1.8 Architectural Considerations ............................................................................................................. 12
1.8.1 Information Model ...................................................................................................................... 12
1.8.2 Interactions ................................................................................................................................ 12
1.8.3 Normalization............................................................................................................................. 12
1.8.4 Foundation................................................................................................................................. 13
1.9 Changes from Version 1.0 [non-normative] ...................................................................................... 13
2 Quick Start [non-normative] ................................................................................................................ 14
3 Architecture ........................................................................................................................................ 16
3.1 Design Philosophies ......................................................................................................................... 16
3.2 Object Model ..................................................................................................................................... 16
3.3 Encodings ......................................................................................................................................... 16
3.4 URIs .................................................................................................................................................. 17
3.5 REST ................................................................................................................................................ 17
3.6 Contracts........................................................................................................................................... 17
3.7 Extensibility ....................................................................................................................................... 18
4 Object Model ...................................................................................................................................... 19
4.1 Object Model Description .................................................................................................................. 19
4.2 obj ..................................................................................................................................................... 20
4.2.1 name.......................................................................................................................................... 20
4.2.2 href ............................................................................................................................................ 20
4.2.3 is ................................................................................................................................................ 20
4.2.4 null ............................................................................................................................................. 20
4.2.5 val .............................................................................................................................................. 21
4.2.6 ts ................................................................................................................................................ 21
4.2.7 Facets ........................................................................................................................................ 21
4.3 Core Types ....................................................................................................................................... 24
4.3.1 val .............................................................................................................................................. 25
4.3.2 list .............................................................................................................................................. 28
4.3.3 ref .............................................................................................................................................. 28
4.3.4 err .............................................................................................................................................. 29
4.3.5 op ............................................................................................................................................... 29
4.3.6 feed ............................................................................................................................................ 29

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 4 of 79
5 Lobby .................................................................................................................................................. 30
5.1 Lobby Object ..................................................................................................................................... 30
5.2 About................................................................................................................................................. 30
5.3 Batch ................................................................................................................................................. 31
5.4 WatchService .................................................................................................................................... 32
5.5 Server Metadata ............................................................................................................................... 32
5.5.1 Tag Spaces ............................................................................................................................... 32
5.5.2 Versioning.................................................................................................................................. 33
5.5.3 Encodings .................................................................................................................................. 34
5.5.4 Bindings ..................................................................................................................................... 34
6 Naming ............................................................................................................................................... 36
6.1 Name ................................................................................................................................................ 36
6.2 Href ................................................................................................................................................... 36
6.3 URI Normalization ............................................................................................................................. 36
6.4 Fragment URIs ................................................................................................................................. 37
7 Contracts and Contract Lists .............................................................................................................. 38
7.1 Contract Terminology ....................................................................................................................... 38
7.2 Contract List ...................................................................................................................................... 38
7.3 Is Attribute ......................................................................................................................................... 39
7.4 Contract Inheritance ......................................................................................................................... 39
7.4.1 Structure vs Semantics ............................................................................................................. 39
7.4.2 Overriding Defaults .................................................................................................................... 40
7.4.3 Attributes and Facets ................................................................................................................ 40
7.5 Override Rules .................................................................................................................................. 41
7.6 Multiple Inheritance ........................................................................................................................... 41
7.6.1 Flattening ................................................................................................................................... 41
7.6.2 Mixins ........................................................................................................................................ 42
7.7 Contract Compatibility....................................................................................................................... 43
7.8 Lists and Feeds ................................................................................................................................ 43
8 Operations .......................................................................................................................................... 45
9 Object Composition ............................................................................................................................ 46
9.1 Containment ..................................................................................................................................... 46
9.2 References........................................................................................................................................ 46
9.3 Extents .............................................................................................................................................. 46
9.4 Metadata ........................................................................................................................................... 47
10 Networking .......................................................................................................................................... 49
10.1 Service Requests ............................................................................................................................ 49
10.1.1 Read ........................................................................................................................................ 49
10.1.2 Write ........................................................................................................................................ 49
10.1.3 Invoke ...................................................................................................................................... 50
10.1.4 Delete ...................................................................................................................................... 50
10.2 Errors .............................................................................................................................................. 50
10.3 Localization ..................................................................................................................................... 51
11 Core Contract Library ......................................................................................................................... 52
11.1 Nil .................................................................................................................................................... 52

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 5 of 79
 11.2 Range ............................................................................................................................................. 52
11.3 Weekday ......................................................................................................................................... 52
11.4 Month .............................................................................................................................................. 52
11.5 Units ................................................................................................................................................ 53
12 Watches .............................................................................................................................................. 55
12.1 Client Polled Watches..................................................................................................................... 55
12.2 Server Pushed Watches ................................................................................................................. 55
12.3 WatchService .................................................................................................................................. 56
12.4 Watch .............................................................................................................................................. 56
12.4.1 Watch.add ............................................................................................................................... 57
12.4.2 Watch.remove ......................................................................................................................... 57
12.4.3 Watch.pollChanges ................................................................................................................. 58
12.4.4 Watch.pollRefresh ................................................................................................................... 58
12.4.5 Watch.lease ............................................................................................................................. 58
12.4.6 Watch.delete............................................................................................................................ 58
12.5 Watch Depth ................................................................................................................................... 58
12.6 Feeds .............................................................................................................................................. 59
13 Points .................................................................................................................................................. 60
13.1 Writable Points ................................................................................................................................ 60
14 History ................................................................................................................................................ 61
14.1 History Object ................................................................................................................................. 61
14.1.1 History prototype ..................................................................................................................... 62
14.2 History Queries ............................................................................................................................... 62
14.2.1 HistoryFilter ............................................................................................................................. 62
14.2.2 HistoryQueryOut ...................................................................................................................... 63
14.2.3 HistoryRecord .......................................................................................................................... 63
14.2.4 History Query Examples .......................................................................................................... 64
14.3 History Rollups ................................................................................................................................ 65
14.3.1 HistoryRollupIn ........................................................................................................................ 65
14.3.2 HistoryRollupOut ..................................................................................................................... 65
14.3.3 HistoryRollupRecord ............................................................................................................... 65
14.3.4 Rollup Calculation ................................................................................................................... 66
14.4 History Feeds .................................................................................................................................. 67
14.5 History Append ............................................................................................................................... 67
14.5.1 HistoryAppendIn ...................................................................................................................... 67
14.5.2 HistoryAppendOut ................................................................................................................... 67
15 Alarms ................................................................................................................................................ 69
15.1 Alarm States ................................................................................................................................... 69
15.1.1 Alarm Source ........................................................................................................................... 69
15.1.2 StatefulAlarm and AckAlarm ................................................................................................... 70
15.2 Alarm Contracts .............................................................................................................................. 70
15.2.1 Alarm ....................................................................................................................................... 70
15.2.2 StatefulAlarm ........................................................................................................................... 70
15.2.3 AckAlarm ................................................................................................................................. 70
15.2.4 PointAlarms ............................................................................................................................. 71

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 6 of 79
 15.3 AlarmSubject .................................................................................................................................. 71
15.4 Alarm Feed Example ...................................................................................................................... 71
16 Security ............................................................................................................................................... 73
16.1 Error Handling ................................................................................................................................. 73
16.2 Permission-based Degradation ...................................................................................................... 73
17 Conformance ...................................................................................................................................... 74
17.1 Conditions for a Conforming OBIX Server ...................................................................................... 74
17.1.1 Lobby ....................................................................................................................................... 74
17.1.2 Tag Spaces ............................................................................................................................. 74
17.1.3 Bindings ................................................................................................................................... 74
17.1.4 Encodings ................................................................................................................................ 74
17.1.5 Contracts ................................................................................................................................. 74
17.2 Conditions for a Conforming OBIX Client ....................................................................................... 75
17.2.1 Bindings ................................................................................................................................... 75
17.2.2 Encodings ................................................................................................................................ 75
17.2.3 Naming .................................................................................................................................... 75
17.2.4 Contracts ................................................................................................................................. 75
17.3 Interaction with other Implementations ........................................................................................... 75
17.3.1 Unknown Elements and Attributes .......................................................................................... 75
Appendix A. Acknowledgments ............................................................................................................. 76
Appendix B. Revision History ................................................................................................................ 77

Table of Figures
Figure 4-1. The OBIX primitive object hierarchy ........................................................................................ 19

Table of Tables
Table 1-1. Definition of Terms. .................................................................................................................... 12
Table 1-2. Problem spaces for OBIX. ......................................................................................................... 12
Table 1-3. Normalization concepts in OBIX. ............................................................................................... 12
Table 1-4. Changes from Version 1.0. ........................................................................................................ 13
Table 3-1. Design philosophies and principles for OBIX. ........................................................................... 16
Table 7-1. Problems addressed by Contracts............................................................................................. 38
Table 7-2. Contract terminology. ................................................................................................................. 38
Table 7-3. Explicit and Implicit Contracts. ................................................................................................... 40
Table 7-4. Contract inheritance. .................................................................................................................. 41
Table 10-1. Network model for OBIX. ......................................................................................................... 49
Table 10-2. OBIX Service Requests. .......................................................................................................... 49
Table 10-3. OBIX Error Contracts. .............................................................................................................. 50
Table 11-1. OBIX Unit composition. ............................................................................................................ 54
Table 13-1. Base Point types. ..................................................................................................................... 60
Table 14-1. Features of OBIX Histories. ..................................................................................................... 61
Table 14-2. Properties of obix:History. ........................................................................................................ 62
obix-v1.1-cs01 14 September 2015
Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 7 of 79
Table 14-3. Properties of obix:HistoryFilter. ................................................................................................ 63
Table 14-4. Properties of obix:HistoryRollupRecord. .................................................................................. 66
Table 14-5. Calculation of OBIX History rollup values. ............................................................................... 67
Table 15-1. Alarm states in OBIX. .............................................................................................................. 69
Table 15-2. Alarm lifecycle states in OBIX. ................................................................................................. 70
Table 16-1. Security concepts for OBIX. ..................................................................................................... 73

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 8 of 79
1 1 Introduction
2 OBIX is designed to provide access to the embedded software systems which sense and control the
3 world around us. Historically, integrating to these systems required custom low level protocols, often
4 custom physical network interfaces. The rapid increase in ubiquitous networking and the availability of
5 powerful microprocessors for low cost embedded devices is now weaving these systems into the very
6 fabric of the Internet. Generically the term M2M for Machine-to-Machine describes the transformation
7 occurring in this space because it opens a new chapter in the development of the Web - machines
8 autonomously communicating with each other. The OBIX specification lays the groundwork for building
9 this M2M Web using standard, enterprise-friendly technologies like XML, HTTP, and URIs.

10 1.1 Terminology
11 The keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD
12 NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described
13 in [RFC2119]. When used in the non-capitalized form, these words are to be interpreted with their normal
14 English meaning.

15 1.2 Normative References

16 PNG Portable Network Graphics (PNG) Specification (Second Edition) , D. Duce,
17 Editor, W3C Recommendation, 10 November 2003,
18 http://www.w3.org/TR/2003/REC-PNG-20031110. Latest version available
19 at http://www.w3.org/TR/PNG.
20 RFC2119 Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels”, BCP
21 14, RFC 2119, March 1997. http://www.ietf.org/rfc/rfc2119.txt.
22 RFC3986 Berners-Lee, T., Fielding, R., and Masinter, L., “Uniform Resource Identifier
23 (URI): Generic Syntax”, STD 66, RFC 3986, January 2005.
24 http://www.ietf.org/rfc/rfc3986.txt.
25 SI Units A. Thompson and B. N. Taylor, The NIST Guide for the use of the International
26 System of Units (SI), NIST Special Publication 811, 2008 Edition.
27 http://www.nist.gov/pml/pubs/sp811/index.cfm.
28 XML Schema XML Schema Part 2: Datatypes Second Edition , P. V. Biron, A. Malhotra,
29 Editors, W3C Recommendation, 28 October 2004,
30 http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/. Latest version
31 available at http://www.w3.org/TR/xmlschema-2/.
32 ZoneInfo DB IANA Time Zone Database, 24 September 2013 (latest version),
33 http://www.iana.org/time-zones.

34 1.3 Non-Normative References

35 CamelCase Use of Camel Case for Naming XML and XML-Related Components, OASIS
36 Technology Report, December 29, 2005.
37 http://xml.coverpages.org/camelCase.html.
38 OBIX REST Bindings for OBIX: REST Bindings Version 1.0. Edited by Craig Gemmill and
39 Markus Jung. Latest version. http://docs.oasis-open.org/obix/obix-rest/v1.0/obix-
40 rest-v1.0.html.
41 OBIX SOAP Bindings for OBIX: SOAP Bindings Version 1.0. Edited by Markus Jung. Latest
42 version. http://docs.oasis-open.org/obix/obix-soap/v1.0/obix-soap-v1.0.html.
43 OBIX Encodings Encodings for OBIX: Common Encodings Version 1.0. Edited by Markus Jung.
44 Latest version. http://docs.oasis-open.org/obix/obix-encodings/v1.0/obix-
45 encodings-v1.0.html.

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 9 of 79
46 OBIX WebSocket Bindings for OBIX: Web Socket Bindings Version 1.0. Edited by Matthias Hub.
47 Latest version. http://docs.oasis-open.org/obix/obix-websocket/v1.0/obix-
48 websocket-v1.0.html.
49 RDDL 2.0 Jonathan Borden, Tim Bray, eds. “Resource Directory Description Language
50 (RDDL) 2.0,” January 2004.
51 http://www.openhealth.org/RDDL/20040118/rddl-20040118.html.
52 REST Fielding, R.T., “Architectural Styles and the Design of Network-based Software
53 Architectures”, Dissertation, University of California at Irvine, 2000.
54 http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm
55 RFC2818 Rescorla, E., “HTTP over TLS”, RFC 2818, May 2000.
56 http://www.ietf.org/rfc/rfc2818.txt.
57 RFC5785 Nottingham, M., Hammer-Lahav, E., “Defining Well-Known Uniform Resource
58 Identifiers (URIs)”, RFC 5785, April 2010. http://www.ietf.org/rfc/rfc5785.txt.
59 UML Unified Modeling Language (UML), Version 2.4.1, Object Management Group,
60 May 07, 2012. http://uml.org/.
61 XLINK XML Linking Language (XLink) Version 1.1 , S. J. DeRose, E. Maler, D. Orchard,
62 N. Walsh, Editors, W3C Recommendation, 6 May 2010,
63 http://www.w3.org/TR/2010/REC-xlink11-20100506/. Latest version available at
64 http://www.w3.org/TR/xlink11/.
65 XML-ns Namespaces in XML , T. Bray, D. Hollander, A. Layman, Editors, W3C
66 Recommendation, 14 January 1999, http://www.w3.org/TR/1999/REC-xml-
67 names-19990114/. Latest version available at http://www.w3.org/TR/REC-xml-
68 names.

69 1.4 Namespace
70 If an implementation is using the XML Encoding according to the [OBIX Encodings] specification
71 document, the XML namespace [XML-ns] URI that MUST be used is:
72 http://docs.oasis-open.org/obix/ns/201506/schema/obix
73 Dereferencing the above URI will produce a document that describes this namespace and provides links
74 to the schema and the core contract library.
75 Along with the schema, there is a normative XML artifact that describes the core contract library as
76 described in Section 11. This artifact can be retrieved at:
77 http://docs.oasis-open.org/obix/ns/201506/stdlib.obix

78 1.5 Naming Conventions

79 Where XML is used, the names of elements and attributes in XSD files follow Lower Camel Case
80 capitalization rules (see [CamelCase] for a description).

81 1.6 Editing Conventions

82 For readability, Element names in tables appear as separate words. In the Schema, they follow the rules
83 as described in Section 1.5.
84 Terms defined in this specification or used from specific cited references are capitalized; the same term
85 not capitalized has its normal English meaning.
86 Examples and Contract definitions are Non-Normative. They are marked with the following style:
87 <str name="example" val="This is an example, which is non-normative."/>
88 Schema fragments included in this specification as XML Contract definitions are Non-Normative; in the
89 event of disagreement between the two, the formal Schema supersedes the examples and Contract
90 definitions defined here.
91 All UML and figures are illustrative and SHALL NOT be considered normative.

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 10 of 79
92 1.7 Language Conventions
93 Although several different encodings may be used for representing OBIX data, the most common is XML.
94 Therefore many of the concepts in OBIX are strongly tied to XML concepts. Data objects are represented
95 in XML by XML documents. It is important to distinguish the usage of the term document in this context
96 from references to this specification document. When “this document” is used, it references this
97 specification document. When “OBIX document” or “XML document” is used, it references an OBIX
98 object, encoded in XML, as per the convention for this (specification) document. When used in the latter
99 context, this could equally be understood to mean an OBIX object encoded in any of the other possible
100 encoding mechanisms.
101 When expressed in XML, there is a one-to-one-mapping between Objects and elements. Objects are the
102 fundamental abstraction used by the OBIX data model. Elements are how those Objects are expressed in
103 XML syntax. This specification uses the term Object and sub-Object, although one can equivalently
104 substitute the term element and sub-element when referencing the XML representation. The term child is
105 used to describe an Object that is contained by another Object, and is semantically equivalent to the term
106 sub-Object. The two terms are used interchangeably throughout this specification.

107 1.7.1 Definition of Terms

108 Several named terms are used within this document. The following table describes the terms and
109 provides an explanation of their meaning in the context of this specification.

Term Meaning Introduced

In

Client An entity which makes requests to Servers over a network to access 10

OBIX-enabled data and services.

Contract A standard OBIX object used as a template for describing a set of 3.6, 7
values and semantics. Objects implement Contracts to advertise
data and services with which other devices may interact.

Contract List A sequence of Contracts referenced by an OBIX Object describing 3.6, 7

the Contracts which the Object implements

Extent The tree of child Objects contained within an Object. 9.3

Facet An attribute of an Object that provides additional metadata about the 4.2.7
Object.

Feed An Object that tracks every event rather than retaining only the 4.3.6
current state. This is typically used in alarm monitoring and history
record retrieval.
Object The base abstraction for expressing a piece of information in OBIX. 4.1
The Schema uses the name Obj for brevity, but the two terms Obj
and Object are equivalent.

Rollup An operation available on History objects to summarize the history 14.3

data by a specific interval of time.

Server An entity containing OBIX enabled data and services. Servers 10

respond to requests from Client over a network.
Tag A name-value pair that provides additional information about an 9.4
Object, presented as a child Object of the original Object.

Val A special type of Object, that stores a piece of information (a ‘value’) 4.3.1
in a specific attribute named “val”.

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 11 of 79
110 Table 1-1. Definition of Terms.
111

112 1.8 Architectural Considerations

113 Table 1-1 illustrates the problem space OBIX attempts to address. Each of these concepts is covered in
114 the subsequent sections of the specification as shown.
Concept Solution Covered in
Sections

Information Representing M2M information in a standard syntax – 4, 5, 6, 8, 9

Model originally XML but expanded to other technologies
Interactions transferring M2M information over a network 10

Normalization developing standard representations for common M2M 11, 12, 13, 14, 15
features: points, histories, and alarms
Foundation providing a common kernel for new standards 7, 11

115 Table 1-2. Problem spaces for OBIX.

116 1.8.1 Information Model

117 OBIX defines a common information model to represent diverse M2M systems and an interaction model
118 for their communications. The design philosophy of OBIX is based on a small but extensible data model
119 which maps to a simple fixed syntax. This core model and its syntax are simple enough to capture entirely
120 in one illustration, which is done in Figure 4-1. The object model’s extensibility allows for the definition of
121 new abstractions through a concept called Contracts. Contracts are flexible and powerful enough that
122 they are even used to define the majority of the conformance rules in this specification.

123 1.8.2 Interactions

124 Once a way exists to represent M2M information in a common format, the next step is to provide standard
125 mechanisms to transfer it over networks for publication and consumption. OBIX breaks networking into
126 two pieces: an abstract request/response model and a series of protocol bindings which implement that
127 model. In Version 1.1 of OBIX, the two goals are accomplished in separate documents: this core
128 specification defines the core model, while several protocol bindings designed to leverage existing Web
129 Service infrastructure are described in companion documents to this specification.

130 1.8.3 Normalization

131 There are a few concepts which have broad applicability in systems which sense and control the physical
132 world. Version 1.1 of OBIX provides a normalized representation for three of these, described in Table
133 1-2.
Concept Description

Points Representing a single scalar value and its status – typically these map to
sensors, actuators, or configuration variables like a setpoint
Histories Modeling and querying of time sampled point data. Typically edge devices
collect a time stamped history of point values which can be fed into higher level
applications for analysis
Alarms Modeling, routing, and acknowledgment of alarms. Alarms indicate a condition
which requires notification of either a user or another application

134 Table 1-3. Normalization concepts in OBIX.

obix-v1.1-cs01 14 September 2015
Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 12 of 79
135 1.8.4 Foundation
136 The requirements and vertical problem domains for M2M systems are immensely broad – too broad to
137 cover in one single specification. OBIX is deliberately designed as a fairly low level specification, but with
138 a powerful extension mechanism based on Contracts. The goal of OBIX is to lay the groundwork for a
139 common object model and XML syntax which serves as the foundation for new specifications. It is hoped
140 that a stack of specifications for vertical domains can be built upon OBIX as a common foundation.

141 1.9 Changes from Version 1.0 [non-normative]

142 Several areas of the specification have changed from Version 1.0 to Version 1.1. Table 1-3 below lists
143 key differences between Versions 1.0 and 1.1. Implementers of earlier versions of OBIX should examine
144 this list and consider where modifications may be necessary for compliance with Version 1.1.

Added date, time primitive types and tz Facet to the core object model.

Specific discussion on encodings has been moved to the [OBIX Encodings] document, which includes
XML, EXI, binary, and JSON.

Add support for History Append operation.

Specific discussion on HTTP/REST binding has been moved to the [OBIX REST] document, which
includes HTTP and CoAP. General discussion of REST, as a guiding principle of OBIX, remains.

Add the of attribute to the ref element type and specify usage of this and the is attribute for ref.

Add support for user-specified or referenced metadata for alternate taxonomies, commonly called
tagging.

Add support for alternate history formats.

Add support for concise encoding of long Contract Lists.

Add Delete request semantics.

Add Bindings, Encodings, and Tagspaces sections to the Lobby to better describe how to communicate
with and interpret data from an OBIX Server.

145 Table 1-4. Changes from Version 1.0.

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 13 of 79
146 2 Quick Start [non-normative]
147 This chapter is for those eager to jump right into OBIX in all its angle bracket glory. The best way to begin
148 is to take a simple example that anybody is familiar with – the staid thermostat. Let’s assume a very
149 simple thermostat. It has a temperature sensor which reports the current space temperature and it has a
150 setpoint that stores the desired temperature. Let’s assume the thermostat only supports a heating mode,
151 so it has a variable that reports if the furnace should currently be on. Let’s take a look at what the
152 thermostat might look like in OBIX XML:
153 <obj href="http://myhome/thermostat">
154 <real name="spaceTemp" unit="obix:units/fahrenheit" val="67.2"/>
155 <real name="setpoint" unit="obix:units/fahrenheit" val="72.0"/>
156 <bool name="furnaceOn" val="true"/>
157 </obj>
158 The first thing to notice is the Information Model: there are three element types – obj, real, and bool.
159 The root obj element models the entire thermostat. Its href attribute identifies the URI for this OBIX
160 document. The thermostat Object has three child Objects, one for each of the thermostat’s variables. The
161 real Objects store our two floating point values: space temperature and setpoint. The bool Object
162 stores a boolean variable for furnace state. Each sub-element contains a name attribute which defines the
163 role within the parent. Each sub-element also contains a val attribute for the current value. Lastly we see
164 that we have annotated the temperatures with an attribute called unit so we know they are in
165 Fahrenheit, not Celsius (which would be one hot room). The OBIX specification defines several of these
166 annotations which are called Facets.
167 How was this Object obtained? The OBIX specification leverages commonly available networking
168 technologies and concepts for defining Interactions between devices. The thermostat implements an
169 OBIX Server, and an OBIX Client can be used to issue a request for the thermostat’s data, by specifying
170 its uri. This concept is well understood in the world of M2M so OBIX requires no new knowledge to
171 implement.
172 OBIX addresses the need to Normalize information from devices and present it in a standard way. In
173 most cases sensor and actuator variables (called Points) imply more semantics than a simple scalar
174 value. In the example of our thermostat, in addition to the current space temperature, it also reports the
175 setpoint for desired temperature and whether it is trying to command the furnace on. In other cases such
176 as alarms, it is desirable to standardize a complex data structure. OBIX captures these concepts into
177 Contracts. Contracts allow us to tag Objects with normalized semantics and structure.
178 Let’s suppose our thermostat’s sensor is reading a value of -412F? Clearly our thermostat is busted, so
179 it should report a fault condition. Let’s rewrite the XML to include the status Facet and to provide
180 additional semantics using Contracts:
181 <obj href="http://myhome/thermostat/">
182
183 <!-- spaceTemp point -->
184 <real name="spaceTemp" is="obix:Point"
185 val="-412.0" status="fault"
186 unit="obix:units/fahrenheit"/>
187
188 <!-- setpoint point -->
189 <real name="setpoint" is="obix:Point"
190 val="72.0"
191 unit="obix:units/fahrenheit"/>
192
193 <!-- furnaceOn point -->
194 <bool name="furnaceOn" is="obix:Point" val="true"/>
195
196 </obj>
197 Notice that each of our three scalar values are tagged as obix:Points via the is attribute. This is a
198 standard Contract defined by OBIX for representing normalized point information. By implementing these
199 Contracts, Clients immediately know to semantically treat these objects as points.

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 14 of 79
200 Contracts play a pivotal role in OBIX because they provide a Foundation for building new abstractions
201 upon the core object model. Contracts are just normal objects defined using standard OBIX. In fact, the
202 following sections defining the core OBIX object model are expressed using Contracts. One can see how
203 easily this approach allows for definition of the key parts of this model, or any model that builds upon this
204 model.

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 15 of 79
205 3 Architecture
206 3.1 Design Philosophies
207 The OBIX architecture is based on the design philosophies and principles in Table 3-1.

Philosophy Usage/Description
Object Model A concise object model used to define all OBIX information
Encodings Sets of rules for representing the object model in certain common formats

URIs Uniform Resource Identifiers are used to identify information within the object model
[RFC3986]

REST A small set of verbs is used to access objects via their URIs and transfer their state
[REST]

Contracts A template model for expressing new OBIX “types”

Extensibility Providing for consistent extensibility using only these concepts

208 Table 3-1. Design philosophies and principles for OBIX.

209 3.2 Object Model

210 All information in OBIX is represented using a small, fixed set of primitives. The base abstraction for these
211 primitives is called Object. An Object can be assigned a URI and all Objects can contain other Objects.

212 3.3 Encodings

213 OBIX provides simple syntax rules able to represent the underlying object model. XML is a widely used
214 language with well-defined and well-understood syntax that maps nicely to the OBIX object model. The
215 rest of this specification will use XML as the example encoding, because it is easily human-readable, and
216 serves to clearly demonstrate the concepts presented. The syntax used is normative. Implementations
217 using an XML encoding MUST conform to this syntax and representation of elements.
218 When encoding OBIX objects in XML, each of the object types map to one type of element. The Value
219 Objects represent their data value using the val attribute (see Section 4.3.1 for a full description of Value
220 Objects). All other aggregation is simply nesting of elements. A simple example to illustrate this concept is
221 the Brady family from the TV show The Brady Bunch:
222 <obj href="http://bradybunch/people/Mike-Brady/">
223 <obj name="fullName">
224 <str name="first" val="Mike"/>
225 <str name="last" val="Brady"/>
226 </obj>
227 <int name ="age" val="45"/>
228 <ref name="spouse" href="/people/Carol-Brady"/>
229 <list name="children">
230 <ref href="/people/Greg-Brady"/>
231 <ref href="/people/Peter-Brady"/>
232 <ref href="/people/Bobby-Brady"/>
233 <ref href="/people/Marsha-Brady"/>
234 <ref href="/people/Jan-Brady"/>
235 <ref href="/people/Cindy-Brady"/>
236 </list>
237 </obj>
238 Note in this simple example how the href attribute specifies URI references [RFC3986] which may be
239 used to fetch more information about the object. Names and hrefs are discussed in detail in Section 6.

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 16 of 79
240 3.4 URIs
241 OBIX identifies objects (resources) with Uniform Resource Indicators (URIs) as defined in [RFC3986].
242 This is a logical choice, as a primary focus of OBIX is making information available over the web. Naming
243 authorities manage the uniqueness of the first component of a URI, the domain name.
244
245 Conforming implementations MUST use [RFC3986] URIs to identify resources. Conforming
246 implementations MAY restrict URI schemes and MUST indicate any restrictions in their conformance
247 statement.
248
249 Typically, http scheme URIs are used, but other bindings may require other schemes. Note that while
250 https is technically a different scheme from http [RFC2818], [RFC5785] they are typically used
251 interchangeably with differing security transport. The commonly used term URL is shorthand for what is
252 now an http scheme URI.

253 3.5 REST

254 Objects identified with URIs and passed around as XML documents may sound a lot like [REST] – and
255 this is intentional. REST stands for REpresentational State Transfer and is an architectural style for web
256 services that mimics how the World Wide Web works. The World Wide Web is in essence a distributed
257 collection of documents hyperlinked together using URIs. Similarly, OBIX presents controls and sensors
258 as a collection of documents hyperlinked together using URIs. Because REST is such a key concept in
259 OBIX, it is not surprising that a REST binding is a core part of the specification. The specification of this
260 binding is defined in the [OBIX REST] specification.
261 REST is really more of a design style, than a specification. REST is resource centric as opposed to
262 method centric - resources being OBIX objects. The methods actually used tend to be a very small fixed
263 set of verbs used to work generically with all resources. In OBIX all network requests boil down to four
264 request types:
265  Read: an object
266  Write: an object
267  Invoke: an operation
268  Delete: an object

269 3.6 Contracts

270 In every software domain, patterns start to emerge where many different object instances share common
271 characteristics. For example in most systems that model people, each person has a name, address, and
272 phone number. In vertical domains domain specific information may be attached to each person. For
273 example an access control system might associate a badge number with each person.
274 In object oriented systems these patterns are captured into classes. In relational databases they are
275 mapped into tables with typed columns. In OBIX these patterns are modeled using a concept called
276 Contracts, which are standard OBIX objects used as a template. Contracts provide greater flexibility than
277 a strongly typed schema language, without the overhead of introducing new syntax. A Contract Definition
278 defines the syntactical requirements of the Contract, and is just an OBIX document parsed just like any
279 other OBIX document. OBIX Objects reference Contracts in groups called Contract Lists. In formal terms,
280 Contracts are a combination of prototype based inheritance and mixins. Contracts and their usage are
281 discussed in detail in Section 7.
282 OBIX Contracts describe abstract patterns for interaction with remote systems. Contracts use the
283 grammar of OBIX to create semantics for these interactions. Standard Contracts normalize these
284 semantics for common use by many systems. Contracts are used in OBIX in the same way as class
285 definitions are for objects, or as tables and relations are for databases.
286
287 The OBIX specification defines a minimal set of base Contracts, which are described in Section 11.
288 Various vendors and groups have defined additional common Contracts, the discussion of which is out of
289 scope for this specification. Sets of these Contracts may be available as standard libraries. Implementers
obix-v1.1-cs01 14 September 2015
Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 17 of 79
290 of systems using OBIX are advised to research whether these libraries are available, and if so, to use
291 them to reduce work and expand interoperation.

292 3.7 Extensibility

293 OBIX provides a foundation for developing new abstractions (Contracts) in vertical domains. OBIX is also
294 extensible to support both legacy systems and new products. It is common for even standard building
295 control systems to ship as a blank slate, to be completely programmed in the field. Control systems
296 include, and will continue to include, a mix of standards based, vendor-based, and even project-based
297 extensions.
298 The principle behind OBIX extensibility is that anything new is defined strictly in terms of Objects, URIs,
299 and Contracts. To put it another way - new abstractions do not introduce any new XML syntax or
300 functionality that client code is forced to care about. New abstractions are always modeled as standard
301 trees of OBIX objects, just with different semantics. That does not mean that higher level application code
302 never changes to deal with new abstractions. But the core stack that deals with networking and parsing
303 should not have to change to accommodate a new type.
304 This extensibility model is similar to most mainstream programming languages such as Java or C#. The
305 syntax of the core language is fixed with a built in mechanism to define new abstractions. Extensibility is
306 achieved by defining new class libraries using the language’s fixed syntax. This means the compiler need
307 not be updated every time someone adds a new class.

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 18 of 79
308 4 Object Model
309 4.1 Object Model Description
310 The OBIX object model is summarized in Figure 4-1. OBIX specifies a small, fixed set of object types.
311 OBIX types are a categorization of different objects, analogous to the complexType definition in [XML
312 Schema] or to a [UML] class. The OBIX object model consists of a common base Object (obix:obj)
313 type, and derived types. It lists the default values and attributes for each type, including their optionality.
314 These optional attributes are included as well in the Schema definition for each type. Section 4.2
315 describes the associated properties called Facets that certain OBIX types may have. Section 4.3
316 describes each of the core OBIX types, including the rules for their usage and interpretation. Additional
317 rules defining complex behaviors such as naming and Contract inheritance are described in Sections 6
318 and 7. These sections are essential to a full understanding of the object model.
319 Diagram Notes: All types are as defined in [XML Schema]. obix:Nil is the empty Contract List included in
320 stdlib.obix (see section 11.1)

321
322 Figure 4-1. The OBIX primitive object hierarchy.

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 19 of 79
323 4.2 obj
324 The root abstraction in OBIX is Obj. The name Obj is shortened from Object for brevity in encoding, but
325 for more convenient reference, this specification uses the term Object synonymously with Obj. Every
326 Object type in OBIX is a derivative of Object. Any Object or its derivatives can contain other Objects.
327 As stated in Section 3.3, the expression of Objects in an XML encoding is through XML elements.
328 Although the examples in this section are expressed in XML, the same concepts can be encoded in any
329 of the specified OBIX encodings. The OBIX Object type is expressed through the obj element. The
330 properties of an Object are expressed through XML attributes of the element. The full set of rules for
331 encoding OBIX in XML is contained in the [OBIX Encodings] document. The term obj as used in this
332 specification represents an OBIX Object in general, regardless of how it is encoded.
333 The Contract Definition of Object is expressed by an obj element as
334 <obj href="obix:obj" null="false" writable="false" status="ok" />
335 The interpretation of this definition is described as follows. The Contract Definition provides the
336 attributes, including Contract implementations and Schema references, that exist in the Object by default,
337 and which are inherited by any Object (and thus derived type) that extends this type. Optional attributes
338 that do not exist by default, such as displayName, are not included in the Contract Definition. The href
339 is the URI by which this Contract can be referenced (see Section 4.2.2), so another Object can reference
340 this Contract in its is attribute (see Section 4.2.3). The null attribute is specified as false, meaning that
341 by default this Object "has a value" (see Section 4.2.4). The writable attribute indicates this Object is
342 readonly, so any Object type extending from obj (which is all Objects) will be readonly unless it explicitly
343 overrides the writable attribute. The status of the Object defaults to 'ok' unless overridden. The
344 properties supported on Object, and therefore on any derivative type, are described in the following
345 sections.

346 4.2.1 name

347 All Objects MAY have the name attribute. This defines the Object’s purpose in its parent Object. Names
348 of Objects SHOULD be in Camel case per [CamelCase]. Additional considerations with respect to Object
349 naming are discussed in Section 6.

350 4.2.2 href

351 All Objects MAY have the href attribute. This provides a URI reference for identifying the Object. Href is
352 closely related to name, and is also discussed in Section 6.

353 4.2.3 is
354 All Objects MAY have the is attribute. This attribute defines all of the Contracts this Object implements.
355 The value of this attribute MUST be a Contract List. In addition, all Objects derive from the obj type, so
356 is MUST NOT ever be equal to the OBIX Nil Contract, defined in Section 11.1 to represent an empty
357 Contract List. Contracts are discussed in general in Section 7, and Contract Lists are discussed in
358 Section 7.2.

359 4.2.4 null

360 All Objects support the null attribute. Null is the absence of a value, meaning that this Object has no
361 value, has not been configured or initialized, or is otherwise not defined. Null is indicated using the null
362 attribute with a boolean value. The default value of the null attribute is true for enum, abstime, date,
363 and time, and false for all other Objects. An example of the null attribute used in an abstime Object
364 is:
365 <abstime name="startTime" displayName="Start Time"/>
366 Null is inherited from Contracts a little differently than other attributes. See Section 7.4.3 for details.

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 20 of 79
367 4.2.5 val
368 Certain Objects represent a value and are called Value-type Objects. These Objects MAY have the val
369 attribute. The Objects NEED NOT explicitly state the val attribute, as all Value-type objects define a
370 default value for the attribute. The Object types that are Value-type Objects, and are allowed to contain a
371 val attribute, are bool, int, real, str, enum, abstime, reltime, date, time, and uri. The literal
372 representation of the values maps to [XML Schema], indicated in the following sections with the ‘xs:’
373 prefix.

374 4.2.6 ts
375 Certain Objects may be used as a Tag to provide metadata about their parent Object. Tags and their
376 usage are discussed in Section 9.4. Tags are often grouped together into a Tag Space and published for
377 use by others. Use of Tag Spaces is discussed in Section 5.5.1. If an Object is a Tag, then it MUST use
378 the Tag name in its name attribute, and include the Tag Space which defines the Tag in the ts attribute.
379 For example, if a Tag Space named “foo” declares a Tag named “bar”, then an Object that has this Tag
380 would be encoded as follows:
381 <obj name="taggedObject">
382 <obj name="bar" ts="foo"/>
383 </obj>

384 4.2.7 Facets

385 All Objects can be annotated with a predefined set of attributes called Facets. Facets provide additional
386 meta-data about the Object. The set of available Facets is: displayName, display, icon, min, max,
387 precision, range, status, tz, unit, writable, of, in, and out. Although OBIX predefines a
388 number of Facets, vendors MAY add additional Facets. Vendors that wish to annotate Objects with
389 additional Facets SHOULD use XML namespace qualified attributes.

390 4.2.7.1 displayName

391 The displayName Facet provides a localized human readable name of the Object stored as an
392 xs:string:
393 <obj name="spaceTemp" displayName="Space Temperature"/>
394 Typically the displayName Facet SHOULD be a localized form of the name attribute. There are no
395 restrictions on displayName overrides from the Contract (although it SHOULD be uncommon since
396 displayName is just a human friendly version of name).

397 4.2.7.2 display

398 The display Facet provides a localized human readable description of the Object stored as an
399 xs:string:
400 <bool name="occupied" val="false" display="Unoccupied"/>
401 There are no restrictions on display overrides from the Contract.
402 The display attribute serves the same purpose as Object.toString() in Java or C#. It provides a general
403 way to specify a string representation for all Objects. In the case of value Objects (like bool or int) it
404 SHOULD provide a localized, formatted representation of the val attribute.

405 4.2.7.3 icon

406 The icon Facet provides a URI reference to a graphical icon which may be used to represent the Object
407 in an user agent:
408 <obj icon="/icons/equipment.png"/>

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 21 of 79
409 The contents of the icon attribute MUST be a URI to an image file. The image file SHOULD be a 16x16
410 PNG file, defined in the [PNG] specification. There are no restrictions on icon overrides from the
411 Contract.

412 4.2.7.4 min

413 The min Facet is used to define an inclusive minimum value:
414 <int min="5" val="6"/>
415 The contents of the min attribute MUST match its associated val type. The min Facet is used with int,
416 real , abstime, date, time, and reltime to define an inclusive lower limit of the value space. It is
417 used with str to indicate the minimum number of Unicode characters of the string. It is used with list to
418 indicate the minimum number of child Objects (named or unnamed). Overrides of the min Facet may only
419 narrow the value space using a larger value. The min Facet MUST never be greater than the max Facet
420 (although they MAY be equal).

421 4.2.7.5 max

422 The max Facet is used to define an inclusive maximum value:
423 <real max="70" val="65"/>
424 The contents of the max attribute MUST match its associated val type. The max Facet is used with int,
425 real, abstime, date, time, and reltime to define an inclusive upper limit of the value space. It is
426 used with str to indicate the maximum number of Unicode characters of the string. It is used with list
427 to indicate the maximum number of child Objects (named or unnamed). Overrides of the max Facet may
428 only narrow the value space using a smaller value. The max Facet MUST never be less than the min
429 Facet (although they MAY be equal).

430 4.2.7.6 precision

431 The precision Facet is used to describe the number of decimal places to use for a real value:
432 <real precision="2" val="75.04"/>
433 The contents of the precision attribute MUST be xs:int. The value of the precision attribute
434 equates to the number of meaningful decimal places. In the example above, the value of 2 indicates two
435 meaningful decimal places: “75.04”. Typically precision is used by client applications which do their own
436 formatting of real values. There are no restrictions on precision overrides.

437 4.2.7.7 range

438 The range Facet is used to define the value space of an enumeration. A range attribute is a URI
439 reference to an obix:Range Object (see Section 11.2). It is used with the bool and enum types:
440 <enum range="/enums/offSlowFast" val="slow"/>
441 The override rule for range is that the specified range MUST inherit from the Contract’s range.
442 Enumerations are unusual in that specialization of an enum usually involves adding new items to the
443 range. Technically this is widening the enum’s value space, rather than narrowing it. But in practice,
444 adding items into the range is the desired behavior.

445 4.2.7.8 status

446 The status Facet is used to annotate an Object about the quality and state of the information:
447 <real val="67.2" status="alarm"/>
448 Status is an enumerated string value with one of the following values from Table 4-2 (in ascending
449 priority):
Status Description

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 22 of 79
 ok The ok state indicates normal status. This is the assumed default state for all Objects.
overridden The overridden state means the data is ok, but that a local override is currently in
effect. An example of an override might be the temporary override of a setpoint from
its normal scheduled setpoint.
unacked The unacked state is used to indicate a past alarm condition which remains
unacknowledged.
alarm This state indicates the Object is currently in the alarm state. The alarm state typically
means that an Object is operating outside of its normal boundaries. In the case of an
analog point this might mean that the current value is either above or below its
configured limits. Or it might mean that a digital sensor has transitioned to an
undesired state. See Alarming (Section 15) for additional information.
unackedAlarm The unackedAlarm state indicates there is an existing alarm condition which has
not been acknowledged by a user – it is the combination of the alarm and unacked
states. The difference between alarm and unackedAlarm is that alarm implies that
a user has already acknowledged the alarm or that no human acknowledgement is
necessary for the alarm condition. The difference between unackedAlarm and
unacked is that the Object has returned to a normal state.
down The down state indicates a communication failure.
fault The fault state indicates that the data is invalid or unavailable due to a failure
condition - data which is out of date, configuration problems, software failures, or
hardware failures. Failures involving communications SHOULD use the down state.
disabled This state indicates that the Object has been disabled from normal operation (out of
service). In the case of operations and Feeds, this state is used to disable support for
the operation or Feed.

450 Table 4-1. Status enumerations in OBIX.

451 Status MUST be one of the enumerated strings above. It might be possible in the native system to exhibit
452 multiple status states simultaneously, however when mapping to OBIX the highest priority status
453 SHOULD be chosen – priorities are ranked from top (disabled) to bottom (ok).

454 4.2.7.9 tz
455 The tz Facet is used to annotate an abstime, date, or time Object with a timezone. The value of a tz
456 attribute is a zoneinfo string identifier, as specified in the IANA Time Zone ([ZoneInfo DB]) database. The
457 zoneinfo database defines the current and historical rules for each zone including its offset from UTC and
458 the rules for calculating daylight saving time. OBIX does not define a Contract for modeling timezones,
459 instead it just references the zoneinfo database using standard identifiers. It is up to OBIX enabled
460 software to map zoneinfo identifiers to the UTC offset and daylight saving time rules.
461 The following rules are used to compute the timezone of an abstime, date, or time Object:
462 1. If the tz attribute is specified, set the timezone to tz;
463 2. Otherwise, if the Contract defines an inherited tz attribute, set the timezone to the inherited tz
464 attribute;
465 3. Otherwise, set the timezone to the Server’s timezone as defined by the lobby’s About.tz.
466 When using timezones, an implementation MUST specify the timezone offset within the value
467 representation of an abstime or time Object. It is an error condition for the tz Facet to conflict with the
468 timezone offset. For example, New York has a -5 hour offset from UTC during standard time and a -4
469 hour offset during daylight saving time:
470 <abstime val="2007-12-25T12:00:00-05:00" tz="America/New_York"/>

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 23 of 79
471 <abstime val="2007-07-04T12:00:00-04:00" tz="America/New_York"/>

472 4.2.7.10 unit

473 The unit Facet defines a unit of measurement in the [SI Units] system. A unit attribute is a URI
474 reference to an obix:Unit Object (see section 11.5 for the Contract definition). It is used with the int
475 and real types:
476 <real unit="obix:units/fahrenheit" val="67.2"/>
477 It is recommended that the unit Facet not be overridden if declared in a Contract. If it is overridden, then
478 the override SHOULD use a Unit Object with the same dimensions as the Contract (it must measure the
479 same physical quantity).

480 4.2.7.11 writable

481 The writable Facet specifies if this Object can be written by the Client. If false (the default), then the
482 Object is read-only. It is used with all types except op and feed:
483 <str name="userName" val="jsmith" writable="false"/>
484 <str name="fullName" val="John Smith" writable="true"/>
485 The writable Facet describes only the ability of Clients to modify this Object’s value, not the ability of
486 Clients to add or remove children of this Object. Servers MAY allow addition or removal of child Objects
487 independently of the writability of existing objects. If a Server does not support addition or removal of
488 Object children through writes, it MUST return an appropriate error response (see Section 10.2 for
489 details).

490 4.2.7.12 of
491 The of Facet specifies the type of child Objects contained by this Object. The value of this attribute
492 MUST be a Contract List, which is described in detail in Section 7.2. All Objects in the list MUST
493 implement all of the Contracts in the Contract List, as Clients will expect that Objects retrieved from the
494 list will provide the syntactic and semantic behaviors of each of the Contracts in the Contract List. This
495 Facet is used with list and ref types, as explained in Sections 4.3.2 and 4.3.3, respectively.

496 4.2.7.13 in
497 The in Facet specifies the input argument type used by this Object. The value of this attribute MUST be
498 a Contract List, which is described in detail in Section 7.2. The Object provided to the Server by the
499 Client using the input argument MUST implement all of the Contracts in the Contract List defined in the
500 in Facet. As a result, the Server MAY depend upon the syntactic and semantic behaviors described by
501 each of the Contracts in the Contract List. This Facet is used with op and feed types. Its use is
502 described with the definition of those types in Section 4.3.5 for op and 4.3.6 for feed.

503 4.2.7.14 out

504 The out Facet specifies the output argument type used by this Object. The value of this attribute MUST
505 be a Contract List, which is described in detail in Section 7.2. The Object returned to the Client by the
506 Server as the result of executing the operation MUST implement all of the Contracts in the Contract List.
507 As a result, the Client MAY depend upon the syntactic and semantic behaviors described by each of the
508 Contracts in the Contract List. This Facet is used with the op type. Its use is described with the definition
509 of that type in Section 4.3.5.

510 4.3 Core Types

511 OBIX defines a handful of core types which derive from Object.

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 24 of 79
512 4.3.1 val
513 Certain types are allowed to have a val attribute and are called “value” types. The val type is not
514 directly used (it is “abstract”). It simply reflects that instances of the type may contain a val attribute, as
515 it is used to represent an object that has a specific value. In object-oriented terms, the base OBIX val
516 type is an abstract class, and its subtypes are concrete classes that inherit from that abstract class. The
517 different Value Object types defined for OBIX are listed in Table 4-3.
Type Name Usage

bool stores a boolean value – true or false

int stores an integer value

real stores a floating point value

str stores a UNICODE string

enum stores an enumerated value within a fixed range

abstime stores an absolute time value (timestamp)

reltime stores a relative time value (duration or time span)

date stores a specific date as day, month, and year

time stores a time of day as hour, minutes, and seconds

uri stores a Universal Resource Identifier

518 Table 4-2. Value Object types.

519 Note that any Value typed Object can also contain sub-Objects.

520 4.3.1.1 bool

521 The bool type represents a boolean condition of either true or false. Its val attribute maps to
522 xs:boolean defaulting to false. The literal value of a bool MUST be “true” or “false” (the literals “1” and
523 “0” are not allowed). The Contract definition is:
524 <bool href="obix:bool" is="obix:obj" val="false" null="false"/>
525 This defines an Object that can be referenced via the URI obix:bool, which extends the obix:obj type.
526 Its default value is false, and its null attribute is false by default. The optional attribute range is not
527 present in the Contract definition, which means that there is no standard range of values attached to an
528 obix:bool by default.
529 Here is an example of an obix:bool which defines its range:
530 <bool val="true" range="#myRange">
531 <list href="#myRange" is="obix:Range">
532 <obj name="false" displayName="Inactive"/>
533 <obj name="true" displayName="Active"/>
534 </list>
535 </bool>
536 The range attribute specifies a local fragment reference to its myRange child, where the intended display
537 names for the false and true states are listed.

538 4.3.1.2 int

539 The int type represents an integer number. Its val attribute maps to xs:long as a 64-bit integer with a
540 default of 0. The Contract definition is:
541 <int href="obix:int" is="obix:obj" val="0" null="false"/>

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 25 of 79
542 This defines an Object that can be referenced via the URI obix:int, which extends the obix:obj type. Its
543 default value is 0, and its null attribute is false by default. The optional attributes min, max, and unit
544 are not present in the Contract definition, which means that no minimum, maximum, or units are attached
545 to an obix:int by default.
546 An example:
547 <int val="52" min="0 max="100"/>
548 This example shows an obix:int with a value of 52. The int may take on values between a minimum of 0
549 and a maximum of 100. No units are attached to this value.

550 4.3.1.3 real

551 The real type represents a floating point number. Its val attribute maps to xs:double as an IEEE
552 64-bit floating point number with a default of 0. The Contract definition is:
553 <real href="obix:real" is="obix:obj" val="0" null="false"/>
554 This defines an Object that can be referenced via the URI obix:real, which extends the obix:obj type.
555 Its default value is 0, and its null attribute is false by default. The optional attributes min, max, and
556 unit are not present in the Contract definition, which means that no minimum, maximum, or units are
557 attached to an obix:real by default.
558 An example:
559 <real val="31.06" name="spcTemp" displayName="Space Temp" unit="obix:units/celsius"/>
560 This example has provided a value for the name and displayName attributes, and has specified units to
561 be attached to the value through the unit attribute.

562 4.3.1.4 str

563 The str type represents a string of Unicode characters. Its val attribute maps to xs:string with a
564 default of the empty string. The Contract definition is:
565 <str href="obix:str" is="obix:obj" val="" null="false"/>
566 This defines an Object that can be referenced via the URI obix:str, which extends the obix:obj type. Its
567 default value is an empty string, and its null attribute is false by default. The optional attributes min and
568 max are not present in the Contract definition, which means that no minimum or maximum are attached to
569 an obix:str by default. The min and max attributes are constraints on the character length of the
570 string, not the 'value' of the string.
571 An example:
572 <str val="hello world"/>

573 4.3.1.5 enum

574 The enum type is used to represent a value which must match a finite set of values. The finite value set is
575 called the range. The val attribute of an enum is represented as a string key using xs:string. Enums
576 default to null. The range of an enum is declared via Facets using the range attribute. The Contract
577 definition is:
578 <enum href="obix:enum" is="obix:obj" val="" null="true"/>
579 This definition overrides the value of the null attribute so that by default, an obix:enum has a null
580 value. The val attribute by default is assigned an empty string, although this value is not used directly.
581 The inheritance of the null attribute is described in detail in Section 7.4.3.
582 An example:
583 <enum range="/enums/offSlowFast" val="slow"/>
584 In this example, the val attribute is specified, so the null attribute is implied to be false. See Section
585 7.4.3 for details on the inheritance of the null attribute. The range is also specified with a URI. A

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 26 of 79
586 consumer of this Object would be able to get the resource at that location to determine the list of tags that
587 are associated with this enum.

588 4.3.1.6 abstime

589 The abstime type is used to represent an absolute point in time. Its val attribute maps to
590 xs:dateTime, with the exception that it MUST contain the timezone. According to [XML Schema] Part 2
591 section 3.2.7.1, the lexical space for abstime is:
592 '-'? yyyy '-' mm '-' dd 'T' hh ':' mm ':' ss ('.' s+)? (zzzzzz)
593 Abstimes default to null. The Contract definition is:
594 <abstime href="obix:abstime" is="obix:obj" val="1970-01-01T00:00:00Z" null="true"/>
595 The Contract Definition for obix:abstime also overrides the null attribute to be true. The default value
596 of the val attribute is thus not important.
597 An example for 9 March 2005 at 1:30PM GMT:
598 <abstime val="2005-03-09T13:30:00Z"/>
599 In this example, the val attribute is specified, so the null attribute is implied to be false. See Section
600 7.4.3 for details on the inheritance of the null attribute.
601 The timezone offset is REQUIRED, so the abstime can be used to uniquely relate the abstime to UTC.
602 The optional tz Facet is used to specify the timezone as a zoneinfo identifier. This provides additional
603 context about the timezone, if available. The timezone offset of the val attribute MUST match the offset
604 for the timezone specified by the tz Facet, if it is also used. See the tz Facet section for more
605 information.

606 4.3.1.7 reltime

607 The reltime type is used to represent a relative duration of time. Its val attribute maps to
608 xs:duration with a default of 0 seconds. The Contract definition is:
609 <reltime href="obix:reltime" is="obix:obj" val="PT0S" null="false"/>
610 The Contract Definition for obix:reltime sets the default values of the val and null attributes. In
611 contrast to obix:abstime, here the null attribute is specified to be false. The default value is 0
612 seconds, expressed according to [XML Schema] as "PT0S".
613 An example of a reltime which is constrained to be between 0 and 60 seconds, with a current value of 15
614 seconds:
615 <reltime val="PT15S" min="PT0S" max="PT60S"/>

616 4.3.1.8 date

617 The date type is used to represent a day in time as a day, month, and year. Its val attribute maps to
618 xs:date. According to XML Schema Part 2 section 3.2.9.1, the lexical space for date is:
619 '-'? yyyy '-' mm '-' dd
620 Date values in OBIX MUST omit the timezone offset and MUST NOT use the trailing “Z”. Only the tz
621 attribute SHOULD be used to associate the date with a timezone. Date Objects default to null. The
622 Contract definition is described here and is interpreted in similar fashion to obix:abstime.
623 <date href="obix:date" is="obix:obj" val="1970-01-01" null="true"/>
624 An example for 26 November 2007:
625 <date val="2007-11-26"/>
626 In this example, the val attribute is specified, so the null attribute is implied to be false. See Section
627 7.4.3 for details on the inheritance of the null attribute.
628 The tz Facet is used to specify the timezone as a zoneinfo identifier. See the tz Facet section for more
629 information.

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 27 of 79
630 4.3.1.9 time
631 The time type is used to represent a time of day in hours, minutes, and seconds. Its val attribute maps
632 to xs:time. According to [XML Schema] Part 2 section 3.2.8, the lexical space for time is the left
633 truncated representation of xs:dateTime:
634 hh ':' mm ':' ss ('.' s+)?
635 Time values in OBIX MUST omit the timezone offset and MUST NOT use the trailing “Z”. Only the tz
636 attribute SHOULD be used to associate the time with a timezone. Time Objects default to null. The
637 Contract definition is:
638 <time href="obix:time" is="obix:obj" val="00:00:00" null="true"/>
639 An example representing a wake time, which (in this example at least) must be between 7 and 10AM:
640 <time val="08:15:00" min="07:00:00" max="10:00:00"/>
641 In this example, the val attribute is specified, so the null attribute is implied to be false. See Section
642 7.4.3 for details on the inheritance of the null attribute.
643 The tz Facet is used to specify the timezone as a zoneinfo identifier. See the tz Facet section for more
644 information.

645 4.3.1.10 uri

646 The uri type is used to store a URI reference. Unlike a plain old str, a uri has a restricted lexical
647 space as defined by [RFC3986] and the XML Schema xs:anyURI type. OBIX Servers MUST use the
648 URI syntax described by [RFC3986] for identifying resources. OBIX Clients MUST be able to navigate
649 this URI syntax. Most URIs will also be a URL, meaning that they identify a resource and how to retrieve
650 it (typically via HTTP). The Contract definition is:
651 <uri href="obix:uri" is="obix:obj" val="" null="false"/>
652 An example for the OBIX home page:
653 <uri val="http://obix.org/" />

654 4.3.2 list

655 The list type is a specialized Object type for storing a list of other Objects. The primary advantage of
656 using a list versus a generic obj is that lists can specify a common Contract for their contents using
657 the of attribute. If specified, the of attribute MUST be a list of URIs formatted as a Contract List. The
658 definition of list is:
659 <list href="obix:list" is="obix:obj" of="obix:obj"/>
660 This definition states that the obix:list type contains elements that are themselves OBIX Objects,
661 because the of attribute value is obix:obj. Instances of the obix:list type can provide a different
662 value for of to indicate the type of Objects they contain.
663 An example list of strings:
664 <list of="obix:str">
665 <str val="one"/>
666 <str val="two"/>
667 </list>
668 Because lists typically have constraints on the URIs used for their child elements, they use special
669 semantics for adding children. Lists are discussed in greater detail along with Contracts in section 7.8.

670 4.3.3 ref

671 The ref type is used to create an external reference to another OBIX Object. It is the OBIX equivalent of
672 the HTML anchor tag. The Contract definition is:
673 <ref href="obix:ref " is="obix:obj"/>
674 A ref element MUST always specify an href attribute. A ref element SHOULD specify the type of the
675 referenced object using the is attribute. A ref element referencing a list (is=”obix:list”)
obix-v1.1-cs01 14 September 2015
Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 28 of 79
676 SHOULD specify the type of the Objects contained in the list using the of attribute. References are
677 discussed in detail in section 9.2.

678 4.3.4 err

679 The err type is a special Object used to indicate an error. Its actual semantics are context dependent.
680 Typically err Objects SHOULD include a human readable description of the problem via the display
681 attribute. The Contract definition is:
682 <err href="obix:err" is="obix:obj"/>

683 4.3.5 op
684 The op type is used to define an operation. All operations take one input Object as a parameter, and
685 return one Object as an output. The input and output Contracts are defined via the in and out attributes.
686 The Contract definition is:
687 <op href="obix:op" is="obix:obj" in="obix:Nil" out="obix:Nil"/>
688 Operations are discussed in detail in Section 8.

689 4.3.6 feed

690 The feed type is used to define a topic for a Feed of events. Feeds are used with Watches to subscribe
691 to a stream of events such as alarms. A Feed SHOULD specify the event type it fires via the of attribute.
692 The in attribute can be used to pass an input argument when subscribing to the Feed (a filter for
693 example).
694 <feed href="obix:feed" is="obix:obj" in="obix:Nil" of="obix:obj"/>
695 Feeds are subscribed via Watches. This is discussed in Section 12.

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 29 of 79
696 5 Lobby
697 5.1 Lobby Object
698 All OBIX Servers MUST contain an Object which implements obix:Lobby. The Lobby Object serves as
699 the central entry point into an OBIX Server, and lists the URIs for other well-known Objects defined by the
700 OBIX Specification. Theoretically all a Client needs to know to bootstrap discovery is one URI for the
701 Lobby instance. By convention this URI is “http://<server-ip-address>/obix”, although vendors are
702 certainly free to pick another URI. The Lobby Contract is:
703 <obj href="obix:Lobby">
704 <ref name="about" is="obix:About"/>
705 <op name="batch" in="obix:BatchIn" out="obix:BatchOut"/>
706 <ref name="watchService" is="obix:WatchService"/>
707 <list name="tagspaces" of="obix:uri" null="true"/>
708 <list name="encodings" of="obix:str" null="true"/>
709 <list name="bindings" of="obix:uri" null="true"/>
710 </obj>
711 The following rules apply to the Lobby object:

712 1. The Lobby MUST provide a ref to an Object which implements the obix:About Contract as
713 described in Section 5.1.
714 2. The Lobby MUST provide an op to invoke batch operations using the obix:BatchIn and
715 obix:BatchOut Contracts as described in Section 5.2.
716 3. The Lobby MUST provide a ref to an Object which implements the obix:WatchService
717 Contract as described in Section 5.3.
718 4. The Lobby MUST provide a list of the tag spaces referenced as described in Section in 5.5.1.
719 5. The Lobby MUST provide a list of the encodings supported as described in Section 5.5.3.
720 6. The Lobby MUST provide a list of the bindings supported as described in Section 5.5.4.

721 The Lobby instance is where implementers SHOULD place vendor-specific Objects used for data and
722 service discovery. The standard Objects defined in the Lobby Contract are described in the following
723 Sections.
724 Because the Lobby Object is the primary entry point into an OBIX Server, it also serves as the primary
725 attack point for malicious entities. With that in mind, it is important that implementers of OBIX Servers
726 consider carefully how to address security concerns. Servers SHOULD ensure that Clients are properly
727 authenticated and authorized before providing any information or performing any requested actions.
728 Even providing Lobby information can significantly increase the attack surface of an OBIX Server. For
729 instance, malicious Clients could make use of the Batch Service to issue further requests, or could
730 reference items from the About section to search the web for any reported vulnerabilities associated with
731 the Server’s vendor.

732 5.2 About

733 The obix:About Object is a standardized list of summary information about an OBIX Server. Clients can
734 discover the About URI directly from the Lobby. The About Contract is:
735 <obj href="obix:About">
736
737 <str name="obixVersion"/>
738
739 <str name="serverName"/>
740 <abstime name="serverTime"/>
741 <abstime name="serverBootTime"/>
742
743 <str name="vendorName"/>
744 <uri name="vendorUrl"/>

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 30 of 79
745
746 <str name="productName"/>
747 <str name="productVersion"/>
748 <uri name="productUrl"/>
749
750 <str name="tz"/>
751 </obj>
752
753 The following children provide information about the OBIX implementation:
754  obixVersion: specifies which version of the OBIX specification the Server implements. This
755 string MUST be a list of decimal numbers separated by the dot character (Unicode 0x2E). The
756 current version string is “1.1”.
757 The following children provide information about the Server itself:
758  serverName: provides a short localized name for the Server.
759  serverTime: provides the Server’s current local time.
760  serverBootTime: provides the Server’s start time - this SHOULD be the start time of the OBIX
761 Server software, not the machine’s boot time.
762 The following children provide information about the Server’s software vendor:
763  vendorName: the company name of the vendor who implemented the OBIX Server software.
764  vendorUrl: a URL to the vendor’s website.
765 The following children provide information about the software product running the Server:
766  productName: with the product name of OBIX Server software.
767  productUrl: a URL to the product’s website.
768  productVersion: a string with the product’s version number. Convention is to use decimal
769 digits separated by dots.
770 The following children provide additional miscellaneous information:
771  tz: specifies a zoneinfo identifier for the Server’s default timezone.

772 5.3 Batch

773 The Lobby defines a batch operation which allows Clients to group multiple OBIX requests together into
774 a single operation. Grouping multiple requests together can often provide significant performance
775 improvements over individual round-robin network requests. As a general rule, one big request will
776 always out-perform many small requests over a network.
777 A batch request is an aggregation of read, write, and invoke requests implemented as a standard OBIX
778 operation. At the protocol binding layer, it is represented as a single invoke request using the
779 Lobby.batch URI. Batching a set of requests to a Server MUST be processed semantically equivalent
780 to invoking each of the requests individually in a linear sequence.
781 The batch operation inputs a BatchIn Object and outputs a BatchOut Object:
782 <list href="obix:BatchIn" of="obix:uri"/>
783
784 <list href="obix:BatchOut" of="obix:obj"/>
785 The BatchIn Contract specifies a list of requests to process identified using the Read, Write, or
786 Invoke Contract:
787 <uri href="obix:Read"/>
788
789 <uri href="obix:Write">
790 <obj name="in"/>
791 </uri>
792
793 <uri href="obix:Invoke">
794 <obj name="in"/>

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 31 of 79
795 </uri>
796 The BatchOut Contract specifies an ordered list of the response Objects to each respective request. For
797 example the first Object in BatchOut must be the result of the first request in BatchIn. Failures are
798 represented using the err Object. Every uri passed via BatchIn for a read or write request MUST
799 have a corresponding result obj in BatchOut with an href attribute using an identical string
800 representation from BatchIn (no normalization or case conversion is allowed).
801 It is up to OBIX Servers to decide how to deal with partial failures. In general idempotent requests
802 SHOULD indicate a partial failure using err, and continue processing additional requests in the batch. If
803 a Server decides not to process additional requests when an error is encountered, then it is still
804 REQUIRED to return an err for each respective request not processed.
805 Let’s look at a simple example:
806 <list is="obix:BatchIn">
807 <uri is="obix:Read" val="/someStr"/>
808 <uri is="obix:Read" val="/invalidUri"/>
809 <uri is="obix:Write" val="/someStr">
810 <str name="in" val="new string value"/>
811 </uri>
812 </list>
813
814 <list is="obix:BatchOut">
815 <str href="/someStr" val="old string value"/>
816 <err href="/invalidUri" is="obix:BadUriErr" display="href not found"/>
817 <str href="/someStr" val="new string value">
818 </list>
819 In this example, the batch request is specifying a read request for “/someStr” and “/invalidUri”, followed by
820 a write request to “/someStr”. Note that the write request includes the value to write as a child named “in”.
821 The Server responds to the batch request by specifying exactly one Object for each request URI. The first
822 read request returns a str Object indicating the current value identified by “/someStr”. The second read
823 request contains an invalid URI, so the Server returns an err Object indicating a partial failure and
824 continues to process subsequent requests. The third request is a write to “someStr”. The Server updates
825 the value at “someStr”, and returns the new value. Note that because the requests are processed in
826 order, the first request provides the original value of “someStr” and the third request contains the new
827 value. This is exactly what would be expected had each of the requests been individually processed.

828 5.4 WatchService

829 The WatchService is an important mechanism for providing data from a Server. As such, this
830 specification devotes an entire Section to the description of Watches, and of the WatchService. Section
831 12 covers Watches in detail.

832 5.5 Server Metadata

833 Several components of the Lobby provide additional information about the Server’s implementation of the
834 OBIX specification. This is to be used by Clients to allow them to tailor their interaction with the Server
835 based on mutually interoperable capabilities. The following subsections describe these components.

836 5.5.1 Tag Spaces

837 Any semantic models, such as tag dictionaries, used by the Server for presenting metadata about its
838 Objects, are declared in a Tag Space. This is a collection of names, called Tags, that relate to a
839 particular usage or industry. Tag Spaces used by a Server MUST be identified in the Lobby in the
840 tagspaces element, which is a list of uris. The name of each uri MUST be the name that is
841 referenced by the Server when presenting Tags. A more descriptive name MAY be provided in the
842 displayName Facet. The val of the uri MUST contain the reference location for this model or
843 dictionary. In order to prevent conflicts when the source of the referenced Tag Space is updated, the
844 Server MUST provide version information, if it is available, for the Tag Space in the uri element. Version
845 information MUST be expressed as a child str element with the name “version”. If the Tag Space

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 32 of 79
846 publication source does not provide version information, then the Server MUST provide the time of
847 retrieval from the publication source of the Tag Space. Retrieval time MUST be expressed as a child
848 abstime element with the name “retrieved”. With this information, a Client can use the appropriate
849 version of the model or dictionary for interpreting the Server metadata. Clients MUST use the version
850 element, if it exists, and retrieved as a fallback, for identifying which revision of the Tag Space to use
851 in interpreting Tags presented by the Server. A Server MAY include the retrieved element in addition
852 to the version element, so a Client MUST NOT use retrieved unless version is not present. For
853 example, a Server that makes use of both an HVAC tag dictionary and a Building Terms tag dictionary
854 might express these models in the following way:
855 <obj is="obix:Lobby">
856 <!-- ... other lobby items ...-->
857 <list name="tagspaces" of="obix:uri">
858 <uri name="hvac" displayName="HVAC Tag Dictionary"
859 val="http://example.com/tags/hvac">
860 <str name="version" val="1.0.42"/>
861 </uri>
862 <uri name="bldg" displayName="Building Terms Dictionary"
863 val="http://example.com/tags/building">
864 <abstime name="retrieved" val="2014-07-01T10:39:00Z"/>
865 </uri>
866 </list>
867 </obj>
868 Namespaces in XML are similar to Tag Spaces, but not identical. Namespaces are required by XML
869 encoding rules, when encoding an Object in XML. A Tag Space, as a simple collection of Tags defined
870 by a Tag dictionary, may not even have an XML expression. Consequently, all Namespaces are
871 essentially Tag Spaces, but not all Tag Spaces are XML Namespaces. XML Namespaces are not
872 required for other encodings like JSON, but an Implementation MAY include them.
873 If a particular tag dictionary provides an XML representation, then it can be used in validating the XML
874 encoded Objects that use that Tag Space. An XML Namespace, such as the OBIX Namespace defined
875 by obix:, is treated just like a Tag Space. Every OBIX Implementation MUST be able to reference and
876 retrieve objects in the OBIX Tag Space, and this space MUST be assumed if the space for a Tag is not
877 included in the Object being decoded by an Implementation. Encoding Implementations MAY include the
878 OBIX Tag Space for Objects referencing it.
879 One caveat to this behavior is that the presentation of the usage of a particular semantic model may
880 divulge unwanted information about the Server. For instance, a Server that makes use of a medical tag
881 dictionary and presents this in the Lobby may be undesirably advertising itself as an interesting target for
882 individuals attempting to access confidential medical records. Therefore, Servers SHOULD protect this
883 section of the Lobby by only including it in communication to authenticated, authorized Clients.

884 5.5.2 Versioning

885 Each of the subsequent subsections describes a set of Objects that describe specifications to which a
886 Server is implemented. These specifications are expected to change over time, and the Server
887 implementation may not be updated at the same pace. Therefore, a Server implementation MAY wish to
888 provide versioning information with the Objects that describes the date on which the specification was
889 retrieved. This information SHOULD be included as a child element of the uri. It SHOULD be included
890 as a str with the name ‘version’, containing the version information, if the source being referenced
891 provides it. If version information is not available, it SHOULD be included as an abstime with the name
892 ‘retrieved’ and the time at which the version used by the Server was retrieved from the source. The
893 following example shows the structure of the Lobby for a sample Server that provides an HTTP Binding
894 using the OBIX REST Binding and a separate non-standard binding. Note that the actual conversation
895 between the Client and Server is subject to the rules governing the marshaling of Objects with respect to
896 their Extents, and may not include this complete structure. See Section 9.3 for a discussion of how
897 Extents are used in OBIX.
898 <obj is="obix:Lobby">
899 {... other lobby items ...}
900 <list name="bindings" of="obix:uri">

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 33 of 79
901 <uri name="http" displayName="HTTP Binding" val="http://docs.oasis-
902 open.org/obix/obix-rest/v1.0/obix-rest-v1.0.pdf">
903 <abstime name="retrieved" val="2013-11-26T3:14:15.926Z"/>
904 </uri>
905 <uri name="myBinding" displayName="My New Binding" val="http://example.com/my-new-
906 binding.doc">
907 <str name="version" val="1.2.34"/>
908 </uri>
909 </list>
910 </obj>

911 5.5.3 Encodings

912 Servers MUST include the encodings supported in the encodings Lobby Object. This is a list of str
913 elements. The val attribute of each str MUST be the MIME type of the encoding. A more friendly
914 name MAY be provided in the displayName attribute. If the encoding is not one of the standard
915 encodings defined in the [OBIX Encodings] document, the specification document SHOULD be included
916 as a child uri of the list element.
917 The discovery of which encoding to use for communication between a Client and a Server is a function of
918 the specific binding used. Both Clients and Servers SHOULD support the XML encoding, as this
919 encoding is used by the majority of OBIX implementations. Clients and Servers MUST be able to support
920 negotiation of the encoding to be used according to the binding’s error message rules. Clients SHOULD
921 first attempt to request communication using the desired encoding, and then fall back to other encodings
922 as necessary based on the encodings supported by the Server.
923 For example, a Server that supports both XML and JSON encoding as defined in the [OBIX Encodings]
924 specification would have a Lobby that appeared as follows (note the displayNames used are optional):
925 <obj is="obix:Lobby">
926 {... other lobby items ...}
927 <list name="encodings" of="obix:str">
928 <str val="text/xml" displayName="XML"/>
929 <str val="application/json" displayName="JSON"/>
930 </list>
931 </obj>
932 A Server that receives a request for an encoding that is not supported MUST send an UnsupportedErr
933 response (see Section 10.2).

934 5.5.4 Bindings

935 Servers MUST include the available bindings supported in the bindings Lobby Object. This is a list
936 of uris. The name of each uri SHOULD be the name of the binding as described by its corresponding
937 specification document. If the binding is not a standard binding defined in the OBIX Bindings
938 specifications, the val of the uri SHOULD be included, and SHOULD contain a reference to the binding
939 specification.
940 Servers that support multiple bindings and encodings MAY support only certain combinations of the
941 available bindings and encodings. For example, a Server may support XML encoding over the HTTP and
942 SOAP bindings, but support JSON encoding only over the HTTP binding.
943 For example, a Server that supports the SOAP and HTTP bindings as defined in the [OBIX REST] and
944 [OBIX SOAP] specifications would have a Lobby that appeared as follows (note the displayNames
945 used are optional):
946 <obj is="obix:Lobby">
947 {... other lobby items ...}
948 <list name="bindings" of="obix:uri">
949 <uri name="http" displayName="HTTP Binding" val="http://docs.oasis-
950 open.org/obix/obix-rest/v1.0/obix-rest-v1.0.pdf"/>
951 <uri name="soap" displayName="SOAP Binding" val="http://docs.oasis-
952 open.org/obix/obix-soap/v1.0/obix-soap-v1.0.pdf"/>
953 </list>
954 </obj>

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 34 of 79
955 A Server that receives a request for a binding/encoding pair that is not supported MUST send an
956 UnsupportedErr response (see Section 10.2).

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 35 of 79
957 6 Naming
958 All OBIX objects have two potential identifiers: name and href. Name is used to define the role of an
959 Object within its parent. Names are programmatic identifiers only; the displayName Facet SHOULD be
960 used for human interaction. Naming convention is to use camel case with the first character in lowercase.
961 The primary purpose of names is to attach semantics to sub-objects. Names are also used to indicate
962 overrides from a Contract. A good analogy to names is the field/method names of a class in Java or C#.
963 Hrefs are used to attach URIs to objects. An href is always a URI reference [RFC3986], which means it
964 might be a relative URI or fragment URI [RFC3986] that requires normalization against a base URI. The
965 exception to this rule is the href of the root Object in an OBIX document – this href MUST be an absolute
966 URI, and NOT be a relative URI. This allows the root Object’s href to be used as the effective base URI
967 (xml:base) for normalization. A good analogy is hrefs in HTML or [XLINK].
968 Some Objects may have both a name and an href, just a name, just an href, or neither. It is common for
969 objects within a list to not use names, since most lists are unnamed sequences of objects. The OBIX
970 specification makes a clear distinction between names and hrefs - Clients MUST NOT assume any
971 relationship between names and hrefs. From a practical perspective many vendors will likely build an href
972 structure that mimics the name structure, but Client software MUST never assume such a relationship.

973 6.1 Name

974 The name of an Object is represented using the name attribute. Names are programmatic identifiers with
975 restrictions on their valid character set. A name SHOULD contain only ASCII letters, digits, underbar, or
976 dollar signs. A digit MUST NOT be used as the first character. Names SHOULD use lower Camel case
977 per [CamelCase] with the first character in lower case, as in the examples “foo”, “fooBar”,
978 “thisIsOneLongName”. Within a given Object, all of its direct children MUST have unique names. Objects
979 which don’t have a name attribute are called unnamed Objects. The root Object of an OBIX document
980 SHOULD NOT specify a name attribute (but almost always has an absolute href URI).

981 6.2 Href

982 The href of an Object is represented using the href attribute. If specified, the root Object MUST have an
983 absolute URI. All other hrefs within an OBIX document are treated as potentially relative URI references.
984 Because the root Object’s href is always an absolute URI, it may be used as the base for normalizing
985 relative URIs within the OBIX document. OBIX implementations MUST follow the formal rules for URI
986 syntax and normalization defined in [RFC3986]. Several common cases that serve as design patterns
987 within OBIX are considered in Section 6.3.
988 As a general rule every Object accessible for a read MUST specify a URI. An OBIX document returned
989 from a read request MUST specify a root URI. However, there are certain cases where the Object is
990 transient, such as a computed Object from an operation invocation. In these cases there MAY not be a
991 root URI, meaning there is no way to retrieve this particular Object again. If no root URI is provided, then
992 the Server’s authority URI is implied to be the base URI for resolving relative URI references.

993 6.3 URI Normalization

994 Implementers are free to use any URI schema, although the recommendation is to use URIs since they
995 have well defined normalization semantics. Implementations that use URIs MUST comply with the rules
996 and requirements described in [RFC3986]. Implementations SHOULD be able to interpret and navigate
997 HTTP URIs, as this is used by the majority of OBIX implementations.
998 Perhaps one of the trickiest issues is whether the base URI ends with a slash. If the base URI doesn’t
999 end with a slash, then a relative URI is assumed to be relative to the base’s parent (to match HTML). If
1000 the base URI does end in a slash, then relative URIs can just be appended to the base. In practice,
1001 systems organized into hierarchical URIs SHOULD always specify the base URI with a trailing slash.

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 36 of 79
1002 Retrieval with and without the trailing slash SHOULD be supported with the resulting OBIX document
1003 always adding the implicit trailing slash in the root Object’s href.

1004 6.4 Fragment URIs

1005 It is not uncommon to reference an Object internal to an OBIX document. This is achieved using fragment
1006 URI references starting with the “#” as described in Section 3.5 of [RFC3986]. Consider the example:
1007 <obj href="http://server/whatever/">
1008 <enum name="switch1" range="#onOff" val="on"/>
1009 <enum name="switch2" range="#onOff" val="off"/>
1010 <list is="obix:Range" href="onOff">
1011 <obj name="on"/>
1012 <obj name="off"/>
1013 </list>
1014 </obj>
1015 In this example there are two Objects with a range Facet referencing a fragment URI. Any URI reference
1016 starting with “#” MUST be assumed to reference an Object within the same OBIX document. Clients
1017 SHOULD NOT perform another URI retrieval to dereference the Object. In this case the Object being
1018 referenced is identified via the href attribute.
1019 In the example above the Object with an href of “onOff” is both the target of the fragment URI, but also
1020 has the absolute URI “http://server/whatever/onOff”. But consider an Object that was the target of a
1021 fragment URI within the document, but could not be directly addressed using an absolute URI. In that
1022 case the href attribute SHOULD be a fragment identifier itself. When an href attribute starts with “#” that
1023 means the only place it can be used is within the document itself:
1024 …
1025 <list is="obix:Range" href="#onOff">
1026 …

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 37 of 79
1027 7 Contracts and Contract Lists
1028 OBIX Contracts are used to define inheritance in OBIX Objects. A Contract is a template, defined as an
1029 OBIX Object, that is referenced by other Objects by using the URI to the Contract Definition. These
1030 templates are referenced using the is attribute. Contracts solve several important problems in OBIX:

Semantics Contracts are used to define “types” within OBIX. This lets us collectively agree on
common Object definitions to provide consistent semantics across vendor
implementations. For example the Alarm Contract ensures that Client software can
extract normalized alarm information from any vendor’s system using the exact
same Object structure.
Defaults Contracts also provide a convenient mechanism to specify default values. Note that
when serializing Object trees to XML (especially over a network), defaults are
typically not allowed, in order to keep Client processing simple.

Type Export OBIX will be used to interact with existing and future control systems based on
statically-typed languages such as Java or C#. Contracts provide a standard
mechanism to export type information in a format that all OBIX Clients can
consume.

1031 Table 7-1. Problems addressed by Contracts.

1032 The benefit of the Contract design is its flexibility and simplicity. Conceptually Contracts provide an
1033 elegant model for solving many different problems with one abstraction. One can define new abstractions
1034 using the OBIX syntax itself. Contracts also give us a machine readable format that Clients already know
1035 how to retrieve and parse –the exact same syntax is used to represent both a class and an instance.

1036 7.1 Contract Terminology

1037 Common terms that are useful for discussing Contracts are defined in the following Table.
Term Definition

Contract Contracts are the templates or prototypes used as the foundation of the OBIX
type system. They may contain both syntactical and semantic behaviors.
Contract Definition A reusable definition of a Contract, expressed as a standard OBIX Object and
referenced with a URI.
Contract List One or more Contracts, expressed as a list of URIs referencing Contract
Definitions. Contract List is used as the value of the is, of, in, and out
attributes. See Sections 4.2.3, 4.2.7.12, 4.2.7.13, and 4.2.7.14, respectively.
Implements When an Object specifies a Contract in its Contract List, the Object is said to
implement the Contract. This means that the Object is inheriting both the
structure and semantics of the specified Contract.
Implementation An Object which implements a Contract is said to be an implementation of that
Contract.

1038 Table 7-2. Contract terminology.

1039 7.2 Contract List

1040 The syntax of a Contract List attribute is a list of one or more URI references to other OBIX Objects. The
1041 URIs within the list MUST be separated by the space character (Unicode 0x20). To convey the absence

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 38 of 79
1042 of a Contract, i.e., and empty Contract List, the special Nil Contract is used. The Nil Contract Definition is
1043 in Section 11.1. Just like the href attribute, a Contract URI can be an absolute URI, Server relative, or
1044 even a fragment reference. The URIs within a Contract List may be scoped with an XML namespace
1045 prefix (see “Namespace Prefixes in Contract Lists” in the [OBIX Encodings] document).
1046 A Contract List is not an obix:list type described in Section 4.3.2. It is a string with special structure
1047 regarding the space-separated group of URIs.
1048 The only place Contract List is used in the OBIX specification is as the value of the is, of, in and out
1049 attributes. In fact, a Contract itself would never appear in an OBIX Object, as any instance in an Object
1050 would simply be a Contract List of one Contract. An example of a point that implements multiple
1051 Contracts and advertises this through its Contract List is:
1052 <real val="70.0" name="setpoint" is="obix:Point obix:WritablePoint acme:Setpoint"/>
1053 From this example, we can see that this 'setpoint' Object implements the Point and WritablePoint
1054 Contracts that are described in this specification (Section 13). It also implements a separate Contract
1055 defined with the acme namespace called Setpoint. A consumer of this Object can rely on the fact that it
1056 has all of the syntactical and semantic behaviors of each of these Contracts, and can interact with any of
1057 these behaviors.
1058 An example of an obix:list that uses Contract List in its of attribute to describe the type of items
1059 contained in the obix:list is:
1060 <list name="Logged Data" of="obix:Point obix:History">
1061 <real name="spaceTemp"/>
1062 <str val="Whiskers on Kittens"/>
1063 <str val="Bright Copper Kettles"/>
1064 <str val="Warm Woolen Mittens"/>
1065 </list>

1066 7.3 Is Attribute

1067 An Object defines the Contracts it implements via the is attribute. The value of the is attribute is a
1068 Contract List. If the is attribute is unspecified, then the following rules are used to determine the implied
1069 Contract List:
1070  If the Object is an item inside a list or feed, then the Contract List specified by the of attribute
1071 is used.
1072  If the Object overrides (by name) an Object specified in one of its Contracts, then the Contract
1073 List of the overridden Object is used.
1074  If all the above rules fail, then the respective primitive Contract is used. For example, an obj
1075 element has an implied Contract of obix:obj and real an implied Contract of obix:real.
1076 Element names such as bool, int, or str are abbreviations for implied Contracts. However if an Object
1077 implements one of the primitive types, then it MUST use the correct OBIX type name. If an Object
1078 implements obix:int, then it MUST be expressed as <int/>, and MUST NOT use the form <obj
1079 is="obix:int"/>. An Object MUST NOT implement multiple value types, such as implementing both
1080 obix:bool and obix:int. An Object MUST NOT specify an empty is attribute (using the obix:Nil
1081 Contract), as all Objects derive at least from obix:obj.

1082 7.4 Contract Inheritance

1083 7.4.1 Structure vs Semantics
1084 Contracts are a mechanism of inheritance – they establish the classic “is a” relationship. In the abstract
1085 sense a Contract allows inheritance of a type. One can further distinguish between the explicit and implicit
1086 Contract:
Explicit Contract Defines an object structure which all implementations must conform
with. This can be evaluated quantitatively by examining the Object

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 39 of 79
 data structure.
Implicit Contract Defines semantics associated with the Contract. The implicit Contract
is typically documented using natural language prose. It is
qualitatively interpreted, rather than quantitatively interpreted.

1087 Table 7-3. Explicit and Implicit Contracts.

1088 For example when an Object implements the Alarm Contract, one can immediately infer that it will have a
1089 child called timestamp. This structure is in the explicit contract of Alarm and is formally defined in its
1090 encoded definition. But semantics are also attached to what it means to be an Alarm Object: that the
1091 Object is providing information about an alarm event. These subjective concepts cannot be captured in
1092 machine language; rather they can only be captured in prose.
1093 When an Object declares itself to implement a Contract it MUST meet both the explicit Contract and the
1094 implicit Contract. An Object MUST NOT put obix:Alarm in its Contract List unless it really represents an
1095 alarm event. Interpretation of Implicit Contracts generally requires that a human brain be involved, i.e.,
1096 they cannot in general be consumed with pure machine-to-machine interaction.

1097 7.4.2 Overriding Defaults

1098 A Contract’s named children Objects are automatically applied to implementations. An implementation
1099 may choose to override or default each of its Contract’s children. If the implementation omits the child,
1100 then it is assumed to default to the Contract’s value. If the implementation declares the child (by name),
1101 then it is overridden and the implementation’s value SHOULD be used. Let’s look at an example:
1102 <obj href="/def/television">
1103 <bool name="power" val="false"/>
1104 <int name="channel" val="2" min="2" max="200"/>
1105 </obj>
1106
1107 <obj href="/livingRoom/tv" is="/def/television">
1108 <int name="channel" val="8"/>
1109 <int name="volume" val="22"/>
1110 </obj>
1111 In this example a Contract Object is identified with the URI “/def/television”. It has two children to store
1112 power and channel. The living room TV instance includes “/def/television” in its Contract List via the is
1113 attribute. In this Object, channel is overridden to 8 from its default value of 2. However since power was
1114 omitted, it is implied to default to false.
1115 An override is always matched to its Contract via the name attribute. In the example above it was clear
1116 that ‘channel’ was being overridden, because an Object was declared with a name of ‘channel’. A second
1117 Object was also declared with a name of ‘volume’. Since volume wasn’t declared in the Contract, it is
1118 assumed to be a new definition specific to this Object.

1119 7.4.3 Attributes and Facets

1120 Also note that the Contract’s channel Object declares a min and max Facet. These two Facets are also
1121 inherited by the implementation. Almost all attributes are inherited from their Contract including Facets,
1122 val, of, in, and out. The href attribute is never inherited. The null attribute inherits as follows:
1123 1. If the null attribute is specified, then its explicit value is used;
1124 2. If a val attribute is specified and null is unspecified, then null is implied to be false;
1125 3. If neither a val attribute or a null attribute is specified, then the null attribute is inherited from
1126 the Contract;
1127 4. If the null attribute is specified and is true, then the val attribute is ignored.
1128 This allows us to implicitly override a null Object to non-null without specifying the null attribute.

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 40 of 79
1129 7.5 Override Rules
1130 Contract overrides are REQUIRED to obey the implicit and explicit Contract. Implicit means that the
1131 implementation Object provides the same semantics as the Contract it implements. In the example above
1132 it would be incorrect to override channel to store picture brightness. That would break the semantic
1133 Contract.
1134 Overriding the explicit Contract means to override the value, Facets, or Contract List. However one can
1135 never override the Object to be an incompatible value type. For example if the Contract specifies a child
1136 as real, then all implementations must use real for that child. As a special case, obj may be narrowed
1137 to any other element type.
1138 One must also be careful when overriding attributes to never break restrictions the Contract has defined.
1139 Technically this means the value space of a Contract can be specialized or narrowed, but never
1140 generalized or widened. This concept is called covariance. Returning to the example from above:
1141 <int name="channel" val="2" min="2" max="200"/>
1142 In this example the Contract has declared a value space of 2 to 200. Any implementation of this Contract
1143 must meet this restriction. For example it would an error to override min to –100 since that would widen
1144 the value space. However the value space can be narrowed by overriding min to a number greater than 2
1145 or by overriding max to a number less than 200. The specific override rules applicable to each Facet are
1146 documented in section 4.2.7.

1147 7.6 Multiple Inheritance

1148 An Object’s Contract List may specify multiple Contract URIs to implement. This is actually quite common
1149 - even required in many cases. There are two terms associated with the implementation of multiple
1150 Contracts:

Flattening Contract Lists SHOULD always be flattened when specified. This comes into play
when a Contract has its own Contract List (Section 7.6.1).
Mixins The mixin design specifies the exact rules for how multiple Contracts are merged
together. This section also specifies how conflicts are handled when multiple
Contracts contain children with the same name (Section 7.6.2).

1151 Table 7-4. Contract inheritance.

1152 7.6.1 Flattening

1153 It is common for Contract Objects themselves to implement Contracts, just like it is common in OO
1154 languages to chain the inheritance hierarchy. However due to the nature of accessing OBIX documents
1155 over a network, it is often desired to minimize round trip network requests which might be needed to
1156 “learn” about a complex Contract hierarchy. Consider this example:
1157 <obj href="/A" />
1158 <obj href="/B" is="/A" />
1159 <obj href="/C" is="/B" />
1160 <obj href="/D" is="/C" />
1161 In this example if an OBIX Client were reading Object D for the first time, it would take three more
1162 requests to fully learn what Contracts are implemented (one for C, B, and A). Furthermore, if the Client
1163 was just looking for Objects that implemented B, it would difficult to determine this just by looking at D.
1164 Because of these issues, Servers are REQUIRED to flatten their Contract inheritance hierarchy into a list
1165 when specifying the is, of, in, or out attributes. In the example above, the correct representation would
1166 be:
1167 <obj href="/A" />
1168 <obj href="/B" is="/A" />
1169 <obj href="/C" is="/B /A" />
1170 <obj href="/D" is="/C /B /A" />

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 41 of 79
1171 This allows Clients to quickly scan D’s Contract List to see that D implements C, B, and A without further
1172 requests.
1173 Because complex Servers often have a complex Contract hierarchy of Object types, the requirement to
1174 flatten the Contract hierarchy can lead to a verbose Contract List. Often many of these Contracts are
1175 from the same namespace. For example:
1176 <obj name="VSD1" href="acme:VSD-1" is="acmeObixLibrary:VerySpecificDevice1
1177 acmeObixLibrary:VerySpecificDeviceBase acmeObixLibrary:SpecificDeviceType
1178 acmeObixLibrary:BaseDevice acmeObixLibrary:BaseObject"/>
1179 To save space, Servers MAY choose to combine the Contracts from the same namespace and present
1180 the Contract List with the namespace followed by a colon, then a brace-enclosed list of Contract names:
1181 <real name="writableReal" is="obix:{Point WritablePoint}"/>
1182
1183 <obj name="vsd1" href="acme:VSD-1" is="acmeObixLibrary:{VerySpecificDevice1
1184 VerySpecificDeviceBase SpecificDeviceType BaseDevice BaseObject}"/>
1185 Clients MUST be able to consume this form of the Contract List and expand it to the standard form.

1186 7.6.2 Mixins

1187 Flattening is not the only reason a Contract List might contain multiple Contract URIs. OBIX also supports
1188 the more traditional notion of multiple inheritance using a mixin approach as in the following example:
1189 <obj href="acme:Device">
1190 <str name="serialNo"/>
1191 </obj>
1192
1193 <obj href="acme:Clock" is="acme:Device">
1194 <op name="snooze"/>
1195 <int name="volume" val="0"/>
1196 </obj>
1197
1198 <obj href="acme:Radio" is="acme:Device ">
1199 <real name="station" min="87.0" max="107.5"/>
1200 <int name="volume" val="5"/>
1201 </obj>
1202
1203 <obj href="acme:ClockRadio" is="acme:Radio acme:Clock acme:Device"/>
1204 In this example ClockRadio implements both Clock and Radio. Via flattening of Clock and Radio,
1205 ClockRadio also implements Device. In OBIX this is called a mixin – Clock, Radio, and Device are
1206 mixed into (merged into) ClockRadio. Therefore ClockRadio inherits four children: serialNo,
1207 snooze, volume, and station. Mixins are a form of multiple inheritance akin to Java/C# interfaces
1208 (remember OBIX is about the type inheritance, not implementation inheritance).
1209 Note that Clock and Radio both implement Device. This inheritance pattern where two types both
1210 inherit from a base, and are themselves both inherited by a single type, is called a “diamond” pattern from
1211 the shape it takes when the class hierarchy is diagrammed. From Device, ClockRadio inherits a child
1212 named serialNo. Furthermore notice that both Clock and Radio declare a child named volume. This
1213 naming collision could potentially create confusion for what serialNo and volume mean in
1214 ClockRadio.
1215 OBIX solves this problem by flattening the Contract’s children using the following rules:
1216 1. Process the Contract definitions in the order they are listed
1217 2. If a new child is discovered, it is mixed into the Object’s definition
1218 3. If a child is discovered that has already been processed via a previous Contract definition, then
1219 the previous definition takes precedence. However it is an error if the duplicate child is not
1220 Contract compatible with the previous definition (see Section 7.7).
1221 In the example above this means that Radio.volume is the definition used for ClockRadio.volume,
1222 because Radio has a higher precedence than Clock (it is first in the Contract List). Thus
1223 ClockRadio.volume has a default value of “5”. However it would be invalid if Clock.volume were
1224 declared as str, since it would not be Contract compatible with Radio’s definition as an int – in that

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 42 of 79
1225 case ClockRadio could not implement both Clock and Radio. It is the Server vendor’s responsibility
1226 not to create incompatible name collisions in Contracts.
1227 The first Contract in a list is given special significance since its definition trumps all others. In OBIX this
1228 Contract is called the Primary Contract. For this reason, the Primary Contract SHOULD implement all the
1229 other Contracts specified in the Contract List (this actually happens quite naturally by itself in many
1230 programming languages). This makes it easier for Clients to bind the Object into a strongly typed class if
1231 desired. Contracts MUST NOT implement themselves nor have circular inheritance dependencies.

1232 7.7 Contract Compatibility

1233 A Contract List which is covariantly substitutable with another Contract List is said to be Contract
1234 compatible. Contract compatibility is a useful term when talking about mixin rules and overrides for lists
1235 and operations. It is a concept similar to previously defined override rules – however, instead of the rules
1236 applied to individual Facet attributes, it is applied to an entire Contract List.
1237 A Contract List X is compatible with Contract List Y, if and only if X narrows the value space defined by Y.
1238 This means that X can narrow the set of Objects which implement Y, but never expand the set. Contract
1239 compatibility is not commutative (X is compatible with Y does not imply Y is compatible with X).
1240 Practically, this can be expressed as: X can add new URIs to Y’s list, but never take any away.

1241 7.8 Lists and Feeds

1242 Implementations derived from list or feed Contracts inherit the of attribute. Like other attributes an
1243 implementing Object can override the of attribute, but only if Contract compatible - a Server SHOULD
1244 include all of the URIs in the Contract’s of attribute, but it MAY add additional ones (see Section 7.7).
1245 Lists and Feeds also have the special ability to implicitly define the Contract List of their contents. In the
1246 following example it is implied that each child element has a Contract List of /def/MissingPerson
1247 without actually specifying the is attribute in each list item:
1248 <list of="/def/MissingPerson">
1249 <obj> <str name="fullName" val="Jack Shephard"/> </obj>
1250 <obj> <str name="fullName" val="John Locke"/> </obj>
1251 <obj> <str name="fullName" val="Kate Austen"/> </obj>
1252 </list>
1253 If an element in the list or Feed does specify its own is attribute, then it MUST be Contract compatible
1254 with the of attribute.
1255 If an implementation wishes to specify that a list should contain references to a given type, then the
1256 implementation SHOULD include obix:ref in the of attribute. This MUST be the first URI in the of
1257 attribute. For example, to specify that a list should contain references to obix:History Objects (as
1258 opposed to inline History Objects):
1259 <list name="histories" of="obix:ref obix:History"/>
1260 In many cases a Server will implement its own management of the URI scheme of the child elements of a
1261 list. For example, the href attribute of child elements may be a database key, or some other string
1262 defined by the Server when the child is added. Servers will not, in general, allow Clients to specify this
1263 URI during addition of child elements through a direct write to a list’s subordinate URI.
1264 Therefore, in order to add child elements to a list which supports Client addition of list elements, Servers
1265 MUST support adding list elements by writing to the list URI with an Object of a type that matches the
1266 list’s Contract. Servers MUST return the written resource (including any Server-assigned href) upon
1267 successful completion of the write.
1268 For example, given a list of <real> elements, and presupposing a Server-imposed URI scheme:
1269 <list href="/a/b" of="obix:real" writable="true"/>
1270 Writing to the list URI itself will replace the entire list if the Server supports this behavior:
1271 WRITE /a/b
1272 <list of="obix:real">
1273 <real name="foo" val="10.0"/>

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 43 of 79
1274 <real name="bar" val="20.0"/>
1275 </list>
1276 returns:
1277 <list href="/a/b" of="obix:real">
1278 <real name="foo" href="1" val="10.0"/>
1279 <real name="bar" href="2" val="20.0"/>
1280 </list>
1281 Writing a single element of type <real> will add this element to the list.
1282 WRITE /a/b
1283 <real name="baz" val="30.0"/>
1284 returns:
1285 <real name="baz" href="/a/b/3" val="30.0"/>
1286 while the list itself is now:
1287 <list href="/a/b" of="obix:real">
1288 <real name="foo" href="1" val="10.0"/>
1289 <real name="bar" href="2" val="20.0"/>
1290 <real name="baz" href="3" val="30.0"/>
1291 </list>
1292 Note that if a Client has the correct URI to reference a list child element, this can still be used to modify
1293 the value of the element directly:
1294 WRITE /a/b/3
1295 <real name="baz2" val="33.0"/>
1296 returns:
1297 <real name="baz2" href="/a/b/3" val="33.0"/>
1298 and the list has been modified to:
1299 <list href="/a/b" of="obix:real">
1300 <real name="foo" href="1" val="10.0"/>
1301 <real name="bar" href="2" val="20.0"/>
1302 <real name="baz" href="3" val="33.0"/>
1303 </list>

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 44 of 79
1304 8 Operations
1305 OBIX Operations are the exposed actions that an OBIX Object can be commanded to take, i.e., they are
1306 things you can invoke to “do” something to the Object. Typically object-oriented languages express this
1307 concept as the publicly accessible methods on the object. They generally map to commands rather than a
1308 variable that has continuous state. Unlike Value Objects which represent an Object and its current state,
1309 the op element merely represents the definition of an operation you can invoke.
1310 All operations take exactly one Object as a parameter and return exactly one Object as a result. The in
1311 and out attributes define the Contract List for the input and output Objects. If you need multiple input or
1312 output parameters, then wrap them in a single Object using a Contract as the signature. For example:
1313 <op href="/addTwoReals" in="/def/AddIn" out="obix:real"/>
1314
1315 <obj href="/def/AddIn">
1316 <real name="a"/>
1317 <real name="b"/>
1318 </obj>
1319 Objects can override the operation definition from one of their Contracts. However the new in or out
1320 Contract List MUST be Contract compatible (see Section 7.7) with the Contract’s definition.
1321 If an operation doesn’t require a parameter, then specify in as obix:Nil. If an operation doesn’t return
1322 anything, then specify out as obix:Nil. Occasionally an operation is inherited from a Contract which is
1323 unsupported in the implementation. In this case set the status attribute to disabled.
1324 Operations are always invoked via their own href attribute (not their parent’s href). Therefore
1325 operations SHOULD always specify an href attribute if you wish Clients to invoke them. A common
1326 exception to this rule is Contract definitions themselves.

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 45 of 79
1327 9 Object Composition
1328 Object Composition describes how multiple OBIX Objects representing individual pieces are combined to
1329 form a larger unit. The individual pieces can be as small as the various data fields in a simple thermostat,
1330 as described in Section 2, or as large as entire buildings, each themselves composed of multiple
1331 networks of devices. All of the OBIX Objects are linked together via URIs, similar to the way that the
1332 World Wide Web is a group of HTML documents hyperlinked together through URIs These OBIX Objects
1333 may be static documents like Contracts or device descriptions. Or they may be real-time data or services.
1334 Individual Objects are composed together in two ways to define this web. Objects may be composed
1335 together via containment or via reference.

1336 9.1 Containment

1337 Any OBIX Object may contain zero or more child Objects. This even includes Objects which might be
1338 considered primitives such as bool or int. All Objects are open ended and free to specify new Objects
1339 which may not be in the Object’s Contract. Containment is represented in the XML syntax by nesting the
1340 XML elements:
1341 <obj href="/a/">
1342 <list name="b" href="b">
1343 <obj href="b/c"/>
1344 </list>
1345 </obj>
1346 In this example the Object identified by “/a” contains “/a/b”, which in turn contains “/a/b/c”. Child Objects
1347 may be named or unnamed depending on if the name attribute is specified (Section 6.1). In the example,
1348 “/a/b” is named and “/a/b/c” is unnamed. Typically named children are used to represent fields in a record,
1349 structure, or class type. Unnamed children are often used in lists.

1350 9.2 References

1351
1352 To understand references, it is useful to return to the World Wide Web metaphor. Individual HTML
1353 elements like <p> and <div> are grouped into HTML documents, which are the atomic entities passed
1354 over the network. The documents are linked together using the <a> anchor element. These anchors
1355 serve as placeholders, referencing outside documents via a URI.
1356 An OBIX reference is similar to an HTML anchor. It serves as a placeholder to “link” to another OBIX
1357 Object via a URI. While containment is best used to model small trees of data, references may be used to
1358 model very large trees or graphs of Objects.
1359 As a clue to Clients consuming OBIX references, the Server SHOULD specify the type of the referenced
1360 Object using the is attribute. In addition, for the list element type, the Server SHOULD use the of
1361 attribute to specify the type of Objects contained by the list. This allows the Client to prepare the
1362 proper visualizations, data structures, etc. for consuming the Object when it accesses the actual Object.
1363 For example, a Server might provide a reference to a list of available points:
1364 <ref name="points" is="obix:list" of="obix:Point"/>

1365 9.3 Extents

1366 Within any problem domain, the intra-model relationships can be expressed by using either containment
1367 or references. The choice changes the semantics of both the model expression as well as the method for
1368 accessing the elements within the model. The containment relationship is imbued with special semantics
1369 regarding encoding and event management. If the model is expressed through containment, then OBIX
1370 uses the term Extent to refer to the tree of children contained within that Object, down to references. Only
1371 Objects which have an href have an Extent. Objects without an href are always included within the Extent

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 46 of 79
1372 of one or more referenceable Objects which are called its ancestors. This is demonstrated in the
1373 following example.
1374 <obj href="/a/">
1375 <obj name="b" href="b">
1376 <obj name="c"/>
1377 <ref name="d" href="/d"/>
1378 </obj>
1379 <ref name="e" href="/e"/>
1380 </obj>
1381 In the example above, there are five Objects named ‘a’ to ‘e’. Because ‘a’ includes an href, it has an
1382 associated extent, which encompasses ‘b’ and ‘c’ by containment and ‘d’ and ‘e’ by reference. Likewise,
1383 ‘b’ has an href which results in an extent encompassing ‘c’ by containment and ‘d’ by reference. Object ‘c’
1384 does not provide a direct href, but exists in both the ‘a’ and ‘b’ Objects’ extents. Note an Object with an
1385 href has exactly one extent, but can be nested inside multiple extents.
1386 When marshaling Objects into an OBIX document, it is REQUIRED that an extent always be fully inlined
1387 into the document. Only ref Objects may reference targets outside the scope of the document. In order
1388 to allow conservation of bandwidth usage, processing time, and storage requirements, Servers SHOULD
1389 use non-ref Objects only for representing primitive children which have no further extent. Refs
1390 SHOULD be used for all complex children that have further structure under them. Clients MUST be able
1391 to consume the refs and then request the referenced object if it is needed for the application. As an
1392 example, consider a Server which has the following object tree, represented here with full extent:
1393 <obj name="myBuilding" href="/building/">
1394 <str name="address" val="123 Main Street"/>
1395 <obj name="floor1">
1396 <obj name="zone1">
1397 <obj name="room1"/>
1398 </obj>
1399 </obj>
1400 </obj>
1401 When marshaled into an OBIX document to respond to a Client Read request of the /building/ URI, the
1402 Server SHOULD inline only the address, and use a ref for Floor1:
1403 <obj name="myBuilding" href="/building/">
1404 <str name="address" val="123 Main Street"/>
1405 <ref name="floor1" href="floor1"/>
1406 </obj>
1407 If the Object implements a Contract, then it is REQUIRED that the extent defined by the Contract be fully
1408 inlined into the document (unless the Contract itself defined a child as a ref element). An example of a
1409 Contract which specifies a child as a ref is Lobby.about (Section 5.2).

1410 9.4 Metadata

1411 An OBIX Server MAY present additional metadata about Objects in its model through the use of Tags. A
1412 Tag is simply a name-value pair represented as a child element of the Object about which the Tag is
1413 providing information. Tags containing values MUST be represented with an OBIX primitive matching the
1414 value type. Certain Tags, called “marker” Tags, have a 'null' value. This is commonly treated as having
1415 only the name, with no value. Marker Tags MUST be represented in the is attribute of the object, as
1416 they are semantically identical to Marker Contracts. If these Tags are defined in an external Tag space,
1417 e.g. Haystack, a building information model (BIM), etc., then the Tags MUST reference the Tag space by
1418 an identifier which MUST be declared in the Lobby, along with the URI for the semantic model it
1419 represents. The format for the Lobby definition is discussed in Section 5.5.1.
1420 The only exception is the obix Tag Space, which represents Tags defined within the OBIX Specification.
1421 The obix: prefix MAY be omitted for marker Tags defined by the OBIX Specification. Correspondingly,
1422 any Tag found while decoding the is attribute of an OBIX Object MUST be interpreted as referencing the
1423 obix Tag Space.
1424 Multiple Tag spaces MAY be included simultaneously in an Object. For example, a Server representing a
1425 building management system might present one of its Variable Air Volume (VAV) controllers using

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 47 of 79
1426 metadata from both HVAC and Building Tag Spaces as shown below. The Lobby would express the
1427 models used, as in Section 5.5.1:
1428 <obj is="obix:Lobby">
1429 <!-- ... other lobby items ...-->
1430 <list name="tagspaces" of="obix:uri">
1431 <uri name="hvac" displayName="HVAC Tag Dictionary"
1432 val="http://example.com/tags/hvac">
1433 <str name="version" val="1.0.42"/>
1434 </uri>
1435 <uri name="bldg" displayName="Building Terms Dictionary"
1436 val="http://example.com/tags/building">
1437 <abstime name="retrieved" val="2014-07-01T10:39:00Z"/>
1438 </uri>
1439 </list>
1440 </obj>
1441 Then, the Object representing the VAV controller would reference these dictionaries using their names in
1442 the tagspace attribute, and the Tag names as defined in the dictionary:
1443 <real name="VAV-101" href="/MainCampus/BurnsHall/Floor1/Room101/VAV/" val="70.0"
1444 is="hvac:temperature hvac:vav">
1445 <real name="spaceTemp" href="spaceTemp/" val="70.0"/>
1446 <real name="setpoint" href="setpoint/" val="72.0"/>
1447 <bool name="heatCmd" href="heatCmd/" val="true"/>
1448 <enum name="sensorType" val="ThermistorType3"/>
1449 <int name="roomNumber" ts="bldg" val="101"/>
1450 <int name="floor" ts="bldg" val="1"/>
1451 <str name="buildingName" ts="bldg" val="Montgomery Burns Science Labs"/>
1452 <uri name="ahuReference" ts="hvac" val="/MainCampus/BurnsHall/AHU/AHU1"/>
1453 </real>
1454 When the only Tags provided are marker Tags, this collapses to a much more compact presentation. For
1455 example, if using the hypothetical HVAC tag dictionary above to represent a chilled water temperature
1456 sensor point, a Server might provide an object to OBIX, annotated with several Tags, as follows:
1457 <real name="CWT" displayName="Chilled Water Temperature" is="hvac:chilled hvac:water
1458 hvac:temp hvac:sensor hvac:point" val="30.0">
1459 </real>
1460 Servers SHOULD only provide this information to Clients that are properly authenticated and authorized,
1461 to avoid providing a vector for attack if usage of a particular model identifies the Server as an interesting
1462 target.
1463 The metadata SHOULD be presented using the ref element, so this additional information can be
1464 skipped during normal encoding. If a Client is able to consume the metadata, it SHOULD ask for the
1465 metadata by requesting the metadata hierarchy.
1466 OBIX Clients SHALL ignore information that they do not understand. In particular, a conformant Client
1467 that is presented with Tags that it does not understand MUST ignore those Tags. No OBIX Server may
1468 require understanding of these Tags for interoperation.

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 48 of 79
1469 10 Networking
1470 The heart of OBIX is its object model and associated encoding. However, the primary use case for OBIX
1471 is to access information and services over a network. The OBIX architecture is based on a Client/Server
1472 network model, described below:
Server An entity containing OBIX enabled data and services. Servers respond
to requests from Client over a network.

Client An entity which makes requests to Servers over a network to access

OBIX enabled data and services.

1473 Table 10-1. Network model for OBIX.

1474 There is nothing to prevent a device or system from being both an OBIX Client and Server. However, a
1475 key tenet of OBIX is that a Client is NOT REQUIRED to implement Server functionality which might
1476 require a Server socket to accept incoming requests.

1477 10.1 Service Requests

1478 All service requests made against an OBIX Server can be distilled to 4 atomic operations, expressed in
1479 the following Table:
Request Description

Read Return the current state of an object at a given URI as an OBIX Object.
Write Update the state of an existing object at a URI. The state to write is passed over the
network as an OBIX Object. The new updated state is returned in an OBIX Object.
Invoke Invoke an operation identified by a given URI. The input parameter and output result
are passed over the network as an OBIX Object.
Delete Delete the object at a given URI.

1480 Table 10-2. OBIX Service Requests.

1481 Exactly how these requests and responses are implemented between a Client and Server is called a
1482 protocol binding. The OBIX specification defines standard protocol bindings in separate companion
1483 documents. All protocol bindings MUST follow the same read, write, invoke, and delete semantics
1484 discussed next.

1485 10.1.1 Read

1486 The read request specifies an object’s URI and the read response returns the current state of the object
1487 as an OBIX document. The response MUST include the Object’s complete extent (see Section 9.3).
1488 Servers may return an err Object to indicate the read was unsuccessful – the most common error is
1489 obix:BadUriErr (see Section 10.2 for standard error Contracts).

1490 10.1.2 Write

1491 The write request is designed to overwrite the current state of an existing Object. The write request
1492 specifies the URI of an existing Object and its new desired state. The response returns the updated state
1493 of the Object. If the write is successful, the response MUST include the Object’s complete extent (see
1494 Section 9.3). If the write is unsuccessful, then the Server MUST return an err Object indicating the
1495 failure.

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 49 of 79
1496 The Server is free to completely or partially ignore the write, so Clients SHOULD be prepared to examine
1497 the response to check if the write was successful. Servers may also return an err Object to indicate the
1498 write was unsuccessful.
1499 Clients are NOT REQUIRED to include the Object’s full extent in the request. Objects explicitly specified
1500 in the request object tree SHOULD be overwritten or “overlaid” over the Server’s actual object tree. Only
1501 the val attribute SHOULD be specified for a write request (outside of identification attributes such as
1502 name). The null attribute MAY also be used to set an Object to null. If the null attribute is not specified
1503 and the val attribute is specified, then it is implied that null is false.The behavior of a Server upon
1504 receiving a write request which provides Facets is unspecified with regards to the Facets. When writing
1505 int or reals with units, the write value MUST be in the same units as the Server specifies in read
1506 requests – Clients MUST NOT provide a different unit Facet and expect the Server to auto-convert (in
1507 fact the unit Facet SHOULD NOT be included in the request).

1508 10.1.3 Invoke

1509 The invoke request is designed to trigger an operation. The invoke request specified the URI of an op
1510 Object and the input argument Object. The response includes the output Object. The response MUST
1511 include the output Object’s complete extent (see Section 9.3). Servers MAY instead return an err Object
1512 to indicate the invocation was unsuccessful.

1513 10.1.4 Delete

1514 The delete request is designed to remove an existing Object from the Server. The delete request
1515 specifies the URI of an existing Object. If the delete is successful, the Server MUST return an empty
1516 response. If the delete is unsuccessful, the Server MUST return an err Object indicating the failure.

1517 10.2 Errors

1518 Request errors are conveyed to Clients with the err element. Any time an OBIX Server successfully
1519 receives a request and the request cannot be processed, then the Server MUST return an err Object to
1520 the Client. This includes improperly encoded requests, such as non-well-formed XML, if that encoding is
1521 used. Returning a valid OBIX document with err SHOULD be used when feasible rather than protocol
1522 specific error handling (such as an HTTP response code). Such a design allows for consistency with
1523 batch request partial failures and makes protocol binding more pluggable by separating data transport
1524 from application level error handling.
1525 The following Table describes the base Contracts predefined for representing common errors:
Err Contract Usage

BadUriErr Used to indicate either a malformed URI or a unknown URI

UnsupportedErr Used to indicate an a request which isn’t supported by the Server implementation
(such as an operation defined in a Contract, which the Server doesn’t support)
PermissionErr Used to indicate that the Client lacks the necessary security permission to access
the object or operation

1526 Table 10-3. OBIX Error Contracts.

1527 The Contracts for these errors are:
1528 <err href="obix:BadUriErr"/>
1529 <err href="obix:UnsupportedErr"/>
1530 <err href="obix:PermissionErr"/>
1531 If one of the above Contracts makes sense for an error, then it SHOULD be included in the err element’s
1532 is attribute. It is strongly encouraged to also include a useful description of the problem in the display
1533 attribute.

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 50 of 79
1534 10.3 Localization
1535 Servers SHOULD localize appropriate data based on the desired locale of the Client agent. Localization
1536 SHOULD include the display and displayName attributes. The desired locale of the Client SHOULD
1537 be determined through authentication or through a mechanism appropriate to the binding used. A
1538 suggested algorithm is to check if the authenticated user has a preferred locale configured in the Server’s
1539 user database, and if not then fallback to the locale derived from the binding.
1540 Localization MAY include auto-conversion of units. For example if the authenticated user has configured
1541 a preferred unit system such as English versus Metric, then the Server might attempt to convert values
1542 with an associated unit facet to the desired unit system.

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 51 of 79
1543 11 Core Contract Library
1544 This chapter defines some fundamental Object Contracts that serve as building blocks for the OBIX
1545 specification. This Core Contract Library is also called the Standard Library, and is expressed in the
1546 stdlib.obix file that is associated with this specification.

1547 11.1 Nil

1548 The obix:Nil Contract defines a standardized null Object. Nil is commonly used for an operation’s in
1549 or out attribute to denote the absence of an input or output. The definition:
1550 <obj href="obix:Nil" null="true"/>

1551 11.2 Range

1552 The obix:Range Contract is used to define a bool or enum’s range. Range is a list Object that contains
1553 zero or more Objects called the range items. Each item’s name attribute specifies the identifier used as
1554 the literal value of an enum. Item ids are never localized, and MUST be used only once in a given range.
1555 You may use the optional displayName attribute to specify a localized string to use in a user interface.
1556 The definition of Range:
1557 <list href="obix:Range" of="obix:obj"/>
1558 An example:
1559 <list href="/enums/offSlowFast" is="obix:Range">
1560 <obj name="off" displayName="Off"/>
1561 <obj name="slow" displayName="Slow Speed"/>
1562 <obj name="fast" displayName="Fast Speed"/>
1563 </list>
1564 The range Facet may be used to define the localized text of a bool value using the ids of “true” and
1565 “false”:
1566 <list href="/enums/onOff" is="obix:Range">
1567 <obj name="true" displayName="On"/>
1568 <obj name="false" displayName="Off"/>
1569 </list >

1570 11.3 Weekday

1571 The obix:Weekday Contract is a standardized enum for the days of the week:
1572 <enum href="obix:Weekday" range="#Range">
1573 <list href="#Range" is="obix:Range">
1574 <obj name="sunday" />
1575 <obj name="monday" />
1576 <obj name="tuesday" />
1577 <obj name="wednesday" />
1578 <obj name="thursday" />
1579 <obj name="friday" />
1580 <obj name="saturday" />
1581 </list>
1582 </enum>

1583 11.4 Month

1584 The obix:Month Contract is a standardized enum for the months of the year:
1585 <enum href="obix:Month" range="#Range">
1586 <list href="#Range" is="obix:Range">
1587 <obj name="january" />
1588 <obj name="febuary" />
1589 <obj name="march" />
1590 <obj name="april" />

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 52 of 79
1591 <obj name="may" />
1592 <obj name="june" />
1593 <obj name="july" />
1594 <obj name="august" />
1595 <obj name="september" />
1596 <obj name="october" />
1597 <obj name="november" />
1598 <obj name="december" />
1599 </list>
1600 </enum>

1601 11.5 Units

1602 Representing units of measurement in software is a thorny issue. OBIX provides a unit framework for
1603 mathematically defining units within the object model. An extensive database of predefined units is also
1604 provided.
1605 All units measure a specific quantity or dimension in the physical world. Most known dimensions can be
1606 expressed as a ratio of the seven fundamental dimensions: length, mass, time, temperature, electrical
1607 current, amount of substance, and luminous intensity. These seven dimensions are represented in the [SI
1608 Units] system respectively as kilogram (kg), meter (m), second (sec), Kelvin (K), ampere (A), mole (mol),
1609 and candela (cd).
1610 The obix:Dimension Contract defines the ratio of the seven SI units using a positive or negative
1611 exponent:
1612 <obj href="obix:Dimension">
1613 <int name="kg" val="0"/>
1614 <int name="m" val="0"/>
1615 <int name="sec" val="0"/>
1616 <int name="K" val="0"/>
1617 <int name="A" val="0"/>
1618 <int name="mol" val="0"/>
1619 <int name="cd" val="0"/>
1620 </obj>
1621 A Dimension Object contains zero or more ratios of kg, m, sec, K, A, mol, or cd. Each of these ratio
1622 maps to the exponent of that base SI unit. If a ratio is missing then the default value of zero is implied. For
2
1623 example acceleration is m/s , which would be encoded in OBIX as:
1624 <obj is="obix:Dimension">
1625 <int name="m" val="1"/>
1626 <int name="sec" val="-2"/>
1627 </obj>
1628
1629 Units with equal dimensions are considered to measure the same physical quantity. This is not always
1630 precisely true, but is good enough for practice. This means that units with the same dimension are
1631 convertible. Conversion can be expressed by specifying the formula used to convert the unit to the
1632 dimension’s normalized unit. The normalized unit for every dimension is the ratio of SI units itself. For
example the normalized unit of energy is the joule m kgs . The kilojoule is 1000 joules and the watt-
2 -2
1633
1634 hour is 3600 joules. Most units can be mathematically converted to their normalized unit and to other
1635 units using the linear equations:
1636 unit = dimension  scale + offset
1637 toNormal = scalar  scale + offset
1638 fromNormal = (scalar - offset) / scale
1639 toUnit = fromUnit.fromNormal( toUnit.toNormal(scalar) )
1640 There are some units which don’t fit this model including logarithm units and units dealing with angles.
1641 But this model provides a practical solution for most problem spaces. Units which don’t fit this model
1642 SHOULD use a dimension where every exponent is set to zero. Applications SHOULD NOT attempt
1643 conversions on these types of units.
1644 The obix:Unit Contract defines a unit including its dimension and its toNormal equation:
1645 <obj href="obix:Unit">
1646 <str name="symbol"/>
1647 <obj name="dimension" is="obix:Dimension"/>

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 53 of 79
1648 <real name="scale" val="1"/>
1649 <real name="offset" val="0"/>
1650 </obj>
1651 The unit element contains symbol, dimension, scale, and offset sub-Objects, as described in the
1652 following Table:
symbol The symbol element defines a short abbreviation to use for the unit. For example
“F” would be the symbol for degrees Fahrenheit. The symbol element SHOULD
always be specified.
dimension The dimension Object defines the dimension of measurement as a ratio of the
seven base SI units. If omitted, the dimension Object defaults to the
obix:Dimension Contract, in which case the ratio is the zero exponent for all
seven base units.
scale The scale element defines the scale variable of the toNormal equation. The
scale Object defaults to 1.
offset The offset element defines the offset variable of the toNormal equation. If
omitted then offset defaults to 0.

1653 Table 11-1. OBIX Unit composition.

1654 The display attribute SHOULD be used to provide a localized full name for the unit based on the
1655 Client’s locale. If the display attribute is omitted, Clients SHOULD use symbol for display purposes.
1656
1657 An example for the predefined unit for kilowatt:
1658 <obj href="obix:units/kilowatt" display="kilowatt">
1659 <str name="symbol" val="kW"/>
1660 <obj name="dimension">
1661 <int name="m" val="2"/>
1662 <int name="kg" val="1"/>
1663 <int name="sec" val="-3"/>
1664 </obj>
1665 <real name="scale" val="1000"/>
1666 </obj>
1667 Automatic conversion of units is considered a localization issue.

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 54 of 79
1668 12 Watches
1669 A key requirement of OBIX is access to real-time information. OBIX is designed to enable Clients to
1670 efficiently receive access to rapidly changing data. However, Clients should not be required to implement
1671 web Servers or expose a well-known IP address. In order to address this problem, OBIX provides a
1672 model for event propagation called Watches.
1673 The Implicit Contract for Watch is described in the following lifecycle:
1674  The Client creates a new Watch Object with the make operation on the Server’s WatchService
1675 URI. The Server defines a new Watch Object and provides a URI to access the new Watch.
1676  The Client registers (and unregisters) Objects to watch using operations on the Watch Object.
1677  The Server tracks events that occur on the Objects in the Watch.
1678  The Client receives events from the Server about changes to Objects in the Watch. The events
1679 can be polled by the Client (see 12.1) or pushed by the Server (see 12.2).
1680  The Client may invoke the pollRefresh operation at any time to obtain a full list of the current
1681 value of each Object in the Watch.
1682  The Watch is freed, either by the explicit request of the Client using the delete operation, or
1683 when the Server determines the Watch is no longer being used. See Sections 12.1 and 12.2 for
1684 details on the criteria for Server removal of Watches. When the Watch is freed, the Objects in it
1685 are no longer tracked by the Server and the Server may return any resources used for it to the
1686 system.
1687 Watches allow a Client to maintain a real-time cache of the current state of one or more Objects. They are
1688 also used to access an event stream from a feed Object. Watches also serve as the standardized
1689 mechanism for managing per-Client state on the Server via leases.

1690 12.1 Client Polled Watches

1691 When the underlying binding does not allow the Server to send unsolicited messages, the Watch must be
1692 periodically polled by the Client. The Implicit Contract for Watch in this scenario is extended as follows:
1693  The Client SHOULD periodically poll the Watch URI using the pollChanges operation to obtain
1694 the events which have occurred since the last poll.
1695  In addition to freeing the Watch by explicit request of the Client, the Server MAY free the Watch if
1696 the Client fails to poll for a time greater than the lease time of the Watch. See the lease
1697 property in Section 12.4.5.

1698 12.2 Server Pushed Watches

1699 Some bindings, for example the [OBIX WebSocket] binding, may allow unsolicited transmission by either
1700 the Client or the Server. If this is possible the standard Implicit Contract for Watch behavior is extended
1701 as follows:
1702  Change events are sent by the Server directly to the Client as unsolicited updates.
1703  The lease time property of the Watch MUST NOT be used for Server automatic removal of the
1704 Watch. The Watch SHOULD remain active without the need for the Client to invoke the
1705 pollChanges or pollRefresh operations.
1706  The Watch MUST be removed by the Server upon termination of the underlying session between
1707 the Client and Server, in addition to the normal removal upon explicit Client request.
1708  The Server MUST return an empty list upon invocation of the pollChanges operation.
1709 Watches used in Servers that can push events MUST provide three additional properties for configuring
1710 the Watch behavior:
obix-v1.1-cs01 14 September 2015
Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 55 of 79
1711  bufferDelay: The implicit contract for bufferDelay is the period of time for which any events
1712 on watched objects will be buffered before being sent by the Server in an update. Clients must be
1713 able to regulate the flow of messages from the Server. A common scenario is an OBIX Client
1714 application on a mobile device where the bandwidth usage is important; for example, a Server
1715 sending updates every 50 milliseconds as a sensor value jitters around will cause problems. On
1716 the other hand, Server devices may be constrained in terms of the available space for buffering
1717 changes. Servers are free to set a maximum value on bufferDelay through the max Facet to
1718 constrain the maximum delay before the Server will report events.
1719  maxBufferedEvents: Servers may also use the maxBufferedEvents property to indicate the
1720 maximum number of events that can be retained before the buffer must be sent to the Client to
1721 avoid missing events.
1722  bufferPolicy: This enum property defines the handling of the buffer on the Server side when
1723 further events occur while the buffer is full. A value of violate means that the bufferDelay
1724 property is violated and the events are sent, allowing the buffer to be emptied. A value of lifo
1725 (last-in-first-out) means that the most recently added buffer event is replaced with the new event.
1726 A value of fifo (first-in-first-out) means that the oldest buffer event is dropped to make room for
1727 the new event.
1728  NOTE: A Server using a bufferPolicy of either lifo or fifo will not send events when a
1729 buffer overrun occurs, and this means that some events will not be received by the Client. It is up
1730 to the Client and Server to negotiate appropriate values for these three properties to ensure that
1731 events are not lost.

1732 Note that bufferDelay MUST be writable by the Client, as the Client capabilities typically constrain the
1733 bandwidth usage. Server capabilities typically constrain maxBufferedEvents, and thus this is generally
1734 not writable by Clients.

1735 12.3 WatchService

1736 The WatchService Object provides a well-known URI as the factory for creating new Watches. The
1737 WatchService URI is available directly from the Lobby Object. The Contract for WatchService:
1738 <obj href="obix:WatchService">
1739 <op name="make" in="obix:Nil" out="obix:Watch"/>
1740 </obj>
1741 The make operation returns a new empty Watch Object as an output. The href of the newly created
1742 Watch Object can then be used for invoking operations to populate and poll the data set.

1743 12.4 Watch

1744 The Watch Object is used to manage a set of Objects which are subscribed by Clients to receive the
1745 latest events. The Explicit Contract definitions are:
1746 <obj href="obix:Watch">
1747 <reltime name="lease" min="PT0S" writable="true"/>
1748 <reltime name="bufferDelay" min="PT0S" writable="true" null="true"/>
1749 <int name="maxBufferedEvents" null="true"/>
1750 <enum name="bufferPolicy" is="obix:WatchBufferPolicy" null="true"/>
1751 <op name="add" in="obix:WatchIn" out="obix:WatchOut"/>
1752 <op name="remove" in="obix:WatchIn"/>
1753 <op name="pollChanges" out="obix:WatchOut"/>
1754 <op name="pollRefresh" out="obix:WatchOut"/>
1755 <op name="delete"/>
1756 </obj>
1757
1758 <enum href="obix:WatchBufferPolicy" range="#Range">
1759 <list href="#Range" is="obix:Range">
1760 <obj name="violate" />
1761 <obj name="lifo" />
1762 <obj name="fifo" />
1763 </list>
1764 </enum>

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 56 of 79
1765
1766 <obj href="obix:WatchIn">
1767 <list name="hrefs" of="obix:WatchInItem"/>
1768 </obj>
1769
1770 <uri href="obix:WatchInItem">
1771 <obj name="in"/>
1772 </uri>
1773
1774 <obj href="obix:WatchOut">
1775 <list name="values" of="obix:obj"/>
1776 </obj>
1777 Many of the Watch operations use two Contracts: obix:WatchIn and obix:WatchOut. The Client
1778 identifies Objects to add and remove from the poll list via WatchIn. This Object contains a list of URIs.
1779 Typically these URIs SHOULD be Server relative.
1780 The Server responds to add, pollChanges, and pollRefresh operations via the WatchOut Contract.
1781 This Object contains the list of subscribed Objects - each Object MUST specify an href URI using the
1782 exact same string as the URI identified by the Client in the corresponding WatchIn. Servers MUST NOT
1783 perform any case conversions or normalization on the URI passed by the Client. This allows Client
1784 software to use the URI string as a hash key to match up Server responses.

1785 12.4.1 Watch.add

1786 Once a Watch has been created, the Client can add new Objects to the Watch using the add operation.
1787 The Objects returned are REQUIRED to specify an href using the exact string representation input by the
1788 Client. If any Object cannot be processed, then a partial failure SHOULD be expressed by returning an
1789 err Object with the respective href. Subsequent URIs MUST NOT be affected by the failure of one
1790 invalid URI. The add operation MUST never return Objects not explicitly included in the input URIs (even
1791 if there are already existing Objects in the watch list). No guarantee is made that the order of Objects in
1792 WatchOut matches the order in of URIs in WatchIn – Clients must use the URI as a key for matching.
1793 Note that the URIs supplied via WatchIn may include an optional in parameter. This parameter is only
1794 used when subscribing a Watch to a feed Object. Feeds also differ from other Objects in that they return
1795 a list of historic events in WatchOut. Feeds are discussed in detail in Section12.6.
1796 It is invalid to add an op’s href to a Watch; the Server MUST report an err.
1797 If an attempt is made to add a URI to a Watch which was previously already added, then the Server
1798 SHOULD return the current Object’s value in the WatchOut result, but treat poll operations as if the URI
1799 was only added once – polls SHOULD only return the Object once. If an attempt is made to add the same
1800 URI multiple times in the same WatchIn request, then the Server SHOULD only return the Object once.

1801 12.4.1.1 Watch Object URIs

1802 The lack of a trailing slash in watched Object URIs can cause problems with Watches. Consider a Client
1803 which adds a URI to a Watch without a trailing slash. The Client will use this URI as a key in its local
1804 hashtable for the Watch. Therefore the Server MUST use the URI exactly as the Client specified.
1805 However, if the Object’s extent includes child Objects they will not be able to use relative URIs. It is
1806 RECOMMENDED that Servers fail fast in these cases and return a BadUriErr when Clients attempt to
1807 add a URI without a trailing slash to a Watch (even though they may allow it for a normal read request).

1808 12.4.2 Watch.remove

1809 The Client can remove Objects from the watch list using the remove operation. A list of URIs is input to
1810 remove, and the Nil Object is returned. Subsequent pollChanges and pollRefresh operations MUST
1811 cease to include the specified URIs. It is possible to remove every URI in the watch list; but this scenario
1812 MUST NOT automatically free the Watch, rather normal poll and lease rules still apply. It is invalid to use
1813 the WatchInItem.in parameter for a remove operation.

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 57 of 79
1814 12.4.3 Watch.pollChanges
1815 Clients SHOULD periodically poll the Server using the pollChanges operation. This operation returns a
1816 list of the subscribed Objects which have changed. Servers SHOULD only return the Objects which have
1817 been modified since the last poll request for the specific Watch. As with add, every Object MUST specify
1818 an href using the exact same string representation the Client passed in the original add operation. The
1819 entire extent of the Object SHOULD be returned to the Client if any one thing inside the extent has
1820 changed on the Server side.
1821 Invalid URIs MUST never be included in the response (only in add and pollRefresh). An exception to
1822 this rule is when an Object which is valid is removed from the URI space. Servers SHOULD indicate an
1823 Object has been removed via an err with the BadUriErr Contract.

1824 12.4.4 Watch.pollRefresh

1825 The pollRefresh operation forces an update of every Object in the watch list. The Server MUST return
1826 every Object and its full extent in the response using the href with the exact same string representation
1827 passed by the Client in the original add. Invalid URIs in the poll list SHOULD be included in the response
1828 as an err element. A pollRefresh resets the poll state of every Object, so that the next pollChanges
1829 only returns Objects which have changed state since the pollRefresh invocation.

1830 12.4.5 Watch.lease

1831 All Watches have a lease time, specified by the lease child. If the lease time elapses without the Client
1832 initiating a request on the Watch, and the Watch is a Client-polled Watch, then the Server MAY expire the
1833 Watch. Every new poll request resets the lease timer. So as long as the Client polls at least as often as
1834 the lease time, the Server SHOULD maintain the Watch. The following requests SHOULD reset the lease
1835 timer: read of the Watch URI itself or invocation of the add, remove, pollChanges, or pollRefresh
1836 operations.
1837 Clients may request a different lease time by writing to the lease Object (requires Servers to assign an
1838 href to the lease child). The Server is free to honor the request, cap the lease within a specific range, or
1839 ignore the request. In all cases the write request will return a response containing the new lease time in
1840 effect.
1841 Servers SHOULD report expired Watches by returning an err Object with the BadUriErr Contract. As a
1842 general principle Servers SHOULD honor Watches until the lease runs out (for Client-polled Watches) or
1843 the Client explicitly invokes delete. However, Servers are free to cancel Watches as needed (such as
1844 power failure) and the burden is on Clients to re-establish a new Watch.

1845 12.4.6 Watch.delete

1846 The delete operation can be used to cancel an existing Watch. Clients SHOULD always delete their
1847 Watch when possible to be good OBIX citizens. However Servers MUST always cleanup correctly without
1848 an explicit delete when the lease expires or the session is terminated.

1849 12.5 Watch Depth

1850 When a Watch is put on an Object which itself has child Objects, how does a Client know how “deep” the
1851 subscription goes? OBIX requires Watch depth to match an Object‘s extent (see Section 9.3). When a
1852 Watch is put on a target Object, a Server MUST notify the Client of any changes to any of the Objects
1853 within that target Object’s extent. If the extent includes feed Objects, they are not included in the Watch
1854 – Feeds have special Watch semantics discussed in Section 12.6. This means a Watch is inclusive of all
1855 descendents within the extent except refs and feeds.

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 58 of 79
1856 12.6 Feeds
1857 Servers may expose event streams using the feed Object. The event instances are typed via the Feed’s
1858 of attribute. Clients subscribe to events by adding the Feed’s href to a Watch, optionally passing an input
1859 parameter which is typed via the Feed’s in attribute. The Object returned from Watch.add is a list of
1860 historic events (or the empty list if no event history is available). Subsequent calls to pollChanges return
1861 the list of events which have occurred since the last poll.
1862 Let’s consider a simple example for an Object which fires an event when its geographic location changes:
1863 <obj href="/car/">
1864 <feed href="moved" of="/def/Coordinate"/>
1865 <obj>
1866
1867 <obj href="/def/Coordinate">
1868 <real name="lat"/>
1869 <real name="long"/>
1870 </obj>
1871 The Client subscribes to the moved event Feed by adding “/car/moved” to a Watch. The WatchOut will
1872 include the list of any historic events which have occurred up to this point in time. If the Server does not
1873 maintain an event history this list will be empty:
1874 <obj is="obix:WatchIn">
1875 <list name="hrefs">
1876 <uri val="/car/moved" />
1877 </list>
1878 </obj>
1879
1880 <obj is="obix:WatchOut">
1881 <list name="values">
1882 <feed href="/car/moved" of="/def/Coordinate/" /> <!-- empty history -->
1883 </list>
1884 </obj>
1885 Now every time the Client pollChanges for the Watch, the Server will return the list of event instances
1886 which have accumulated since the last poll:
1887 <obj is="obix:WatchOut">
1888 <list name="values">
1889 <feed href="/car/moved" of="/def/Coordinate">
1890 <obj>
1891 <real name="lat" val="37.645022"/>
1892 <real name="long" val="-77.575851"/>
1893 </obj>
1894 <obj>
1895 <real name="lat" val="37.639046"/>
1896 <real name="long" val="-77.61872"/>
1897 </obj>
1898 </feed>
1899 </list>
1900 </obj>
1901 Note the Feed’s of attribute works just like the list’s of attribute. The children event instances are
1902 assumed to inherit the Contract defined by of unless explicitly overridden. If an event instance does
1903 override the of Contract, then it MUST be Contract compatible. Refer to the rules defined in Section 7.8.
1904 Invoking a pollRefresh operation on a Watch with a Feed that has an event history, SHOULD return all
1905 the historical events as if the pollRefresh was an add operation. If an event history is not available,
1906 then pollRefresh SHOULD act like a normal pollChanges and just return the events which have
1907 occurred since the last poll.

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 59 of 79
1908 13 Points
1909 Anyone familiar with automation systems immediately identifies with the term Point (sometimes called
1910 tags in the industrial space). Although there are many different definitions, generally points map directly to
1911 a sensor or actuator (called Hard Points). Sometimes a Point is mapped to a configuration variable such
1912 as a software setpoint (called Soft Points). In some systems Point is an atomic value, and in others it
1913 encapsulates a great deal of status and configuration information.
1914 OBIX allows an integrator to normalize the representation of Points without forcing an impedance
1915 mismatch on implementers trying to make their native system OBIX accessible. To meet this requirement,
1916 OBIX defines a low level abstraction for Point - simply one of the primitive value types with associated
1917 status information. Point is basically just a marker Contract used to tag an Object as exhibiting “Point”
1918 semantics:
1919 <obj href="obix:Point"/>
1920 This Contract MUST only be used with the value primitive types: bool, real, enum, str, abstime, and
1921 reltime. Points SHOULD use the status attribute to convey quality information. This Table specifies
1922 how to map common control system semantics to a value type:

Point type OBIX Object Example

digital Point bool <bool is="obix:Point" val="true"/>

analog Point real <real is="obix:Point" val="22"

unit="obix:units/celsius"/>

multi-state Point enum <enum is="obix:Point" val="slow"/>

1923 Table 13-1. Base Point types.

1924 13.1 Writable Points

1925 Different control systems handle Point writes using a wide variety of semantics. Sometimes a Client
1926 desires to write a Point at a specific priority level. Sometimes the Client needs to override a Point for a
1927 limited period of time, after which the Point falls back to a default value. The OBIX specification does not
1928 attempt to impose a specific model on implementers. Rather OBIX provides a standard WritablePoint
1929 Contract which may be extended with additional mixins to handle special cases. WritablePoint
1930 defines write as an operation which takes a WritePointIn structure containing the value to write. The
1931 Contracts are:
1932 <obj href="obix:WritablePoint" is="obix:Point">
1933 <op name="writePoint" in="obix:WritePointIn" out="obix:Point"/>
1934 </obj>
1935
1936 <obj href="obix:WritePointIn">
1937 <obj name="value"/>
1938 </obj>
1939
1940 It is implied that the value passed to writePoint MUST match the type of the Point. For example if
1941 WritablePoint is used with an enum, then writePoint MUST pass an enum for the value.

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 60 of 79
1942 14 History
1943 Most automation systems have the ability to persist periodic samples of point data to create a historical
1944 archive of a point’s value over time. This feature goes by many names including logs, trends, or histories.
1945 In OBIX, a history is defined as a list of time stamped point values. The following features are provided by
1946 OBIX histories:
History Object A normalized representation for a history itself

History Record A record of a point sampling at a specific timestamp

History Query A standard way to query history data as Points
History Rollup A standard mechanism to do basic rollups of history data

History Append The ability to push new history records into a history

1947 Table 14-1. Features of OBIX Histories.

1948 14.1 History Object

1949 Any Object which wishes to expose itself as a standard OBIX history implements the obix:History
1950 Contract:
1951 <obj href="obix:History">
1952 <int name="count" min="0" val="0"/>
1953 <abstime name="start" null="true"/>
1954 <abstime name="end" null="true"/>
1955 <str name="tz" null="true"/>
1956 <obj name="prototype" null="true"/>
1957 <enum name="collectMode" null=true" range="obix:HistoryCollectMode"/>
1958 <list name="formats" of="obix:str" null="true"/>
1959 <op name="query" in="obix:HistoryFilter" out="obix:HistoryQueryOut"/>
1960 <feed name="feed" in="obix:HistoryFilter" of="obix:HistoryRecord"/>
1961 <op name="rollup" in="obix:HistoryRollupIn" out="obix:HistoryRollupOut"/>
1962 <op name="append" in="obix:HistoryAppendIn" out="obix:HistoryAppendOut"/>
1963 </obj>
1964
1965 <list href="obix:HistoryCollectMode" is="obix:Range">
1966 <obj name="interval" displayName="Interval"/>
1967 <obj name="cov" displayName="Change of Value"/>
1968 <obj name="triggered" displayName="Triggered"/>
1969 </list>
1970 The child properties of obix:History are:
1971
Property Description
count The number of history records contained by the history
start Provides the timestamp of the oldest record. The timezone of this abstime MUST
match History.tz
end Provides the timestamp of the newest record. The timezone of this abstime MUST
match History.tz
tz A standardized timezone identifier for the history data (see Section 4.2.7.9)
prototype An object of the form of each history record, identifying the type and any Facets
applicable to the records (such as units).

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 61 of 79
 collectMode Indicates the mechanism for how the history records are collected. Servers
SHOULD provide this field, if it is known, so Client applications can make
appropriate decisions about how to use records in calculations, such as
interpolation.
formats Provides a list of strings describing the formats in which the Server can provide
the history data
query The operation used to query the history to read history records
feed The object used to subscribe to a real-time Feed of history records
rollup The operation used to perform history rollups (it is only supported for numeric
history data)
append The operation used to push new history records into the history

1972 Table 14-2. Properties of obix:History.

1973 An example of a history which contains an hour of 15 minute temperature data:
1974 <obj href="http://x/outsideAirTemp/history/" is="obix:History">
1975 <int name="count" val="5"/>
1976 <abstime name="start" val="2005-03-16T14:00:00-05:00" tz="America/New_York"/>
1977 <abstime name="end" val="2005-03-16T15:00:00-05:00" tz="America/New_York"/>
1978 <str name="tz" val="America/New_York"/>
1979 <list name="formats" of="obix:str">
1980 <str val="text/csv"/>
1981 </list>
1982 <op name="query" href="query"/>
1983 <op name="rollup" href="rollup"/>
1984 </obj>

1985 14.1.1 History prototype

1986 The prototype property of a History SHOULD be included by the Server when the records collected are
1987 identical in their composition. For example, when every record in the History contains a timestamp in the
1988 America/New_York time zone, and a floating point value reported in units of degrees Fahrenheit, the
1989 Server SHOULD include the prototype in its History object as follows:
1990 <obj is="obix:History">
1991 <int name="count" val="100"/>
1992 <abstime name="start" val="2005-03-16T14:00:00-05:00" tz="America/New_York"/>
1993 <abstime name="end" val="2005-03-16T15:00:00-05:00" tz="America/New_York"/>
1994 <str name="tz" val="America/New_York"/>
1995 <obj name="prototype" is="obix:HistoryRecord">
1996 <abstime name="timestamp" tz="America/New_York"/>
1997 <real name="value" unit="obix:units/fahrenheit"/>
1998 </obj>
1999 <op name="query" href="query"/>
2000 <op name="rollup" href="rollup"/>
2001 </obj>

2002 14.2 History Queries

2003 Every History Object contains a query operation to query the historical data. A Client MAY invoke the
2004 query operation to request the data from the Server as an obix:HistoryQueryOut. Alternatively, if
2005 the Server is able to provide the data in a different format, such as CSV, it SHOULD list these additionally
2006 supported formats in the formats field. A Client MAY then supply one of these defined formats in the
2007 HistoryFilter input query.

2008 14.2.1 HistoryFilter

2009 The History.query input Contract:
2010 <obj href="obix:HistoryFilter">
obix-v1.1-cs01 14 September 2015
Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 62 of 79
2011 <int name="limit" null="true"/>
2012 <abstime name="start" null="true"/>
2013 <abstime name="end" null="true"/>
2014 <str name="format" null="true"/>
2015 </obj>
2016 These fields are described in detail in this Table:
Field Description
limit An integer indicating the maximum number of records to return. Clients can use this field to
throttle the amount of data returned by making it non-null. Servers MUST never return more
records than the specified limit. However Servers are free to return fewer records than the
limit.
start If non-null this field indicates an inclusive lower bound for the query’s time range. This value
SHOULD match the history’s timezone, otherwise the Server MUST normalize based on
absolute time.
end If non-null this field indicates an inclusive upper bound for the query’s time range. This value
SHOULD match the history’s timezone, otherwise the Server MUST normalize based on
absolute time.
format If non-null this field indicates the format that the Client is requesting for the returned data. If
the Client uses this field the Server MUST return a HistoryQueryOut with a non-null
dataRef URI, or return an error if it is unable to supply the requested format. A Client
SHOULD use one of the formats defined in the History’s formats field when using this field
in the filter.

2017 Table 14-3. Properties of obix:HistoryFilter.

2018 14.2.2 HistoryQueryOut

2019 The History.query output Contract:
2020 <obj href="obix:HistoryQueryOut">
2021 <int name="count" min="0" val="0"/>
2022 <abstime name="start" null="true"/>
2023 <abstime name="end" null="true"/>
2024 <list name="data" of="obix:HistoryRecord" null="true"/>
2025 <uri name="dataRef" null="true"/>
2026 </obj>
2027 Just like History, every HistoryQueryOut returns count, start, and end. But unlike History,
2028 these values are for the query result, not the entire history. The actual history data is stored as a list of
2029 HistoryRecords in the data field. Remember that child order is not guaranteed in OBIX, therefore it
2030 might be common to have count after data. The start, end, and data HistoryRecord timestamps MUST
2031 have a timezone which matches History.tz.
2032 When using a Client-requested format, the Server MUST provide a URI that can be followed by the Client
2033 to obtain the history data in the alternate format. The exact definition of this format is out of scope of this
2034 specification, but SHOULD be agreed upon by both the Client and Server.

2035 14.2.3 HistoryRecord

2036 The HistoryRecord Contract specifies a record in a history query result:
2037 <obj href="obix:HistoryRecord">
2038 <abstime name="timestamp" null="true"/>
2039 <obj name="value" null="true"/>
2040 </obj>
2041 Typically the value SHOULD be one of the value types used with obix:Point.

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 63 of 79
2042 14.2.4 History Query Examples
2043 Consider an example query from the “/outsideAirTemp/history” example above.

2044 14.2.4.1 History Query as OBIX Objects

2045 First examine how a Client and Server interact using the standard history query mechanism:
2046 Client invoke request:
2047 INVOKE http://x/outsideAirTemp/history/query
2048 <obj name="in" is="obix:HistoryFilter">
2049 <int name="limit" val="5"/>
2050 <abstime name="start" val="2005-03-16T14:00:00-05:00" tz="America/New_York"/>
2051 </obj>
2052 Server response:
2053 <obj href="http://x/outsideAirTemp/history/query" is="obix:HistoryQueryOut">
2054 <int name="count" val="5"/>
2055 <abstime name="start" val="2005-03-16T14:00:00-05:00" tz="America/New_York"/>
2056 <abstime name="end" val="2005-03-16T15:00:00-05:00" tz="America/New_York"/>
2057 <reltime name="interval" val="PT15M"/>
2058 <list name="data" of="#RecordDef obix:HistoryRecord">
2059 <obj> <abstime name="timestamp" val="2005-03-16T14:00:00-05:00"/>
2060 <real name="value" val="40"/> </obj>
2061 <obj> <abstime name="timestamp" val="2005-03-16T14:15:00-05:00"/>
2062 <real name="value" val="42"/> </obj>
2063 <obj> <abstime name="timestamp" val="2005-03-16T14:30:00-05:00"/>
2064 <real name="value" val="43"/> </obj>
2065 <obj> <abstime name="timestamp" val="2005-03-16T14:45:00-05:00"/>
2066 <real name="value" val="47"/> </obj>
2067 <obj> <abstime name="timestamp" val="2005-03-16T15:00:00-05:00"/>
2068 <real name="value" val="44"/> </obj>
2069 </list>
2070 <obj href="#RecordDef" is="obix:HistoryRecord">
2071 <abstime name="timestamp" tz="America/New_York"/>
2072 <real name="value" unit="obix:units/fahrenheit"/>
2073 </obj>
2074 </obj>
2075 Note in the example above how the data list uses a document local Contract to define Facets common to
2076 all the records (although the Contract List must still be flattened).

2077 14.2.4.2 History Query as Preformatted List

2078 Now consider how this might be done in a more compact format. The Server in this case is able to return
2079 the history data as a CSV list.
2080 Client invoke request:
2081 INVOKE http://myServer/obix/outsideAirTemp/history/query
2082 <obj name="in" is="obix:HistoryFilter">
2083 <int name="limit" val="5"/>
2084 <abstime name="start" val="2005-03-16T14:00:00-05:00" tz="America/New_York"/>
2085 <str name="format" val="text/csv"/>
2086 </obj>
2087 Server response:
2088 <obj href="http://myServer/obix/outsideAirTemp/history/query" is="obix:HistoryQueryOut">
2089 <int name="count" val="5"/>
2090 <abstime name="start" val="2005-03-16T14:00:00-05:00" tz="America/New_York"/>
2091 <abstime name="end" val="2005-03-16T15:00:00-05:00" tz="America/New_York"/>
2092 <uri name="dataRef" val="http://x/outsideAirTemp/history/query?text/csv"/>
2093 </obj>
2094
2095 Client then reads the dataRef URI:
2096 GET http://x/outsideAirTemp/history/query?text/csv
2097 Server response:
2098 2005-03-16T14:00:00-05:00,40

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 64 of 79
2099 2005-03-16T14:15:00-05:00,42
2100 2005-03-16T14:30:00-05:00,43
2101 2005-03-16T14:45:00-05:00,47
2102 2005-03-16T15:00:00-05:00,44
2103 Note that the Client’s second request is NOT an OBIX request, and the subsequent Server response is
2104 NOT an OBIX document, but just arbitrarily formatted data as requested by the Client – in this case
2105 text/csv. Also it is important to note that this is simply an example. While the usage of the format and
2106 dataRef properties is normative, the usage of the text/csv MIME type and how the data is actually
2107 presented is purely non-normative. It is not intended to suggest CSV as a mechanism for how the data
2108 should be formatted, as that is an agreement to be made between the Client and Server. The Server and
2109 Client are free to use any agreed-upon format, for example, one where the timestamps are inferred rather
2110 than repeated, for maximum brevity.

2111 14.3 History Rollups

2112 Control systems collect historical data as raw time sampled values. However, most applications wish to
2113 consume historical data in a summarized form which are called rollups. The rollup operation is used to
2114 summarize an interval of time. History rollups only apply to histories which store numeric information.
2115 Attempting to query a rollup on a non-numeric history SHOULD result in an error.

2116 14.3.1 HistoryRollupIn

2117 The History.rollup input Contract extends HistoryFilter to add an interval parameter:
2118 <obj href="obix:HistoryRollupIn" is="obix:HistoryFilter">
2119 <reltime name="interval"/>
2120 </obj>

2121 14.3.2 HistoryRollupOut

2122 The History.rollup output Contract:
2123 <obj href="obix:HistoryRollupOut">
2124 <int name="count" min="0" val="0"/>
2125 <abstime name="start" null="true"/>
2126 <abstime name="end" null="true"/>
2127 <list name="data" of="obix:HistoryRollupRecord"/>
2128 </obj>
2129 The HistoryRollupOut Object looks very much like HistoryQueryOut except it returns a list of
2130 HistoryRollupRecords, rather than HistoryRecords. Note: unlike HistoryQueryOut, the start
2131 for HistoryRollupOut is exclusive, not inclusive. This issue is discussed in greater detail next. The
2132 start, end, and data HistoryRollupRecord timestamps MUST have a timezone which matches
2133 History.tz.

2134 14.3.3 HistoryRollupRecord

2135 A history rollup returns a list of HistoryRollupRecords:
2136 <obj href="obix:HistoryRollupRecord">
2137 <abstime name="start"/>
2138 <abstime name="end" />
2139 <int name="count"/>
2140 <real name="min" />
2141 <real name="max" />
2142 <real name="avg" />
2143 <real name="sum" />
2144 </obj>
2145 The children are defined in the Table below:
Property Description
start The exclusive start time of the record’s rollup interval

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 65 of 79
 end The inclusive end time of the record’s rollup interval
count The number of records used to compute this rollup interval
min The minimum value of all the records within the interval
max The maximum value of all the records within the interval
avg The arithmetic mean of all the values within the interval
sum The summation of all the values within the interval

2146 Table 14-4. Properties of obix:HistoryRollupRecord.

2147 14.3.4 Rollup Calculation

2148 The best way to understand how rollup calculations work is through an example. Let’s consider a history
2149 of meter data which contains two hours of 15 minute readings of kilowatt values:
2150 <obj is="obix:HistoryQueryOut">
2151 <int name="count" val="9">
2152 <abstime name="start" val="2005-03-16T12:00:00+04:00" tz="Asia/Dubai"/>
2153 <abstime name="end" val="2005-03-16T14:00:00+04:00" tz="Asia/Dubai"/>
2154 <list name="data" of="#HistoryDef obix:HistoryRecord">
2155 <obj> <abstime name="timestamp" val="2005-03-16T12:00:00+04:00"/>
2156 <real name="value" val="80"> </obj>
2157 <obj> <abstime name="timestamp" val="2005-03-16T12:15:00+04:00"/>
2158 <real name="value" val="82"></obj>
2159 <obj> <abstime name="timestamp" val="2005-03-16T12:30:00+04:00"/>
2160 <real name="value" val="90"> </obj>
2161 <obj> <abstime name="timestamp" val="2005-03-16T12:45:00+04:00"/>
2162 <real name="value" val="85"> </obj>
2163 <obj> <abstime name="timestamp" val="2005-03-16T13:00:00+04:00"/>
2164 <real name="value" val="81"> </obj>
2165 <obj> <abstime name="timestamp" val="2005-03-16T13:15:00+04:00"/>
2166 <real name="value" val="84"> </obj>
2167 <obj> <abstime name="timestamp" val="2005-03-16T13:30:00+04:00"/>
2168 <real name="value" val="91"> </obj>
2169 <obj> <abstime name="timestamp" val="2005-03-16T13:45:00+04:00"/>
2170 <real name="value" val="83"> </obj>
2171 <obj> <abstime name="timestamp" val="2005-03-16T14:00:00+04:00"/>
2172 <real name="value" val="78"> </obj>
2173 </list>
2174 <obj href="#HistoryRecord" is="obix:HistoryRecord">
2175 <abstime name="timestamp" tz="Asia/Dubai"/>
2176 <real name="value" unit="obix:units/kilowatt"/>
2177 <obj>
2178 </obj>
2179 For a query of the rollup using an interval of 1 hour with a start time of 12:00 and end time of 14:00, the
2180 result would be:
2181 <obj is="obix:HistoryRollupOut obix:HistoryQueryOut">
2182 <int name="count" val="2">
2183 <abstime name="start" val="2005-03-16T12:00:00+04:00 tz="Asia/Dubai"/>
2184 <abstime name="end" val="2005-03-16T14:00:00+04:00" tz="Asia/Dubai"/>
2185 <list name="data" of="obix:HistoryRollupRecord">
2186 <obj>
2187 <abstime name="start" val="2005-03-16T12:00:00+04:00"
2188 tz="Asia/Dubai"/>
2189 <abstime name="end" val="2005-03-16T13:00:00+04:00"
2190 tz="Asia/Dubai"/>
2191 <int name="count" val="4" />
2192 <real name="min" val="81" />
2193 <real name="max" val="90" />
2194 <real name="avg" val="84.5" />
2195 <real name="sum" val="338" />
2196 </obj>
2197 <obj>
2198 <abstime name="start" val="2005-03-16T13:00:00+04:00"

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 66 of 79
2199 tz="Asia/Dubai"/>
2200 <abstime name="end" val="2005-03-16T14:00:00+04:00"
2201 tz="Asia/Dubai"/>
2202 <int name="count" val="4" />
2203 <real name="min" val="78" />
2204 <real name="max" val="91" />
2205 <real name="avg" val="84" />
2206 <real name="sum" val="336" />
2207 </obj>
2208 </list>
2209 </obj>
2210 The first item to notice is that the first raw record of 80kW was never used in the rollup. This is because
2211 start time is always exclusive. The reason start time has to be exclusive is because discrete samples are
2212 being summarized into a contiguous time range. It would be incorrect to include a record in two different
2213 rollup intervals! To avoid this problem, start time MUST always be exclusive and end time MUST always
2214 be inclusive. The following Table illustrates how the raw records were applied to rollup intervals:

Interval Start (exclusive) Interval End (inclusive) Records Included

2005-03-16T12:00 2005-03-16T13:00 82 + 90 + 85 + 81 = 338

2005-03-16T13:00 2005-03-16T14:00 84 + 91 + 83 + 78 = 336

2215 Table 14-5. Calculation of OBIX History rollup values.

2216 14.4 History Feeds

2217 The History Contract specifies a Feed for subscribing to a real-time Feed of the history records.
2218 History.feed reuses the same HistoryFilter input Contract used by History.query – the same
2219 semantics apply. When adding a History Feed to a Watch, the initial result SHOULD contain the list of
2220 HistoryRecords filtered by the input parameter (i.e., the initial result SHOULD match what
2221 History.query would return). Subsequent calls to Watch.pollChanges SHOULD return any new
2222 HistoryRecords which have been collected since the last poll that also satisfy the HistoryFilter.

2223 14.5 History Append

2224 The History.append operation allows a Client to push new HistoryRecords into a History log
2225 (assuming proper security credentials). This operation comes in handy when bi-direction HTTP
2226 connectivity is not available. For example if a device in the field is behind a firewall, it can still push history
2227 data on an interval basis to a Server using the append operation.

2228 14.5.1 HistoryAppendIn

2229 The History.append input Contract:
2230 <obj href="obix:HistoryAppendIn">
2231 <list name="data" of="obix:HistoryRecord"/>
2232 </obj>
2233 The HistoryAppendIn is a wrapper for the list of HistoryRecords to be inserted into the History. The
2234 HistoryRecords SHOULD use a timestamp which matches History.tz. If the timezone doesn’t
2235 match, then the Server MUST normalize to its configured timezone based on absolute time. The
2236 HistoryRecords in the data list MUST be sorted by timestamp from oldest to newest, and MUST not
2237 include a timestamp equal to or older than History.end.

2238 14.5.2 HistoryAppendOut

2239 The History.append output Contract:
2240 <obj href="obix:HistoryAppendOut">
2241 <int name="numAdded"/>
2242 <int name="newCount"/>
2243 <abstime name="newStart" null="true"/>

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 67 of 79
2244 <abstime name="newEnd" null="true"/>
2245 </obj>
2246 The output of the append operation returns the number of new records appended to the History and the
2247 new total count, start time, and end time of the entire History. The newStart and newEnd timestamps
2248 MUST have a timezone which matches History.tz.

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 68 of 79
2249 15 Alarms
2250 OBIX specifies a normalized model to query, Watch, and acknowledge alarms. In OBIX, an alarm
2251 indicates a condition which requires notification of either a user or another application. In many cases an
2252 alarm requires acknowledgement, indicating that someone (or something) has taken action to resolve the
2253 alarm condition. The typical lifecycle of an alarm is:
2254 1. Source Monitoring: Algorithms in a Server monitor an alarm source. An alarm source is an
2255 Object with an href which has the potential to generate an alarm. Example of alarm sources might
2256 include sensor points (this room is too hot), hardware problems (disk is full), or applications
2257 (building is consuming too much energy at current energy rates)
2258 2. Alarm Generation: If the algorithms in the Server detect that an alarm source has entered an
2259 alarm condition, then an alarm record is generated. Every alarm is uniquely identified using an
2260 href and represented using the obix:Alarm Contract. The transition to an alarm state is called
2261 off-normal.
2262 3. To Normal: Many alarm sources are said to be stateful - eventually the alarm source exits the
2263 alarm state, and is said to return to-normal. Stateful alarms implement the
2264 obix:StatefulAlarm Contract. When the alarm source transitions to normal, the alarm’s
2265 normalTimestamp is updated.
2266 4. Acknowledgement: A common requirement for alarming is that a user or application
2267 acknowledges that they have processed an alarm. These alarms implement the
2268 obix:AckAlarm Contract. When the alarm is acknowledged, the alarm’s ackTimestamp and
2269 ackUser are updated.

2270 15.1 Alarm States

2271 Alarm state is summarized with two variables:
In Alarm Is the alarm source currently in the alarm condition or in the normal
condition? This variable maps to the alarm status state.

Acknowledged Is the alarm acknowledged or unacknowledged? This variable maps to the

unacked status state.

2272 Table 15-1. Alarm states in OBIX.

2273 Either of these states may transition independent of the other. For example an alarm source can return to
2274 normal before or after an alarm has been acknowledged. Furthermore it is not uncommon to transition
2275 between normal and off-normal multiple times generating several alarm records before any
2276 acknowledgements occur.
2277 Note not all alarms have state. An alarm which implements neither StatefulAlarm nor the AckAlarm
2278 Contracts is completely stateless – these alarms merely represent event. An alarm which implements
2279 StatefulAlarm but not AckAlarm will have an in-alarm state, but not acknowledgement state.
2280 Conversely an alarm which implements AckAlarm but not StatefulAlarm will have an
2281 acknowledgement state, but not in-alarm state.

2282 15.1.1 Alarm Source

2283 The current alarm state of an alarm source is represented using the status attribute. This attribute is
2284 discussed in Section 4.2.7.8. It is recommended that alarm sources always report their status via the
2285 status attribute.

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 69 of 79
2286 15.1.2 StatefulAlarm and AckAlarm
2287 An Alarm record is used to summarize the entire lifecycle of an alarm event. If the alarm implements
2288 StatefulAlarm it tracks transition from off-normal back to normal. If the alarm implements AckAlarm,
2289 then it also summarizes the acknowledgement. This allows for four discrete alarm states, which are
2290 described in terms of the alarm Contract properties:
Alarm State alarm acked normalTimestamp ackTimestamp

new unacked alarm true false null null

acknowledged alarm true true null non-null

unacked returned alarm false false non-null null

acked returned alarm false true non-null non-null

2291 Table 15-2. Alarm lifecycle states in OBIX.

2292 15.2 Alarm Contracts

2293 15.2.1 Alarm
2294 The core Alarm Contract is:
2295 <obj href="obix:Alarm">
2296 <ref name="source"/>
2297 <abstime name="timestamp"/>
2298 </obj>
2299
2300 The child Objects are:
2301  source: the URI which identifies the alarm source. The source SHOULD reference an OBIX
2302 Object which models the entity that generated the alarm.
2303  timestamp: this is the time at which the alarm source transitioned from normal to off-normal and
2304 the Alarm record was created.

2305 15.2.2 StatefulAlarm

2306 Alarms which represent an alarm state which may transition back to normal SHOULD implement the
2307 StatefulAlarm Contract:
2308 <obj href="obix:StatefulAlarm" is="obix:Alarm">
2309 <abstime name="normalTimestamp" null="true"/>
2310 </obj>
2311 The child Object is:
2312  normalTimestamp: if the alarm source is still in the alarm condition, then this field is null.
2313 Otherwise this indicates the time of the transition back to the normal condition.

2314 15.2.3 AckAlarm

2315 Alarms which support acknowledgment SHOULD implement the AckAlarm Contract:
2316 <obj href="obix:AckAlarm" is="obix:Alarm">
2317 <abstime name="ackTimestamp" null="true"/>
2318 <str name="ackUser" null="true"/>
2319 <op name="ack" in="obix:AckAlarmIn" out="obix:AckAlarmOut"/>
2320 </obj>
2321
2322 <obj href="obix:AckAlarmIn">
2323 <str name="ackUser" null="true"/>
2324 </obj>
2325
2326 <obj href="obix:AckAlarmOut">

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 70 of 79
2327 <obj name="alarm" is="obix:AckAlarm obix:Alarm"/>
2328 </obj>
2329 The child Objects are:
2330  ackTimestamp: if the alarm is unacknowledged, then this field is null. Otherwise this indicates
2331 the time of the acknowledgement.
2332  ackUser: if the alarm is unacknowledged, then this field is null. Otherwise this field SHOULD
2333 provide a string indicating who was responsible for the acknowledgement.
2334 The ack operation is used to programmatically acknowledge the alarm. The Client may optionally specify
2335 an ackUser string via AckAlarmIn. However, the Server is free to ignore this field depending on
2336 security conditions. For example a highly trusted Client may be allowed to specify its own ackUser, but a
2337 less trustworthy Client may have its ackUser predefined based on the authentication credentials of the
2338 protocol binding. The ack operation returns an AckAlarmOut which contains the updated alarm record.
2339 Use the Lobby.batch operation to efficiently acknowledge a set of alarms.

2340 15.2.4 PointAlarms

2341 It is very common for an alarm source to be an obix:Point. The PointAlarm Contract provides a
2342 normalized way to report the Point whose value caused the alarm condition:
2343 <obj href="obix:PointAlarm" is="obix:Alarm">
2344 <obj name="alarmValue"/>
2345 </obj>
2346 The alarmValue Object SHOULD be one of the value types defined for obix:Point in Section 13.

2347 15.3 AlarmSubject

2348 Servers which implement OBIX alarming MUST provide one or more Objects which implement the
2349 AlarmSubject Contract. The AlarmSubject Contract provides the ability to categorize and group the
2350 sets of alarms a Client may discover, query, and watch. For instance a Server could provide one
2351 AlarmSubject for all alarms and other AlarmSubjects based on priority or time of day. The Contract
2352 for AlarmSubject is:
2353 <obj href="obix:AlarmSubject">
2354 <int name="count" min="0" val="0"/>
2355 <op name="query" in="obix:AlarmFilter" out="obix:AlarmQueryOut"/>
2356 <feed name="feed" in="obix:AlarmFilter" of="obix:Alarm"/>
2357 </obj>
2358
2359 <obj href="obix:AlarmFilter">
2360 <int name="limit" null="true"/>
2361 <abstime name="start" null="true"/>
2362 <abstime name="end" null="true"/>
2363 </obj>
2364
2365 <obj href="obix:AlarmQueryOut">
2366 <int name="count" min="0" val="0"/>
2367 <abstime name="start" null="true"/>
2368 <abstime name="end" null="true"/>
2369 <list name="data" of="obix:Alarm"/>
2370 </obj>
2371 The AlarmSubject follows the same design pattern as History. The AlarmSubject specifies the
2372 active count of alarms; however, unlike History it does not provide the start and end bounding
2373 timestamps. It contains a query operation to read the current list of alarms with an AlarmFilter to filter
2374 by time bounds. AlarmSubject also contains a Feed Object which may be used to subscribe to the
2375 alarm events.

2376 15.4 Alarm Feed Example

2377 The following example illustrates how a Feed works with this AlarmSubject:
2378 <obj is="obix:AlarmSubject" href="/alarms/">
2379 <int name="count" val="2"/>

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 71 of 79
2380 <op name="query" href="query"/>
2381 <feed name="feed" href="feed" />
2382 </obj>
2383 The Server indicates it has two open alarms under the specified AlarmSubject. If a Client were to add the
2384 AlarmSubject’s Feed to a watch:
2385 <obj is="obix:WatchIn">
2386 <list name="hrefs"/>
2387 <uri val="/alarms/feed">
2388 <obj name="in" is="obix:AlarmFilter">
2389 <int name="limit" val="25"/>
2390 </obj>
2391 </uri>
2392 </list>
2393 </obj>
2394
2395 <obj is="obix:WatchOut">
2396 <list name="values">
2397 <feed href="/alarms/feed" of="obix:Alarm">
2398 <obj href="/alarmdb/528" is="obix:StatefulAlarm obix:PointAlarm obix:Alarm">
2399 <ref name="source" href="/airHandlers/2/returnTemp"/>
2400 <abstime name="timestamp" val="2006-05-18T14:20:00Z"/>
2401 <abstime name="normalTimestamp" null="true"/>
2402 <real name="alarmValue" val="80.2"/>
2403 </obj>
2404 <obj href="/alarmdb/527" is="obix:StatefulAlarm obix:PointAlarm obix:Alarm">
2405 <ref name="source" href="/doors/frontDoor"/>
2406 <abstime name="timestamp" val="2006-05-18T14:18:00Z"/>
2407 <abstime name=" normalTimestamp" null="true"/>
2408 <real name="alarmValue" val="true"/>
2409 </obj>
2410 </feed>
2411 </list>
2412 </obj>
2413 The Watch returns the historic list of alarm events which is two open alarms. The first alarm indicates an
2414 out of bounds condition in AirHandler-2’s return temperature. The second alarm indicates that the system
2415 has detected that the front door has been propped open.
2416 The system next detects that the front door is closed, and the alarm point transitions to the normal state.
2417 When the Client next polls the Watch the alarm would be included in the Feed list (along with any
2418 additional changes or new alarms not shown here):
2419 <obj is="obix:WatchOut">
2420 <list name="values">
2421 <feed href="/alarms/feed" of="obix:Alarm">>
2422 <obj href="/alarmdb/527" is="obix:StatefulAlarm obix:PointAlarm obix:Alarm">
2423 <ref name="source" href="/doors/frontDoor"/>
2424 <abstime name="timestamp" val="2006-05-18T14:18:00Z"/>
2425 <abstime name=" normalTimestamp" val="2006-05-18T14:45:00Z"/>
2426 <real name="alarmValue" val="true"/>
2427 </obj>
2428 </feed>
2429 </list>
2430 </obj>

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 72 of 79
2431 16 Security
2432 Security is a broad topic that covers many issues. Some of the main concepts are listed below:
Authentication Verifying a user (Client) is who they claim to be
Encryption Protecting OBIX documents from viewing by unauthorized entities
Permissions Checking a user’s permissions before granting access to read/write Objects or
invoke operations

User Management Managing user accounts and permissions levels

2433 Table 16-1. Security concepts for OBIX.

2434 OBIX does not define security protocols or security methods. Security is dependent upon the business
2435 process, the value of the data, the encoding used, and other issues that are out of scope for this
2436 specification. OBIX supports composition with any number of security approaches and technologies. User
2437 authentication and authorization are left to the implementer. The type and depth of encryption are
2438 dependent upon the bindings and transport protocols used. Although it is possible to define contracts for
2439 user management through OBIX, this committee does not define any standard Contracts for user
2440 management.
2441 OBIX does define the messages used to report errors in security or in authentication. OBIX further
2442 defines how security is inherited within the hierarchy of a system. OBIX further makes a number of
2443 statements throughout this specification of areas or conditions wherein practitioners should consider
2444 carefully the security effects of their decisions.

2445 16.1 Error Handling

2446 It is expected that an OBIX Server will perform authentication and utilize those user credentials for
2447 checking permissions before processing read, write, and invoke requests. As a general rule, Servers
2448 SHOULD return err with the obix:PermissionErr Contract to indicate a Client lacks the permission
2449 to perform a request. In particularly sensitive applications, a Server may instead choose to return
2450 BadUriErr so that an untrustworthy Client is unaware that a specific object even exists.

2451 16.2 Permission-based Degradation

2452 Servers SHOULD strive to present their object model to a Client based on the privileges available to the
2453 Client. This behavior is called permission based degradation. The following rules summarize effective
2454 permission based degradation:
2455 1. If an Object cannot be read, then it SHOULD NOT be discoverable through Objects which are
2456 available.
2457 2. Servers SHOULD attempt to group standard Contracts within the same privilege level – for
2458 example don’t split obix:History’s start and end into two different security levels such that a
2459 Client might be able to read start, and not end.
2460 3. Servers SHOULD NOT include a Contract in an Object’s is attribute if the Contract’s children are
2461 not readable to the Client.
2462 4. If an Object isn’t writable, then the writable attribute SHOULD be set to false (either explicitly
2463 or through a Contract default).
2464 5. If an op inherited from a visible Contract cannot be invoked, then the Server SHOULD set the
2465 null attribute to true to disable it.

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 73 of 79
2466 17 Conformance
2467 17.1 Conditions for a Conforming OBIX Server
2468 An implementation conforms to this specification as an OBIX Server if it meets the conditions described in
2469 the following subsections. OBIX Servers MUST implement the OBIX Lobby Object.

2470 17.1.1 Lobby

2471 A conforming OBIX Server MUST meet all of the MUST and REQUIRED level requirements defined in
2472 Section 5 for the Lobby Object.

2473 17.1.2 Tag Spaces

2474 A conformant OBIX Server implementation MUST present any Tagspaces used according to the following
2475 rules, which are discussed in detail in Section 5.5.1:

2476 1. The Server MUST use the tagspaces element to declare any semantic model or tag dictionary it
2477 uses.
2478 2. The Server MUST use the name defined in the name attribute of the uri in the tagspaces Lobby
2479 element when referencing the Tagspace.
2480 3. The uri MUST contain a val that provides the reference location of the semantic model or tag
2481 dictionary.
2482 4. If available the version of the reference MUST be included as a child str element with name
2483 ‘version’, in the uri for that Tagspace.
2484 5. If the version is not available, the uri MUST contain a child abstime element with the name
2485 ‘retrievedAt’ and value containing the date when the dictionary used by the Server was retrieved
2486 from the publication source.

2487 17.1.3 Bindings

2488 A conformant OBIX Server implementation SHOULD support at least one of the standard bindings, which
2489 are defined in the companion specifications to this specification that describe OBIX Bindings. Any
2490 bindings used by the implementation MUST be listed in the Bindings section of the Server’s Lobby
2491 Object.

2492 17.1.4 Encodings

2493 A conformant OBIX Server implementation SHOULD support at least one of the encodings defined in the
2494 companion specification to this specification, [OBIX Encodings]. Any encodings used by the
2495 implementation MUST be listed in the Encodings section of the Server’s Lobby Object.
2496 An implementation MUST support negotiation of the encoding to be used with a Client according to the
2497 mechanism defined for the specific binding used. A conforming binding specification MUST specify how
2498 negotiation of the encoding to be used is performed. A conforming implementation MUST conform to the
2499 negotiation rules defined in the specification for each binding that it uses.
2500 An implementation MUST return values according to the type representations defined in Section 4.2.

2501 17.1.5 Contracts

2502 A conformant OBIX Server implementation MUST define and publish its OBIX Contracts according to the
2503 Contract design and semantics specified in Section 7. A Server MUST use space-separated Contract
2504 Lists to report the Contracts supported by Objects it reports, according to the rules defined in Section 7.

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 74 of 79
2505 Objects returned by an OBIX Server MUST NOT specify the obix:Nil Contract in their is attribute, as
2506 all Objects derive from obix:obj.

2507 17.2 Conditions for a Conforming OBIX Client

2508 A conformant OBIX Client implementation conforms to this specification as an OBIX Client if it meets the
2509 conditions described in the following subsections.

2510 17.2.1 Bindings

2511 A conformant OBIX Client implementation SHOULD support at least one of the standard bindings, which
2512 are defined in the companion specifications to this specification that describe OBIX Bindings.

2513 17.2.2 Encodings

2514 A conformant OBIX Client implementation SHOULD support one of the encodings defined in this
2515 specification. An implementation MUST support negotiation of which encoding to use in communicating
2516 with an OBIX Server using the mechanism defined for the binding being used.

2517 17.2.3 Naming

2518 A conformant OBIX Client implementation MUST be able to interpret and navigate URI schemes
2519 according to the general rules described in section 6.3.

2520 17.2.4 Contracts

2521 A conformant OBIX Client implementation MUST be able to consume and use OBIX Contracts defined by
2522 OBIX Server implementations with which it interacts, according to the Contract design and semantics
2523 defined in Section 7. A Client MUST be able to consume space-separated Contract Lists defining the
2524 implemented OBIX Contracts reported by Servers, according to the rules defined in Section 7. Objects
2525 sent by an OBIX Client MUST NOT specify the obix:Nil Contract in their is attribute, as all Objects
2526 derive from obix:obj.

2527 17.3 Interaction with other Implementations

2528 In order to be conformant, an implementation MUST be able to interoperate with any implementation that
2529 satisfies all MUST and REQUIRED level requirements. Where the implementation has implemented
2530 optional behaviors, the implementation MUST be able to fall back to mandated behaviors if the
2531 implementation it is interacting with has not implemented those same behaviors. Where the other
2532 implementation has implemented optional behaviors not implemented by this implementation, the
2533 conformant implementation MUST be able to provide the mandated level behaviors that allow the other
2534 implementation to fall back to using only mandated behaviors.

2535 17.3.1 Unknown Elements and Attributes

2536 OBIX Clients SHALL ignore information that they do not understand. A Client that receives a response
2537 containing information it does not understand MUST ignore the portion of the response containing the
2538 non-understood information. A Server that receives a request containing information it does not
2539 understand must ignore that portion of the request. If the Server can still understand the request it MAY
2540 choose to attempt to execute the request without using the ignored portion of the request.
2541

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 75 of 79
2542 Appendix A. Acknowledgments
2543 The following individuals have participated in the creation of this specification and are gratefully
2544 acknowledged:
2545 Participants:
2546 Ron Ambrosio, IBM
2547 Brad Benson, Trane
2548 Ron Bernstein, LonMark International*
2549 Ludo Bertsch, Continental Automated Buildings Association (CABA)
2550 Chris Bogen, US Department of Defense
2551 Rich Blomseth, Echelon Corporation
2552 Anto Budiardjo, Clasma Events, Inc.
2553 Jochen Burkhardt, IBM
2554 JungIn Choi, Kyungwon University
2555 David Clute, Cisco Systems, Inc.*
2556 Toby Considine, University of North Carolina at Chapel Hill
2557 William Cox, Individual
2558 Robert Dolin, Echelon Corporation
2559 Marek Dziedzic, Treasury Board of Canada, Secretariat
2560 Brian Frank, SkyFoundry
2561 Craig Gemmill, Tridium, Inc.
2562 Matthew Giannini, SkyFoundry
2563 Markus Jung, Vienna University of Technology
2564 Christopher Kelly, Cisco Systems
2565 Wonsuk Ko, Kyungwon University
2566 Perry Krol, TIBCO Software Inc.
2567 Corey Leong, Individual
2568 Ulf Magnusson, Schneider Electric
2569 Brian Meyers, Trane
2570 Jeremy Roberts, LonMark International
2571 Thorsten Roggendorf, Echelon Corporation
2572 Anno Scholten, Individual
2573 John Sublett, Tridium, Inc.
2574 Dave Uden, Trane
2575 Ron Zimmer, Continental Automated Buildings Association (CABA)*
2576 Rob Zivney, Hirsch Electronics Corporation
2577

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 76 of 79
2578 Appendix B. Revision History
Revision Date Editor Changes Made

wd-0.1 14 Jan 03 Brian Frank Initial version

wd-0.2 22 Jan 03 Brian Frank

wd-0.3 30 Aug 04 Brian Frank Move to Oasis, SysService

wd-0.4 2 Sep 04 Brian Frank Status

wd-0.5 12 Oct 04 Brian Frank Namespaces, Writes, Poll

wd-0.6 2 Dec 04 Brian Frank Incorporate schema comments

wd-0.7 17 Mar 05 Brian Frank URI, REST, Prototypes, History

wd-0.8 19 Dec 05 Brian Frank Contracts, Ops

wd-0.9 8 Feb 06 Brian Frank Watches, Alarming, Bindings

wd-0.10 13 Mar 06 Brian Frank Overview, XML, clarifications

wd-0.11 20 Apr 06 Brian Frank 10.1 sections, ack, min/max

wd-0.11.1 28 Apr 06 Aaron Hansen WSDL Corrections

wd-0.12 22 May 06 Brian Frank Status, feeds, no deltas

wd-0.12.1 29 Jun 06 Brian Frank Schema, stdlib corrections

obix-1.0-cd-02 30 Jun 06 Aaron Hansen OASIS document format compliance.

obix-1.0-cs-01 18 Oct 06 Brian Frank Public review comments

wd-obix.1.1.1 26 Nov 07 Brian Frank Fixes, date, time, tz

wd-obix.1.1.2 11 Nov 08 Craig Gemmill Add iCalendar scheduling

(from Aaron Hansen)

wd-obix-1.1.3 10 Oct 09 Brian Frank Remove Scheduling chapter

Rev namespace to 1.1
Add Binary Encoding chapter

wd-obix-1.1.4 12 Nov 09 Brian Frank MUST, SHOULD, MAY

History.tz, History.append
HTTP Content Negotiation

oBIX-1-1-spec- 01 Jun 10 Toby Considine Updated to current OASIS Templates, requirements

wd05

oBIX-1-1-spec- 08 Jun 10 Brad Benson Custom facets within binary encoding

wd06

oBIX-1-1-spec- 03 Mar 2013 Craig Gemmill Update to current OASIS templates, fixes
wd07

oBIX-1-1-spec- 27 Mar 2013 Craig Gemmill Changes from feedback

wd08

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 77 of 79
 Revision Date Editor Changes Made

obix-v1.1-wd09 23 Apr 2013 Craig Gemmill Update to new OASIS template

Add of attribute to obix:ref
Define additional list semantics
Clarify writable w.r.t. add/remove of children
Add deletion semantics
Add encoding negotiation

obix-v1.1-wd10 08 May Craig Gemmill Add CompactHistoryRecord

2013 Add preformatted History query
Add metadata for alternate hierarchies (tagging)

obix-v1.1-wd11 13 Jun 2013 Craig Gemmill Modify compact histories per TC feedback

obix-v1.1-wd12 27 Jun 2013 Craig Gemmill Add delimiter, interval to compact histories

obix-v1.1-wd13 8 July 2013 Toby Considine Replaced object diagram w/ UML

Updated references to other OBIX artifacts

obix-v1.1- 11 July 2013 Paul Knight Public Review Draft 1

CSPRD01

obix-v1.1-wd14 16 Sep 2013 Craig Gemmill Addressed some comments from PR01; Section 4
rework

obix-v1.1-wd15 30 Sep 2013 Craig Gemmill Addressed most of PR01 comments

obix-v1.1-wd16 16 Oct 2013 Craig Gemmill Finished first round of PR01 comments

obix-v1.1-wd17 30 Oct 2013 Craig Gemmill Reworked Lobby definition, more comments fixed

obix-v1.1-wd18 13 Nov 2013 Craig Gemmill Added bindings to lobby, oBIX->OBIX

obix-v1.1-wd19 26 Nov 2013 Craig Gemmill Updated server metadata and Watch sections

obix-v1.1-wd20 4 Dec 2013 Craig Gemmill WebSocket support for Watches

obix-v1.1-wd21 13 Dec 2013 Craig Gemmill intermediate revision

obix-v1.1-wd22 17 Dec 2013 Craig Gemmill More cleanup from JIRA, general Localization added

obix-v1.1-wd23 18 Dec 2013 Craig Gemmill Replaced UML diagram

obix-v1.1-wd24 19 Dec 2013 Toby Considine Minor error in Conformance, added bindings to
conformance, swapped UML diagram

obix-v1.1-wd25 13 Mar 2014 Craig Gemmill Initial set of corrections from PR02

obix-v1.1-wd26 27 May Craig Gemmill More PR02 corrections

2014

obix-v1.1-wd27 11 Jun 2014 Craig Gemmill PR02 corrections

obix-v1.1-wd28 26 Jun 2014 Craig Gemmill PR02 corrections

obix-v1.1-wd29 14 Jul 2014 Craig Gemmill PR02 corrections – Removed Compact Histories,
updated Lobby

obix-v1.1-wd30 17 Sep 2014 Craig Gemmill Rework Sec 5.5.1 Models to Tagspaces, make
tagspaces less like namespaces to avoid confusion

obix-v1.1-wd31 23 Sep 2014 Craig Gemmill Tagspaces attribute changed to ts, revised rules for
usage

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 78 of 79
 Revision Date Editor Changes Made

obix-v1.1-wd32 25 Sep 2014 Craig Gemmill Conformance and Tagspace fixes

obix-v1.1-wd33 1 Oct 2014 Craig Gemmill Fix incorrect 'names' attribute to 'name'

obix-v1.1-wd34 6 Oct 2014 Craig Gemmill Formatting fixes

obix-v1.1-wd35 13 Oct 2014 Craig Gemmill Minor tweaks, 1.9 -> non-normative

obix-v1.1-wd36 14 Oct 2014 Craig Gemmill Examples and Contract Definitions language in 1.6

obix-v1.1-wd37 28 Oct 2014 Craig Gemmill Better explanation of core type contracts in Section 4
Conformance section on unknown elements and
attributes

obix-v1.1-wd38 31 Oct 2014 Craig Gemmill Clarify rules on Contract List

obix-v1.1-wd39 10 Mar 2015 Craig Gemmill Marker Tags as Contracts, History collection, prototype
changes

obix-v1.1-wd40 14 Apr 2015 Craig Gemmill Clean up Lobby sections, assorted minor tweaks

obix-v1.1-wd41 16 Apr 2015 Craig Gemmill Contract List work

obix-v1.1-wd42 11 Jun 2015 Craig Gemmill Clean up Contract and Contract List, versioning
discussion w.r.t. Extents

obix-v1.1-wd43 15 Jun 2015 Craig Gemmill Clarified Contracts Table, definition of ‘type’ in 4.1,
usage of obix:Nil in ‘is’ attribute

obix-v1.1-wd44 19 Jun 2015 Craig Gemmill Include stdlib.obix, correct UML diagram 4-1

2579

obix-v1.1-cs01 14 September 2015

Standards Track Work Product Copyright © OASIS Open 2015. All Rights Reserved. Page 79 of 79