OBIX Version 1.1

Committee Specification Draft 03 /
Public Review Draft 03

06 November 2014

Specification URIs

This 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

Previous version:

http://docs.oasis-open.org/obix/obix/v1.1/csprd02/obix-v1.1-csprd02.pdf (Authoritative)

http://docs.oasis-open.org/obix/obix/v1.1/csprd02/obix-v1.1-csprd02.html

http://docs.oasis-open.org/obix/obix/v1.1/csprd02/obix-v1.1-csprd02.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 schemas: http://docs.oasis-open.org/obix/obix/v1.1/csprd03/schemas/

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 namespace:

·         http://docs.oasis-open.org/obix/ns/201410/schema

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 Technical Committee web page (https://www.oasis-open.org/committees/obix/ipr.php).

Citation format:

When referencing this specification the following citation format should be used:

[OBIX-v1.1]

OBIX Version 1.1. Edited by Craig Gemmill. 06 November 2014. OASIS Committee Specification Draft 03 / Public Review Draft 03. http://docs.oasis-open.org/obix/obix/v1.1/csprd03/obix-v1.1-csprd03.html. Latest version: http://docs.oasis-open.org/obix/obix/v1.1/obix-v1.1.html.

 

Notices

Copyright © OASIS Open 2014. All Rights Reserved.

All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual Property Rights Policy (the "OASIS IPR Policy"). The full Policy may be found at the OASIS website.

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to OASIS, except as needed for the purpose of developing any document or deliverable produced by an OASIS Technical Committee (in which case the rules applicable to copyrights, as set forth in the OASIS IPR Policy, must be followed) or as required to translate it into languages other than English.

The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns.

This document and the information contained herein is provided on an "AS IS" basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

OASIS requests that any OASIS Party or any other party that believes it has patent claims that would necessarily be infringed by implementations of this OASIS Committee Specification or OASIS Standard, to notify OASIS TC Administrator and provide an indication of its willingness to grant patent licenses to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification.

OASIS invites any party to contact the OASIS TC Administrator if it is aware of a claim of ownership of any patent claims that would necessarily be infringed by implementations of this specification by a patent holder that is not willing to provide a license to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification. OASIS may include such claims on its website, but disclaims any obligation to do so.

OASIS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on OASIS' procedures with respect to rights in any document or deliverable produced by an OASIS Technical Committee can be found on the OASIS website. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this OASIS Committee Specification or OASIS Standard, can be obtained from the OASIS TC Administrator. OASIS makes no representation that any information or list of intellectual property rights will at any time be complete, or that any claims in such list are, in fact, Essential Claims.

The name "OASIS" is a trademark of OASIS, the owner and developer of this specification, and should be used only to refer to the organization and its official outputs. OASIS welcomes reference to, and implementation and use of, specifications, while reserving the right to enforce its marks against misleading uses. Please see https://www.oasis-open.org/policies-guidelines/trademark for above guidance.

 

Table of Contents

1        Introduction. 9

1.1 Terminology. 9

1.2 Normative References. 9

1.3 Non-Normative References. 10

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 19

4.2.1 name. 20

4.2.2 href 20

4.2.3 is. 20

4.2.4 null 20

4.2.5 val 20

4.2.6 ts. 21

4.2.7 Facets. 21

4.3 Core Types. 24

4.3.1 val 24

4.3.2 list 28

4.3.3 ref 28

4.3.4 err 28

4.3.5 op. 28

4.3.6 feed. 28

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 [non-normative] 33

5.5.3 Encodings. 33

5.5.4 Bindings. 34

6        Naming. 35

6.1 Name. 35

6.2 Href 35

6.3 URI Normalization. 35

6.4 Fragment URIs. 36

7        Contracts. 37

7.1 Contract Terminology. 37

7.2 Contract List 37

7.3 Is Attribute. 38

7.4 Contract Inheritance. 38

7.4.1 Structure vs Semantics. 38

7.4.2 Overriding Defaults. 39

7.4.3 Attributes and Facets. 39

7.5 Override Rules. 39

7.6 Multiple Inheritance. 40

7.6.1 Flattening. 40

7.6.2 Mixins. 41

7.7 Contract Compatibility. 42

7.8 Lists and Feeds. 42

8        Operations. 44

9        Object Composition. 45

9.1 Containment 45

9.2 References. 45

9.3 Extents. 45

9.4 Metadata. 46

10      Networking. 48

10.1 Service Requests. 48

10.1.1 Read. 48

10.1.2 Write. 48

10.1.3 Invoke. 49

10.1.4 Delete. 49

10.2 Errors. 49

10.3 Localization. 50

11      Core Contract Library. 51

11.1 Nil 51

11.2 Range. 51

11.3 Weekday. 51

11.4 Month. 51

11.5 Units. 52

12      Watches. 54

12.1 Client Polled Watches. 54

12.2 Server Pushed Watches. 54

12.3 WatchService. 55

12.4 Watch. 55

12.4.1 Watch.add. 56

12.4.2 Watch.remove. 56

12.4.3 Watch.pollChanges. 57

12.4.4 Watch.pollRefresh. 57

12.4.5 Watch.lease. 57

12.4.6 Watch.delete. 57

12.5 Watch Depth. 57

12.6 Feeds. 58

13      Points. 59

13.1 Writable Points. 59

14      History. 60

14.1 History Object 60

14.2 History Queries. 61

14.2.1 HistoryFilter 61

14.2.2 HistoryQueryOut 62

14.2.3 HistoryRecord. 62

14.2.4 History Query Examples. 62

14.3 History Rollups. 63

14.3.1 HistoryRollupIn. 64

14.3.2 HistoryRollupOut 64

14.3.3 HistoryRollupRecord. 64

14.3.4 Rollup Calculation. 64

14.4 History Feeds. 66

14.5 History Append. 66

14.5.1 HistoryAppendIn. 66

14.5.2 HistoryAppendOut 66

15      Alarming. 67

15.1 Alarm States. 67

15.1.1 Alarm Source. 67

15.1.2 StatefulAlarm and AckAlarm.. 68

15.2 Alarm Contracts. 68

15.2.1 Alarm.. 68

15.2.2 StatefulAlarm.. 68

15.2.3 AckAlarm.. 68

15.2.4 PointAlarms. 69

15.3 AlarmSubject 69

15.4 Alarm Feed Example. 69

16      Security. 71

16.1 Error Handling. 71

16.2 Permission-based Degradation. 71

17      Conformance. 72

17.1 Conditions for a Conforming OBIX Server 72

17.1.1 Lobby. 72

17.1.2 Tag Spaces. 72

17.1.3 Bindings. 72

17.1.4 Encodings. 72

17.1.5 Contracts. 72

17.2 Conditions for a Conforming OBIX Client 73

17.2.1 Bindings. 73

17.2.2 Encodings. 73

17.2.3 Naming. 73

17.2.4 Contracts. 73

17.3 Interaction with other Implementations. 73

17.3.1 Unknown Elements and Attributes. 73

Appendix A.       Acknowledgments. 74

Appendix B.       Revision History. 75

 

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. 13

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. 37

Table 7-2. Contract terminology. 37

Table 7-3. Explicit and Implicit Contracts. 39

Table 7-4. Contract inheritance. 40

Table 10-1. Network model for OBIX. 48

Table 10-2. OBIX Service Requests. 48

Table 10-3. OBIX Error Contracts. 49

Table 11-1. OBIX Unit composition. 53

Table 13-1. Base Point types. 59

Table 14-1. Features of OBIX Histories. 60

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

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

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

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

Table 15-1. Alarm states in OBIX. 67

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

Table 16-1. Security concepts for OBIX. 71

 

 


1      Introduction

OBIX is designed to provide access to the embedded software systems which sense and control the world around us. Historically, integrating to these systems required custom low level protocols, often custom physical network interfaces. The rapid increase in ubiquitous networking and the availability of powerful microprocessors for low cost embedded devices is now weaving these systems into the very fabric of the Internet. Generically the term M2M for Machine-to-Machine describes the transformation occurring in this space because it opens a new chapter in the development of the Web - machines autonomously communicating with each other. The OBIX specification lays the groundwork for building this M2M Web using standard, enterprise-friendly technologies like XML, HTTP, and URIs.

1.1 Terminology

The keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD

NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC2119].  When used in the non-capitalized form, these words are to be interpreted with their normal English meaning.

1.2 Normative References

PNG                       Portable Network Graphics (PNG) Specification (Second Edition) , D. Duce, Editor, W3C Recommendation, 10 November 2003, http://www.w3.org/TR/2003/REC-PNG-20031110 . Latest version available at http://www.w3.org/TR/PNG

RFC2119                 Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels”, BCP 14, RFC 2119, March 1997. http://www.ietf.org/rfc/rfc2119.txt.

RFC3986                 Berners-Lee, T., Fielding, R., and Masinter, L., “Uniform Resource Identifier (URI): Generic Syntax”, STD 66, RFC 3986, January 2005.  http://www.ietf.org/rfc/rfc3986.txt.

SI Units                  A. Thompson and B. N. Taylor, The NIST Guide for the use of the International System of Units (SI), NIST Special Publication 811, 2008 Edition. http://www.nist.gov/pml/pubs/sp811/index.cfm.

SOA-RM                 Reference Model for Service Oriented Architecture 1.0, October 2006. OASIS Standard. http://docs.oasis-open.org/soa-rm/v1.0/soa-rm.pdf.

WS-Calendar          WS-Calendar Version 1.0, 30 July 2011.  OASIS Committee Specification, http://docs.oasis-open.org/ws-calendar/ws-calendar/v1.0/ws-calendar-1.0-spec.html.

WSDL                     Christensen, E., Curbera, F., Meredith, G., Weerawarana, S., “Web Services Description Language (WSDL), Version 1.1”, W3C Note, 15 March 2001. http://www.w3.org/TR/wsdl.

XLINK                    XML Linking Language (XLink) Version 1.1 , S. J. DeRose, E. Maler, D. Orchard, N. Walsh, Editors, W3C Recommendation, 6 May 2010, http://www.w3.org/TR/2010/REC-xlink11-20100506/ . Latest version available at http://www.w3.org/TR/xlink11/.

XML Schema          XML Schema Part 2: Datatypes Second Edition , P. V. Biron, A. Malhotra, Editors, W3C Recommendation, 28 October 2004, http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/ . Latest version available at http://www.w3.org/TR/xmlschema-2/.

ZoneInfo DB           IANA Time Zone Database, 24 September 2013 (latest version), http://www.iana.org/time-zones.

1.3 Non-Normative References

CamelCase             Use of Camel Case for Naming XML and XML-Related Components, OASIS Technology Report, December 29, 2005. http://xml.coverpages.org/camelCase.html.

OBIX REST            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.

OBIX SOAP            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.

OBIX Encodings    Encodings for OBIX: Common Encodings Version 1.0. Edited by Marcus Jung. Latest version. http://docs.oasis-open.org/obix/obix-encodings/v1.0/obix-encodings-v1.0.html.

OBIX WebSocket    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.

RDDL 2.0                Jonathan Borden, Tim Bray, eds. “Resource Directory Description Language (RDDL) 2.0,” January 2004.
http://www.openhealth.org/RDDL/20040118/rddl-20040118.html.

REST                     Fielding, R.T., “Architectural Styles and the Design of Network-based Software Architectures”, Dissertation, University of California at Irvine, 2000. http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm

RFC2818                 Rescorla, E., “HTTP over TLS”, RFC 2818, May 2000.  http://www.ietf.org/rfc/rfc2818.txt.

RFC5785                 Nottingham, M., Hammer-Lahav, E., “Defining Well-Known Uniform Resource Identifiers (URIs)”, RFC 5785, April 2010.  http://www.ietf.org/rfc/rfc5785.txt.

UML                       Unified Modeling Language (UML), Version 2.4.1, Object Management Group, May 07, 2012. http://uml.org/.

XML-ns                  Namespaces in XML , T. Bray, D. Hollander, A. Layman, Editors, W3C Recommendation, 14 January 1999, http://www.w3.org/TR/1999/REC-xml-names-19990114/ . Latest version available at http://www.w3.org/TR/REC-xml-names.

1.4 Namespace

If an implementation is using the XML Encoding according to the [OBIX Encodings] specification document, the XML namespace [XML-ns] URI that MUST be used is:

http://docs.oasis-open.org/ns/obix/201410

Dereferencing the above URI will produce the Resource Directory Description Language [RDDL 2.0] document that describes this namespace.

1.5 Naming Conventions

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

1.6 Editing Conventions

For readability, Element names in tables appear as separate words.  In the Schema, they follow the rules as described in Section 1.5.

Terms defined in this specification or used from specific cited references are capitalized; the same term not capitalized has its normal English meaning.

Examples and Contract definitions are informational and SHALL NOT be considered normative.  They will be marked distinctly from the specification text by using the following style:

<str name="example" val="This is an example, which is non-normative."/>

Schema fragments included in this specification as XML Contract definitions SHALL BE considered non-normative; in the event of disagreement between the two, the formal Schema supersedes the examples and Contract definitions defined here.

All UML and figures are illustrative and SHALL NOT be considered normative.

1.7 Language Conventions

Although several different encodings may be used for representing OBIX data, the most common is XML.  Therefore many of the concepts in OBIX are strongly tied to XML concepts.  Data objects are represented in XML by XML documents.  It is important to distinguish the usage of the term document in this context from references to this specification document.  When “this document” is used, it references this specification document.  When “OBIX document” or “XML document” is used, it references an OBIX object, encoded in XML, as per the convention for this (specification) document.  When used in the latter context, this could equally be understood to mean an OBIX object encoded in any of the other possible encoding mechanisms.

When expressed in XML, there is a one-to-one-mapping between Objects and elements. Objects are the fundamental abstraction used by the OBIX data model. Elements are how those Objects are expressed in XML syntax. This specification uses the term Object and sub-Object, although one can equivalently substitute the term element and sub-element when referencing the XML representation. The term child is used to describe an Object that is contained by another Object, and is semantically equivalent to the term sub-Object. The two terms are used interchangeably throughout this specification.

1.7.1 Definition of Terms

Several named terms are used within this document.  The following table describes the terms and 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 OBIX-enabled data and services.

10

Contract

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

3.6, 7

Extent

The tree of child Objects contained within an Object.

9.3

Facet

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

4.2.7

Feed

An Object that tracks every event rather than retaining only the current state.  This is typically used in alarm monitoring and history record retrieval.

4.3.6

Object

The base abstraction for expressing a piece of information in OBIX.  The Schema uses the name Obj for brevity, but the two terms Obj and Object are equivalent.

4.1

Rollup

An operation available on History objects to summarize the history data by a specific interval of time.

14.3

Server

An entity containing OBIX enabled data and services. Servers respond to requests from Client over a network.

10

Tag

A name-value pair that provides additional information about an Object, presented as a child Object of the original Object.

9.4

Val

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

4.3.1

Table 1-1. Definition of Terms.

 

1.8 Architectural Considerations

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

Concept

Solution

Covered in Sections

Information Model

Representing M2M information in a standard syntax – originally XML but expanded to other technologies

4, 5, 6, 8, 9

Interactions

transferring M2M information over a network

10

Normalization

developing standard representations for common M2M features: points, histories, and alarms

11, 12, 13, 14, 15

Foundation

providing a common kernel for new standards

7, 11

Table 1-2. Problem spaces for OBIX.

1.8.1 Information Model

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

1.8.2 Interactions

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

1.8.3 Normalization

There are a few concepts which have broad applicability in systems which sense and control the physical world. Version 1.1 of OBIX provides a normalized representation for three of these, described in Table 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

Table 1-3. Normalization concepts in OBIX.

1.8.4 Foundation

The requirements and vertical problem domains for M2M systems are immensely broad – too broad to cover in one single specification. OBIX is deliberately designed as a fairly low level specification, but with a powerful extension mechanism based on Contracts. The goal of OBIX is to lay the groundwork for a common object model and XML syntax which serves as the foundation for new specifications. It is hoped that a stack of specifications for vertical domains can be built upon OBIX as a common foundation.

1.9 Changes from Version 1.0 [non-normative]

Several areas of the specification have changed from Version 1.0 to Version 1.1.  Table 1-3 below lists key differences between Versions 1.0 and 1.1.  Implementers of earlier versions of OBIX should examine 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.

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

Add support for inclusion of metadata for alternate hierarchies (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.

Table 1-4. Changes from Version 1.0.

2      Quick Start [non-normative]

This chapter is for those eager to jump right into OBIX in all its angle bracket glory. The best way to begin is to take a simple example that anybody is familiar with – the staid thermostat. Let’s assume a very simple thermostat. It has a temperature sensor which reports the current space temperature and it has a setpoint that stores the desired temperature. Let’s assume the thermostat only supports a heating mode, so it has a variable that reports if the furnace should currently be on. Let’s take a look at what the thermostat might look like in OBIX XML:

<obj href="http://myhome/thermostat">

  <real name="spaceTemp" unit="obix:units/fahrenheit" val="67.2"/>

  <real name="setpoint" unit="obix:units/fahrenheit" val="72.0"/>

  <bool name="furnaceOn" val="true"/>

</obj>

The first thing to notice is the Information Model: there are three element types – obj, real, and bool. The root obj element models the entire thermostat. Its href attribute identifies the URI for this OBIX document. The thermostat Object has three child Objects, one for each of the thermostat’s variables. The real Objects store our two floating point values: space temperature and setpoint. The bool Object stores a boolean variable for furnace state. Each sub-element contains a name attribute which defines the role within the parent. Each sub-element also contains a val attribute for the current value. Lastly we see that we have annotated the temperatures with an attribute called unit so we know they are in Fahrenheit, not Celsius (which would be one hot room). The OBIX specification defines several of these annotations which are called Facets.

How was this Object obtained? The OBIX specification leverages commonly available networking technologies and concepts for defining Interactions between devices.  The thermostat implements an OBIX Server, and an OBIX Client can be used to issue a request for the thermostat’s data, by specifying its uri.  This concept is well understood in the world of M2M so OBIX requires no new knowledge to implement.

OBIX addresses the need to Normalize information from devices and present it in a standard way.  In most cases sensor and actuator variables (called Points) imply more semantics than a simple scalar value.  In the example of our thermostat, in addition to the current space temperature, it also reports the setpoint for desired temperature and whether it is trying to command the furnace on. In other cases such as alarms, it is desirable to standardize a complex data structure.  OBIX captures these concepts into Contracts. Contracts allow us to tag Objects with normalized semantics and structure.

Let’s suppose our thermostat’s sensor is reading a value of -412°F?  Clearly our thermostat is busted, so it should report a fault condition. Let’s rewrite the XML to include the status Facet and to provide additional semantics using Contracts:

<obj href="http://myhome/thermostat/">

 

  <!-- spaceTemp point -->

  <real name="spaceTemp" is="obix:Point"

        val="-412.0" status="fault"

        unit="obix:units/fahrenheit"/>

 

  <!-- setpoint point -->

  <real name="setpoint" is="obix:Point"

        val="72.0"

        unit="obix:units/fahrenheit"/>

 

  <!-- furnaceOn point -->

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

 

</obj>

Notice that each of our three scalar values are tagged as obix:Points via the is attribute. This is a standard Contract defined by OBIX for representing normalized point information. By implementing these Contracts, Clients immediately know to semantically treat these objects as points.

Contracts play a pivotal role in OBIX because they provide a Foundation for building new abstractions upon the core object model. Contracts are just normal objects defined using standard OBIX.  In fact, the following sections defining the core OBIX object model are expressed using Contracts.  One can see how easily this approach allows for definition of the key parts of this model, or any model that builds upon this model.

3      Architecture

3.1 Design Philosophies

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

REST

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

Contracts

A template model for expressing new OBIX “types”

Extensibility

Providing for consistent extensibility using only these concepts

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

3.2 Object Model

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

3.3 Encodings

OBIX provides simple syntax rules able to represent the underlying object model.  XML is a widely used language with well-defined and well-understood syntax that maps nicely to the OBIX object model.  The rest of this specification will use XML as the example encoding, because it is easily human-readable, and serves to clearly demonstrate the concepts presented.  The syntax used is normative.  Implementations using an XML encoding MUST conform to this syntax and representation of elements.

When encoding OBIX objects in XML, each of the object types map to one type of element. The Value Objects represent their data value using the val attribute (see Section 4.3.1 for a full description of Value Objects). All other aggregation is simply nesting of elements. A simple example to illustrate this concept is the Brady family from the TV show The Brady Bunch:

<obj href="http://bradybunch/people/Mike-Brady/">

  <obj name="fullName">

    <str name="first" val="Mike"/>

    <str name="last" val="Brady"/>

  </obj>

  <int name ="age" val="45"/>

  <ref name="spouse" href="/people/Carol-Brady"/>

  <list name="children">

    <ref href="/people/Greg-Brady"/>

    <ref href="/people/Peter-Brady"/>

    <ref href="/people/Bobby-Brady"/>

    <ref href="/people/Marsha-Brady"/>

    <ref href="/people/Jan-Brady"/>

    <ref href="/people/Cindy-Brady"/>

  </list>

</obj>

Note in this simple example how the href attribute specifies URI references which may be used to fetch more information about the object. Names and hrefs are discussed in detail in Section 6.

3.4 URIs

OBIX identifies objects (resources) with Uniform Resource Indicators (URIs) as defined in [RFC3986]. This is a logical choice, as a primary focus of OBIX is making information available over the web. Naming authorities manage the uniqueness of the first component of a URI, the domain name.

Conforming implementations MUST use [RFC3986] URIs to identify resources. Conforming implementations MAY restrict URI schemes and MUST indicate any restrictions in their conformance statement.

Typically, http-scheme URIs are used, but other bindings may require other schemes. Note that while https is technically a different scheme from http [RFC2818, RFC5785] they are typically used interchangeably with differing security transport. The commonly used term URL is shorthand for what is now an http-scheme URI.

3.5 REST

Objects identified with URIs and passed around as XML documents may sound a lot like REST – and this is intentional. REST stands for REpresentational State Transfer and is an architectural style for web services that mimics how the World Wide Web works. The World Wide Web is in essence a distributed collection of documents hyperlinked together using URIs. Similarly, OBIX presents controls and sensors as a collection of documents hyperlinked together using URIs.  Because REST is such a key concept in OBIX, it is not surprising that a REST binding is a core part of the specification.  The specification of this binding is defined in the [OBIX REST] specification.

REST is really more of a design style, than a specification. REST is resource centric as opposed to method centric - resources being OBIX objects. The methods actually used tend to be a very small fixed set of verbs used to work generically with all resources. In OBIX all network requests boil down to four request types:

3.6 Contracts

In every software domain, patterns start to emerge where many different object instances share common characteristics. For example in most systems that model people, each person has a name, address, and phone number. In vertical domains domain specific information may be attached to each person. For example an access control system might associate a badge number with each person.

In object oriented systems these patterns are captured into classes. In relational databases they are mapped into tables with typed columns. In OBIX these patterns are modeled using a concept called Contracts, which are standard OBIX objects used as a template. Contracts provide greater flexibility than a strongly typed schema language, without the overhead of introducing new syntax. A Contract document is parsed just like any other OBIX document. In formal terms, Contracts are a combination of prototype based inheritance and mixins.

OBIX Contracts describe abstract patterns for interaction with remote systems. Contracts use the grammar of OBIX to create semantics for these interactions. Standard Contracts normalize these semantics for common use by many systems. Contracts are used in OBIX as class definitions are for objects or as tables and relations are for databases.
  
OBIX specifies a minimal set of Contracts, which are described in later sections. Various vendors and groups have defined additional standard Contracts which are out of scope for this specification. Sets of these Contracts may be available as standard libraries. Implementers of systems using OBIX are advised to research whether these libraries are available, and if so, using them to reduce work and expand interoperation.

3.7 Extensibility

OBIX provides a foundation for developing new abstractions (Contracts) in vertical domains. OBIX is also extensible to support both legacy systems and new products. It is common for even standard building control systems to ship as a blank slate, to be completely programmed in the field. Control systems include, and will continue to include, a mix of standards based, vendor-based, and even project-based extensions.

The principle behind OBIX extensibility is that anything new is defined strictly in terms of Objects, URIs, and Contracts. To put it another way - new abstractions do not introduce any new XML syntax or functionality that client code is forced to care about. New abstractions are always modeled as standard trees of OBIX objects, just with different semantics. That does not mean that higher level application code never changes to deal with new abstractions.  But the core stack that deals with networking and parsing should not have to change to accommodate a new type.

This extensibility model is similar to most mainstream programming languages such as Java or C#. The syntax of the core language is fixed with a built in mechanism to define new abstractions. Extensibility is achieved by defining new class libraries using the language’s fixed syntax. This means the compiler need not be updated every time someone adds a new class.

4      Object Model

4.1 Object Model Description

OBIX specifies a small, fixed set of object types.  The OBIX object model is summarized in Figure 4-1. It consists of a common base Object (obix:obj) type, and includes 16 derived types.  It lists the default values and attributes for each type, including their optionality.  These optional attributes are included as well in the Schema definition for each type.  Section 4.2 describes the associated properties called Facets that certain OBIX types may have.  Section 4.3 describes each of the core OBIX types, including the rules for their usage and interpretation.  Additional rules defining complex behaviors such as naming and Contract inheritance are described in Sections 6 and 7.  These sections are essential to a full understanding of the object model.

Figure 4-1.  The OBIX primitive object hierarchy.

4.2 obj

The root abstraction in OBIX is Obj.  The name Obj is shortened from Object for brevity in encoding, but for more convenient reference, this specification uses the term Object synonymously with Obj.  Every Object type in OBIX is a derivative of Object.  Any Object or its derivatives can contain other Objects.

As stated in Section 3.3, the expression of Objects in an XML encoding is through XML elements.  Although the examples in this section are expressed in XML, the same concepts can be encoded in any of the specified OBIX encodings.  The OBIX Object type is expressed through the obj element.  The properties of an Object are expressed through XML attributes of the element.  The full set of rules for encoding OBIX in XML is contained in the [OBIX Encodings] document.  The term obj as used in this specification represents an OBIX Object in general, regardless of how it is encoded.

The Contract Definition of Object, as expressed by an obj element is

<obj href="obix:obj" null="false" writable="false" status="ok" />

The interpretation of this definition is described as follows.  The Contract Definition provides the attributes, including Contract implementations and Schema references, that exist in the Object by default, and which are inherited by any Object (and thus derived type) that extends this type.  Optional attributes that do not exist by default, such as displayName, are not included in the Contract Definition.  The href is the URI by which this Contract can be referenced (see Section 4.2.2), so another Object can reference this Contract in its is attribute (see Section 4.2.3).  The null attribute is specified as false, meaning that by default this Object "has a value" (see Section 4.2.4).  The writable attribute indicates this Object is readonly, so any Object type extending from obj (which is all Objects) will be readonly unless it explicitly overrides the writable attribute.  The status of the Object defaults to 'ok' unless overridden.  The properties supported on Object, and therefore on any derivative type, are described in the following sections.

4.2.1 name

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

4.2.2 href

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

4.2.3 is

All Objects MAY have the is attribute.  This attribute defines the Contracts this Object implements.  Contracts are discussed in Section 7.  The value of this attribute MUST be a Contract List, which is described in detail in Section 7.2.

4.2.4 null

All Objects support the null attribute. Null is the absence of a value, meaning that this Object has no value, has not been configured or initialized, or is otherwise not defined. Null is indicated using the null attribute with a boolean value. The default value of the null attribute is true for enum, abstime, date, and time, and false for all other Objects.  An example of the null attribute used in an abstime Object is:

<abstime name="startTime" displayName="Start Time"/>

 Null is inherited from Contracts a little differently than other attributes. See Section 7.4.3 for details.

4.2.5 val

Certain Objects represent a value and are called Value-type Objects.  These Objects MAY have the val attribute.  The Objects NEED NOT explicitly state the val attribute, as all Value-type objects define a default value for the attribute.  The Object types that are Value-type Objects, and are allowed to contain a val attribute, are bool, int, real, str, enum, abstime, reltime, date, time, and uri.  The literal representation of the values maps to [XML Schema], indicated in the following sections with the ‘xs:’ prefix.

4.2.6 ts

Certain Objects may be used as a Tag to provide metadata about their parent Object.  Tags and their usage are discussed in Section 9.4.  Tags are often grouped together into a Tag Space and published for use by others.  Use of Tag Spaces is discussed in Section 5.5.1.  If an Object is a Tag, then it MUST use the Tag name in its name attribute, and include the Tag Space which defines the Tag in the ts attribute.  For example, if a Tag Space named “foo” declares a Tag named “bar”, then an Object that has this Tag would be encoded as follows:

<obj name="taggedObject">

  <obj name="bar" ts="foo"/>

</obj>

4.2.7 Facets

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

4.2.7.1 displayName

The displayName Facet provides a localized human readable name of the Object stored as an xs:string:

<obj name="spaceTemp" displayName="Space Temperature"/>

Typically the displayName Facet SHOULD be a localized form of the name attribute. There are no restrictions on displayName overrides from the Contract (although it SHOULD be uncommon since displayName is just a human friendly version of name).

4.2.7.2 display

The display Facet provides a localized human readable description of the Object stored as an xs:string:

<bool name="occupied" val="false" display="Unoccupied"/>

There are no restrictions on display overrides from the Contract.

The display attribute serves the same purpose as Object.toString() in Java or C#. It provides a general way to specify a string representation for all Objects. In the case of value Objects (like bool or int) it SHOULD provide a localized, formatted representation of the val attribute.

4.2.7.3 icon

The icon Facet provides a URI reference to a graphical icon which may be used to represent the Object in an user agent:

<obj icon="/icons/equipment.png"/>

The contents of the icon attribute MUST be a URI to an image file. The image file SHOULD be a 16x16 PNG file, defined in the [PNG] specification. There are no restrictions on icon overrides from the Contract.

4.2.7.4 min

The min Facet is used to define an inclusive minimum value:

<int min="5" val="6"/>

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

4.2.7.5 max

The max Facet is used to define an inclusive maximum value:

<real max="70" val="65"/>

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

4.2.7.6 precision

The precision Facet is used to describe the number of decimal places to use for a real value:

<real precision="2" val="75.04"/>

The contents of the precision attribute MUST be xs:int. The value of the precision attribute equates to the number of meaningful decimal places. In the example above, the value of 2 indicates two meaningful decimal places: “75.04”. Typically precision is used by client applications which do their own formatting of real values. There are no restrictions on precision overrides.

4.2.7.7 range

The range Facet is used to define the value space of an enumeration. A range attribute is a URI reference to an obix:Range Object (see Section 11.2). It is used with the bool and enum types:

<enum range="/enums/offSlowFast" val="slow"/>

The override rule for range is that the specified range MUST inherit from the Contract’s range. Enumerations are unusual in that specialization of an enum usually involves adding new items to the range. Technically this is widening the enum’s value space, rather than narrowing it. But in practice, adding items into the range is the desired behavior.

4.2.7.8 status

The status Facet is used to annotate an Object about the quality and state of the information:

<real val="67.2" status="alarm"/>

Status is an enumerated string value with one of the following values from Table 4-2 (in ascending priority):

Status

Description

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.

Table 4-1. Status enumerations in OBIX.

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

4.2.7.9 tz

The tz Facet is used to annotate an abstime, date, or time Object with a timezone. The value of a tz attribute is a zoneinfo string identifier, as specified in the IANA Time Zone ([ZoneInfo DB]) database. The zoneinfo database defines the current and historical rules for each zone including its offset from UTC and the rules for calculating daylight saving time. OBIX does not define a Contract for modeling timezones, instead it just references the zoneinfo database using standard identifiers. It is up to OBIX enabled software to map zoneinfo identifiers to the UTC offset and daylight saving time rules.

The following rules are used to compute the timezone of an abstime, date, or time Object:

  1. If the tz attribute is specified, set the timezone to tz;
  2. Otherwise, if the Contract defines an inherited tz attribute, set the timezone to the inherited tz attribute;
  3. Otherwise, set the timezone to the Server’s timezone as defined by the lobby’s About.tz.

When using timezones, an implementation MUST specify the timezone offset within the value representation of an abstime or time Object. It is an error condition for the tz Facet to conflict with the timezone offset. For example, New York has a -5 hour offset from UTC during standard time and a -4 hour offset during daylight saving time:

<abstime val="2007-12-25T12:00:00-05:00" tz="America/New_York"/>

<abstime val="2007-07-04T12:00:00-04:00" tz="America/New_York"/>

4.2.7.10 unit

The unit Facet defines a unit of measurement in the [SI Units] system. A unit attribute is a URI reference to an obix:Unit Object (see section 11.5 for the Contract definition). It is used with the int and real types:

<real unit="obix:units/fahrenheit" val="67.2"/>

It is recommended that the unit Facet not be overridden if declared in a Contract. If it is overridden, then the override SHOULD use a Unit Object with the same dimensions as the Contract (it must measure the same physical quantity).

4.2.7.11 writable

The writable Facet specifies if this Object can be written by the Client. If false (the default), then the Object is read-only. It is used with all types except op and feed:

<str name="userName" val="jsmith"     writable="false"/>

<str name="fullName" val="John Smith" writable="true"/>

The writable Facet describes only the ability of Clients to modify this Object’s value, not the ability of Clients to add or remove children of this Object.  Servers MAY allow addition or removal of child Objects independently of the writability of existing objects.  If a Server does not support addition or removal of Object children through writes, it MUST return an appropriate error response (see Section 10.2 for details).

4.2.7.12 of

The of Facet specifies the type of child Objects contained by this Object.  The value of this attribute MUST be a Contract List, which is described in detail in Section 7.2.  This Facet is used with list and ref types, as explained in Sections 4.3.2 and 4.3.3, respectively.

4.2.7.13 in

The in Facet specifies the input argument type used by this Object.  The value of this attribute MUST be a Contract List, which is described in detail in Section 7.2.  This Facet is used with op and feed types.  Its use is described with the definition of those types in Section 4.3.5 for op and 4.3.6 for feed.

4.2.7.14 out

The out Facet specifies the output argument type used by this Object.  The value of this attribute MUST be a Contract List, which is described in detail in Section 7.2.  This Facet is used with the op type.  Its use is described with the definition of that type in Section 4.3.5.

4.3 Core Types

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

4.3.1 val

Certain types are allowed to have a val attribute and are called “value” types.  The val type is not directly used (it is “abstract”).  It simply reflects that instances of the type may contain a val attribute, as it is used to represent an object that has a specific value.  In object-oriented terms, the base OBIX val type is an abstract class, and its subtypes are concrete classes that inherit from that abstract class.  The 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

Table 4-2. Value Object types.

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

4.3.1.1 bool

The bool type represents a boolean condition of either true or false. Its val attribute maps to xs:boolean defaulting to false. The literal value of a bool MUST be “true” or “false” (the literals “1” and “0” are not allowed). The Contract definition is:

<bool href="obix:bool" is="obix:obj" val="false" null="false"/>

This defines an Object that can be referenced via the URI obix:bool, which extends the obix:obj type.  Its default value is false, and its null attribute is false by default.  The optional attribute range is not present in the Contract definition, which means that there is no standard range of values attached to an obix:bool by default.

Here is an example of an obix:bool which defines its range:

<bool val="true" range="#myRange">

  <list href="#myRange" is="obix:Range">

    <obj name="false" displayName="Inactive"/>

    <obj name="true" displayName="Active"/>

  </list>

</bool>

The range attribute specifies a local fragment reference to its myRange child, where the intended display names for the false and true states are listed.

4.3.1.2 int

The int type represents an integer number. Its val attribute maps to xs:long as a 64-bit integer with a default of 0. The Contract definition is:

<int href="obix:int" is="obix:obj" val="0" null="false"/>

This defines an Object that can be referenced via the URI obix:int, which extends the obix:obj type.  Its default value is 0, and its null attribute is false by default.  The optional attributes min, max, and unit are not present in the Contract definition, which means that no minimum, maximum, or units are attached to an obix:int by default.

An example:

<int val="52" min="0 max="100"/>

This example shows an obix:int with a value of 52.  The int may take on values between a minimum of 0 and a maximum of 100.  No units are attached to this value.

4.3.1.3 real

The real type represents a floating point number. Its val attribute maps to xs:double as an IEEE  64-bit floating point number with a default of 0. The Contract definition is:

<real href="obix:real" is="obix:obj" val="0" null="false"/>

This defines an Object that can be referenced via the URI obix:real, which extends the obix:obj type.  Its default value is 0, and its null attribute is false by default.  The optional attributes min, max, and unit are not present in the Contract definition, which means that no minimum, maximum, or units are attached to an obix:real by default.

An example:

<real val="31.06" name="spcTemp" displayName="Space Temp" unit="obix:units/celsius"/>

This example has provided a value for the name and displayName attributes, and has specified units to be attached to the value through the unit attribute.

4.3.1.4 str

The str type represents a string of Unicode characters. Its val attribute maps to xs:string with a default of the empty string. The Contract definition is:

<str href="obix:str" is="obix:obj" val="" null="false"/>

This defines an Object that can be referenced via the URI obix:str, which extends the obix:obj type.  Its default value is an empty string, and its null attribute is false by default.  The optional attributes min and max are not present in the Contract definition, which means that no minimum or maximum are attached to an obix:str by default.  The min and max attributes are constraints on the character length of the string, not the 'value' of the string.

An example:

<str val="hello world"/>

4.3.1.5 enum

The enum type is used to represent a value which must match a finite set of values. The finite value set is called the range. The val attribute of an enum is represented as a string key using xs:string. Enums default to null. The range of an enum is declared via Facets using the range attribute. The Contract definition is:

<enum href="obix:enum" is="obix:obj" val="" null="true"/>

This definition overrides the value of the null attribute so that by default, an obix:enum has a null value.  The val attribute by default is assigned an empty string, although this value is not used directly.  The inheritance of the null attribute is described in detail in Section 7.4.3.

An example:

<enum range="/enums/offSlowFast" val="slow"/>

In this example, the val attribute is specified, so the null attribute is implied to be false.  See Section 7.4.3 for details on the inheritance of the null attribute.  The range is also specified with a URI.  A consumer of this Object would be able to get the resource at that location to determine the list of tags that are associated with this enum.

4.3.1.6 abstime

The abstime type is used to represent an absolute point in time. Its val attribute maps to xs:dateTime, with the exception that it MUST contain the timezone. According to [XML Schema] Part 2 section 3.2.7.1, the lexical space for abstime is:

'-'? yyyy '-' mm '-' dd 'T' hh ':' mm ':' ss ('.' s+)? (zzzzzz) 

Abstimes default to null. The Contract definition is:

<abstime href="obix:abstime" is="obix:obj" val="1970-01-01T00:00:00Z" null="true"/>

The Contract Definition for obix:abstime also overrides the null attribute to be true.  The default value of the val attribute is thus not important.

An example for 9 March 2005 at 1:30PM GMT:

<abstime val="2005-03-09T13:30:00Z"/>

In this example, the val attribute is specified, so the null attribute is implied to be false.  See Section 7.4.3 for details on the inheritance of the null attribute.

The timezone offset is required, so the abstime can be used to uniquely relate the abstime to UTC. The optional tz Facet is used to specify the timezone as a zoneinfo identifier. This provides additional context about the timezone, if available. The timezone offset of the val attribute MUST match the offset for the timezone specified by the tz Facet, if it is also used. See the tz Facet section for more information.

4.3.1.7 reltime

The reltime type is used to represent a relative duration of time. Its val attribute maps to xs:duration with a default of 0 seconds. The Contract definition is:

<reltime href="obix:reltime" is="obix:obj" val="PT0S" null="false"/>

The Contract Definition for obix:reltime sets the default values of the val and null attributes.  In contrast to obix:abstime, here the null attribute is specified to be false.  The default value is 0 seconds, expressed according to [XML Schema] as "PT0S".

An example of a reltime which is constrained to be between 0 and 60 seconds, with a current value of 15 seconds:

<reltime val="PT15S" min="PT0S" max="PT60S"/>

4.3.1.8 date

The date type is used to represent a day in time as a day, month, and year. Its val attribute maps to xs:date. According to XML Schema Part 2 section 3.2.9.1, the lexical space for date is:

'-'? yyyy '-' mm '-' dd 

Date values in OBIX MUST omit the timezone offset and MUST NOT use the trailing “Z”. Only the tz attribute SHOULD be used to associate the date with a timezone. Date Objects default to null. The Contract definition is described here and is interpreted in similar fashion to obix:abstime.

<date href="obix:date" is="obix:obj" val="1970-01-01" null="true"/>

An example for 26 November 2007:

<date val="2007-11-26"/> 

In this example, the val attribute is specified, so the null attribute is implied to be false.  See Section 7.4.3 for details on the inheritance of the null attribute.

The tz Facet is used to specify the timezone as a zoneinfo identifier. See the tz Facet section for more information.

4.3.1.9 time

The time type is used to represent a time of day in hours, minutes, and seconds. Its val attribute maps to xs:time. According to [XML Schema] Part 2 section 3.2.8, the lexical space for time is the left truncated representation of xs:dateTime:

hh ':' mm ':' ss ('.' s+)? 

Time values in OBIX MUST omit the timezone offset and MUST NOT use the trailing “Z”. Only the tz attribute SHOULD be used to associate the time with a timezone. Time Objects default to null. The Contract definition is:

<time href="obix:time" is="obix:obj" val="00:00:00" null="true"/>

An example representing a wake time, which (in this example at least) must be between 7 and 10AM:

<time val="08:15:00" min="07:00:00" max="10:00:00"/>

In this example, the val attribute is specified, so the null attribute is implied to be false.  See Section 7.4.3 for details on the inheritance of the null attribute.

The tz Facet is used to specify the timezone as a zoneinfo identifier. See the tz Facet section for more information.

4.3.1.10 uri

The uri type is used to store a URI reference. Unlike a plain old str, a uri has a restricted lexical space as defined by [RFC3986] and the XML Schema xs:anyURI type. OBIX Servers MUST use the URI syntax described by [RFC3986] for identifying resources.  OBIX Clients MUST be able to navigate this URI syntax.  Most URIs will also be a URL, meaning that they identify a resource and how to retrieve it (typically via HTTP). The Contract definition is:

<uri href="obix:uri" is="obix:obj" val="" null="false"/>

An example for the OBIX home page:

<uri val="http://obix.org/" />

4.3.2 list

The list type is a specialized Object type for storing a list of other Objects. The primary advantage of using a list versus a generic obj is that lists can specify a common Contract for their contents using the of attribute. If specified, the of attribute MUST be a list of URIs formatted as a Contract List. The definition of list is:

<list href="obix:list" is="obix:obj" of="obix:obj"/>

This definition states that the obix:list type contains elements that are themselves OBIX Objects, because the of attribute value is obix:obj.  Instances of the obix:list type can provide a different value for of to indicate the type of Objects they contain.

An example list of strings:

<list of="obix:str">

  <str val="one"/>

  <str val="two"/>

</list>

Because lists typically have constraints on the URIs used for their child elements, they use special semantics for adding children.  Lists are discussed in greater detail along with Contracts in section 7.8.

4.3.3 ref

The ref type is used to create an external reference to another OBIX Object. It is the OBIX equivalent of the HTML anchor tag. The Contract definition is:

<ref href="obix:ref " is="obix:obj"/>

A ref element MUST always specify an href attribute.  A ref element SHOULD specify the type of the referenced object using the is attribute.  A ref element referencing a list (is=”obix:list”) SHOULD specify the type of the Objects contained in the list using the of attribute. References are discussed in detail in section 9.2.

4.3.4 err

The  err type is a special Object used to indicate an error. Its actual semantics are context dependent. Typically err Objects SHOULD include a human readable description of the problem via the display attribute. The Contract definition is:

<err href="obix:err" is="obix:obj"/>

4.3.5 op

The op type is used to define an operation. All operations take one input Object as a parameter, and return one Object as an output. The input and output Contracts are defined via the in and out attributes. The Contract definition is:

<op href="obix:op" is="obix:obj" in="obix:Nil" out="obix:Nil"/>

Operations are discussed in detail in Section 8.

4.3.6 feed

The feed type is used to define a topic for a Feed of events. Feeds are used with Watches to subscribe to a stream of events such as alarms. A Feed SHOULD specify the event type it fires via the of attribute. The in attribute can be used to pass an input argument when subscribing to the Feed (a filter for example).

<feed href="obix:feed" is="obix:obj" in="obix:Nil" of="obix:obj"/>

Feeds are subscribed via Watches.  This is discussed in Section 12.

5      Lobby

5.1 Lobby Object

All OBIX Servers MUST contain an Object which implements obix:Lobby. The Lobby Object serves as the central entry point into an OBIX Server, and lists the URIs for other well-known Objects defined by the OBIX Specification. Theoretically all a Client needs to know to bootstrap discovery is one URI for the Lobby instance. By convention this URI is “http://<server-ip-address>/obix”, although vendors are certainly free to pick another URI. The Lobby Contract is:

<obj href="obix:Lobby">

  <ref name="about" is="obix:About"/>

  <op  name="batch" in="obix:BatchIn" out="obix:BatchOut"/>

  <ref name="watchService" is="obix:WatchService"/>

  <list name="tagspaces" of="obix:uri" null="true"/>

  <list name="encodings" of="obix:str" null="true"/>

  <list name="bindings" of="obix:str" null="true"/>

</obj>

The following rules apply to the Lobby object:

1.     The Lobby MUST provide a ref to an Object which implements the obix:About Contract as described in Section 5.1.

2.     The Lobby MUST provide an op to invoke batch operations using the obix:BatchIn and obix:BatchOut Contracts as described in Section 5.2.

3.     The Lobby MUST provide a ref to an Object which implements the obix:WatchService Contract as described in Section 5.3.

4.     The Lobby MUST provide a list of the tag spaces referenced as described in Section in 5.5.1.

5.     The Lobby MUST provide a list of the encodings supported as described in Section 5.5.3.

6.     The Lobby MUST provide a list of the bindings supported as described in Section 5.5.4.

The Lobby instance is where implementers SHOULD place vendor-specific Objects used for data and service discovery.  The standard Objects defined in the Lobby Contract are described in the following Sections.

Because the Lobby Object is the primary entry point into an OBIX Server, it also serves as the primary attack point for malicious entities.  With that in mind, it is important that implementers of OBIX Servers consider carefully how to address security concerns.  Servers SHOULD ensure that Clients are properly authenticated and authorized before providing any information or performing any requested actions.  Even providing Lobby information can significantly increase the attack surface of an OBIX Server.  For instance, malicious Clients could make use of the Batch Service to issue further requests, or could reference items from the About section to search the web for any reported vulnerabilities associated with the Server’s vendor.

5.2 About

The obix:About Object is a standardized list of summary information about an OBIX Server. Clients can discover the About URI directly from the Lobby. The About Contract is:

<obj href="obix:About">

 

  <str name="obixVersion"/>

 

  <str name="serverName"/>

  <abstime name="serverTime"/>

  <abstime name="serverBootTime"/>

 

  <str name="vendorName"/>

  <uri name="vendorUrl"/>

 

  <str name="productName"/>

  <str name="productVersion"/>

  <uri name="productUrl"/>

 

  <str name="tz"/>

</obj>

 

The following children provide information about the OBIX implementation:

The following children provide information about the Server itself:

The following children provide information about the Server’s software vendor:

The following children provide information about the software product running the Server:

The following children provide additional miscellaneous information:

5.3 Batch

The Lobby defines a batch operation which allows Clients to group multiple OBIX requests together into a single operation. Grouping multiple requests together can often provide significant performance improvements over individual round-robin network requests. As a general rule, one big request will always out-perform many small requests over a network.

A batch request is an aggregation of read, write, and invoke requests implemented as a standard OBIX operation. At the protocol binding layer, it is represented as a single invoke request using the Lobby.batch URI. Batching a set of requests to a Server MUST be processed semantically equivalent to invoking each of the requests individually in a linear sequence.

The batch operation inputs a BatchIn Object and outputs a BatchOut Object:

<list href="obix:BatchIn" of="obix:uri"/>

 

<list href="obix:BatchOut" of="obix:obj"/>

The BatchIn Contract specifies a list of requests to process identified using the Read, Write, or Invoke Contract:

<uri href="obix:Read"/>

 

<uri href="obix:Write">

  <obj name="in"/>

</uri>

 

<uri href="obix:Invoke">

  <obj name="in"/>

</uri>

The BatchOut Contract specifies an ordered list of the response Objects to each respective request. For example the first Object in BatchOut must be the result of the first request in BatchIn. Failures are represented using the err Object. Every uri passed via BatchIn for a read or write request MUST have a corresponding result obj in BatchOut with an href attribute using an identical string representation from BatchIn (no normalization or case conversion is allowed).

It is up to OBIX Servers to decide how to deal with partial failures. In general idempotent requests SHOULD indicate a partial failure using err, and continue processing additional requests in the batch. If a Server decides not to process additional requests when an error is encountered, then it is still REQUIRED to return an err for each respective request not processed.

Let’s look at a simple example:

<list is="obix:BatchIn">

  <uri is="obix:Read" val="/someStr"/>

  <uri is="obix:Read" val="/invalidUri"/>

  <uri is="obix:Write" val="/someStr">

    <str name="in" val="new string value"/>

  </uri>

</list>

 

<list is="obix:BatchOut">

  <str href="/someStr" val="old string value"/>

  <err href="/invalidUri" is="obix:BadUriErr" display="href not found"/>

  <str href="/someStr" val="new string value">

</list>

In this example, the batch request is specifying a read request for “/someStr” and “/invalidUri”, followed by a write request to “/someStr”. Note that the write request includes the value to write as a child named “in”. The Server responds to the batch request by specifying exactly one Object for each request URI. The first read request returns a str Object indicating the current value identified by “/someStr”. The second read request contains an invalid URI, so the Server returns an err Object indicating a partial failure and continues to process subsequent requests. The third request is a write to “someStr”. The Server updates the value at “someStr”, and returns the new value. Note that because the requests are processed in order, the first request provides the original value of “someStr” and the third request contains the new value. This is exactly what would be expected had each of the requests been individually processed.

5.4 WatchService

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

5.5 Server Metadata

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

5.5.1 Tag Spaces

Any semantic models, such as tag dictionaries, used by the Server for presenting metadata about its Objects, are declared in a Tag Space.  This is a collection of names of Tags that relate to a particular usage or industry.  Tag Spaces used by a Server MUST be identified in the Lobby in the tagspaces element, which is a list of uris.  The name of each uri MUST be the name that is referenced by the Server when presenting Tags.  A more descriptive name MAY be provided in the displayName Facet.  The val of the uri MUST contain the reference location for this model or dictionary.  In order to prevent conflicts when the source of the referenced Tag Space is updated, the Server MUST provide version information, if it is available, for the Tag Space in the uri element.  Version information MUST be expressed as a child str element with the name “version”.  If the Tag Space publication source does not provide version information, then the Server MUST provide the time of retrieval from the publication source of the Tag Space.  Retrieval time MUST be expressed as a child abstime element with the name “retrieved”.  With this information, a Client can use the appropriate version of the model or dictionary for interpreting the Server metadata.  Clients MUST use the version element, if it exists, and retrieved as a fallback, for identifying which revision of the Tag Space to use in interpreting Tags presented by the Server.  A Server MAY include the retrieved element in addition to the version element, so a Client MUST NOT use retrieved unless version is not present.  For example, a Server that makes use of both an HVAC tag dictionary and a Building Terms tag dictionary might express these models in the following way:

<obj is="obix:Lobby">

  <!-- ... other lobby items ...-->

  <list name="tagspaces" of="obix:uri">

    <uri name="hvac" displayName="HVAC Tag Dictionary" val="http://example.com/tags/hvac">

      <str name="version" val="1.0.42"/>

    </uri>

    <uri name="bldg" displayName="Building Terms Dictionary" val="http://example.com/tags/building">

      <abstime name="retrieved" val="2014-07-01T10:39:00Z"/>

    </uri>

  </list>

</obj>

One caveat to this behavior is that the presentation of the usage of a particular semantic model may divulge unwanted information about the Server.  For instance, a Server that makes use of a medical tag dictionary and presents this in the Lobby may be undesirably advertising itself as an interesting target for individuals attempting to access confidential medical records.  Therefore, Servers SHOULD protect this section of the Lobby by only including it in communication to authenticated, authorized Clients.

5.5.2 Versioning [non-normative]

Each of the subsequent subsections describes a set of uris that describe specifications to which a Server is implemented.  These specifications are expected to change over time, and the Server implementation may not be updated at the same pace.  Therefore, a Server implementation MAY wish to provide versioning information with the uris that describes the date on which the specification was retrieved.  This information SHOULD be included as a child element of the uri.  It SHOULD be included as a str with the name ‘version’, containing the version information, if the source provides it.  If version information is not available, it SHOULD be included as an abstime with the name ‘retrieved’ and the time at which the version used by the Server was retrieved from the source.

<obj is="obix:Lobby">

{... other lobby items ...}

  <list name="bindings" of="obix:uri">

    <uri name="http" displayName="HTTP Binding" val="http://docs.oasis-open.org/obix/obix-rest/v1.0/obix-rest-v1.0.pdf">

      <abstime name="retrieved" val="2013-11-26T3:14:15.926Z"/>

    </uri>

    <uri name="myBinding" displayName="My New Binding" val="http://example.com/my-new-binding.doc">

      <str name="version" val="1.2.34"/>

    </uri>

  </list>

</obj>

5.5.3 Encodings

Servers MUST include the encodings supported in the encodings Lobby Object.  This is a list of strs.  The val of each uri MUST be the MIME type of the encoding.  A more friendly name MAY be provided in the displayName attribute.

The discovery of which encoding to use for communication between a Client and a Server is a function of the specific binding used.  Both Clients and Servers SHOULD support the XML encoding, as this encoding is used by the majority of OBIX implementations.  Clients and Servers MUST be able to support negotiation of the encoding to be used according to the binding’s error message rules.  Clients SHOULD first attempt to request communication using the desired encoding, and then fall back to other encodings as necessary based on the encodings supported by the Server.

For example, a Server that supports both XML and JSON encoding as defined in the [OBIX Encodings] specification would have a Lobby that appeared as follows (note the displayNames used are optional):

<obj is="obix:Lobby">

{... other lobby items ...}

  <list name="encodings" of="obix:str">

    <str val="text/xml" displayName="XML"/>

    <str val="application/json" displayName="JSON"/>

  </list>

</obj>

A Server that receives a request for an encoding that is not supported MUST send an UnsupportedErr response (see Section 10.2).

5.5.4 Bindings

Servers MUST include the available bindings supported in the bindings Lobby Object.  This is a list of uris.  The name of each uri SHOULD be the name of the binding as described by its corresponding specification document.  The val of the uri SHOULD be a reference to the binding specification.

Servers that support multiple bindings and encodings MAY support only certain combinations of the available bindings and encodings.  For example, a Server may support XML encoding over the HTTP and SOAP  bindings, but support JSON encoding only over the HTTP binding.

A Server that receives a request for a binding/encoding pair that is not supported MUST send an UnsupportedErr response (see Section 10.2).

For example, a Server that supports the SOAP and HTTP bindings as defined in the OBIX REST and OBIX SOAP specifications would have a Lobby that appeared as follows (note the displayNames used are optional):

<obj is="obix:Lobby">

{... other lobby items ...}

  <list name="bindings" of="obix:uri">

    <uri name="http" displayName="HTTP Binding" val="http://docs.oasis-open.org/obix/obix-rest/v1.0/obix-rest-v1.0.pdf"/>

    <uri name="soap" displayName="SOAP Binding" val="http://docs.oasis-open.org/obix/obix-soap/v1.0/obix-soap-v1.0.pdf"/>

  </list>

</obj>

6      Naming

All OBIX objects have two potential identifiers: name and href. Name is used to define the role of an Object within its parent. Names are programmatic identifiers only; the displayName Facet SHOULD be used for human interaction. Naming convention is to use camel case with the first character in lowercase. The primary purpose of names is to attach semantics to sub-objects. Names are also used to indicate overrides from a Contract. A good analogy to names is the field/method names of a class in Java or C#.

Hrefs are used to attach URIs to objects. An href is always a URI reference, which means it might be a relative URI that requires normalization against a base URI. The exception to this rule is the href of the root Object in an OBIX document – this href MUST be an absolute URI, not a URI reference. This allows the root Object’s href to be used as the effective base URI (xml:base) for normalization. A good analogy is hrefs in HTML or XLink.

Some Objects may have both a name and an href, just a name, just an href, or neither. It is common for objects within a list to not use names, since most lists are unnamed sequences of objects. The OBIX specification makes a clear distinction between names and hrefs - Clients MUST NOT assume any relationship between names and hrefs. From a practical perspective many vendors will likely build an href structure that mimics the name structure, but Client software MUST never assume such a relationship.

6.1 Name

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

6.2 Href

The href of an Object is represented using the href attribute. If specified, the root Object MUST have an absolute URI. All other hrefs within an OBIX document are treated as potentially relative URI references. Because the root Object’s href is always an absolute URI, it may be used as the base for normalizing relative URIs within the OBIX document. OBIX implementations MUST follow the formal rules for URI syntax and normalization defined in [RFC3986]. Several common cases that serve as design patterns within OBIX are considered in Section 6.3.

As a general rule every Object accessible for a read MUST specify a URI. An OBIX document returned from a read request MUST specify a root URI. However, there are certain cases where the Object is transient, such as a computed Object from an operation invocation. In these cases there MAY not be a root URI, meaning there is no way to retrieve this particular Object again. If no root URI is provided, then the Server’s authority URI is implied to be the base URI for resolving relative URI references.

6.3 URI Normalization

Implementers are free to use any URI schema, although the recommendation is to use URIs since they have well defined normalization semantics. Implementations that use URIs MUST comply with the rules and requirements described in [RFC3986].  Implementations SHOULD be able to interpret and navigate HTTP URIs, as this is used by the majority of OBIX implementations. 

Perhaps one of the trickiest issues is whether the base URI ends with a slash. If the base URI doesn’t end with a slash, then a relative URI is assumed to be relative to the base’s parent (to match HTML). If the base URI does end in a slash, then relative URIs can just be appended to the base. In practice, systems organized into hierarchical URIs SHOULD always specify the base URI with a trailing slash. Retrieval with and without the trailing slash SHOULD be supported with the resulting OBIX document always adding the implicit trailing slash in the root Object’s href.

6.4 Fragment URIs

It is not uncommon to reference an Object internal to an OBIX document. This is achieved using fragment URI references starting with the “#”. Consider the example:

<obj href="http://server/whatever/">

  <enum name="switch1" range="#onOff" val="on"/>

  <enum name="switch2" range="#onOff" val="off"/>

  <list is="obix:Range" href="onOff">

    <obj name="on"/>

    <obj name="off"/>

  </list>

</obj>

In this example there are two Objects with a range Facet referencing a fragment URI. Any URI reference starting with “#” MUST be assumed to reference an Object within the same OBIX document. Clients SHOULD NOT perform another URI retrieval to dereference the Object. In this case the Object being referenced is identified via the href attribute.

In the example above the Object with an href of “onOff” is both the target of the fragment URI, but also has the absolute URI “http://server/whatever/onOff”. But consider an Object that was the target of a fragment URI within the document, but could not be directly addressed using an absolute URI.  In that case the href attribute SHOULD be a fragment identifier itself. When an href attribute starts with “#” that means the only place it can be used is within the document itself:

  <list is="obix:Range" href="#onOff">

7      Contracts

OBIX Contracts are used to define inheritance in OBIX Objects.  A Contract is a template, defined as an OBIX Object, that is referenced by other Objects.  These 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 aretypically 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.

Table 7-1. Problems addressed by Contracts.

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

7.1 Contract Terminology

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 Object definition expressed as a standard OBIX Object.

Contract List

A list of one or more URIs to Contract Objects. The list of URIs is separated by the space character. It is used as the value of the is, of, in and out attributes.

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.

Table 7-2. Contract terminology.

7.2 Contract List

The syntax of a Contract List attribute is a list of URI references to other OBIX Objects. The URIs within the list MUST be separated by the space character (Unicode 0x20). Just like the href attribute, a Contract URI can be an absolute URI, Server relative, or even a fragment reference. The URIs within a Contract List may be scoped with an XML namespace prefix (see “Namespace Prefixes in Contract Lists” in the [OBIX Encodings] document).

A Contract List is not an obix:list type described in Section 4.3.2.  It is a string with special structure regarding the space-separated group of URIs.

The Contract List is used as the value of the is, of, in and out attributes.  An example of a point that implements multiple Contracts and advertises this through its ContractList is:

<real val="70.0" name="setpoint" is="obix:Point obix:WritablePoint acme:Setpoint"/>

From this example, we can see that this 'setpoint' Object implements the Point and WritablePoint Contracts that are described in this specification (Section 13).  It also implements a separate Contract defined with the acme namespace called Setpoint.  A consumer of this Object can rely on the fact that it has all of the syntactical and semantic behaviors of each of these Contracts, and I can interact with any of these behaviors.

An example of an obix:list that uses ContractList in its of attribute to describe the type of items contained in the obix:list is:

<list name="Logged Data" of="obix:Point obix:History">

  <real name="spaceTemp"/>

  <str val="Whiskers on Kittens"/>

  <str val="Bright Copper Kettles"/>

  <str val="Warm Woolen Mittens"/>

</list>

The

7.3 Is Attribute

An Object defines the Contracts it implements via the is attribute. The value of the is attribute is a Contract List. If the is attribute is unspecified, then the following rules are used to determine the implied Contract List:

Element names such as bool, int, or str are abbreviations for implied Contracts. However if an Object implements one of the primitive types, then it MUST use the correct OBIX type name. If an Object implements obix:int, then it MUST be expressed as <int/>, and MUST NOT use the form <obj is="obix:int"/>. An Object MUST NOT implement multiple value types, such as implementing both obix:bool and obix:int.

7.4 Contract Inheritance

7.4.1 Structure vs Semantics

Contracts are a mechanism of inheritance – they establish the classic “is a” relationship. In the abstract sense a Contract allows inheritance of a type. One can further distinguish between the explicit and implicit Contract:

Explicit Contract

Defines an object structure which all implementations must conform with.  This can be evaluated quantitatively by examining the Object 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.

Table 7-3. Explicit and Implicit Contracts.

For example when an Object implements the Alarm Contract, one can immediately infer that it will have a child called timestamp. This structure is in the explicit contract of Alarm and is formally defined in its encoded definition. But semantics are also attached to what it means to be an Alarm Object:  that the Object is providing information about an alarm event. These subjective concepts cannot be captured in machine language; rather they can only be captured in prose.

When an Object declares itself to implement a Contract it MUST meet both the explicit Contract and the implicit Contract. An Object MUST NOT put obix:Alarm in its Contract List unless it really represents an alarm event. Interpretation of Implicit Contracts generally requires that a human brain be involved, i.e., they cannot in general be consumed with pure machine-to-machine interaction.

7.4.2 Overriding Defaults

A Contract’s named children Objects are automatically applied to implementations. An implementation may choose to override or default each of its Contract’s children. If the implementation omits the child, then it is assumed to default to the Contract’s value. If the implementation declares the child (by name), then it is overridden and the implementation’s value SHOULD be used. Let’s look at an example:

<obj href="/def/television">

  <bool name="power"   val="false"/>

  <int  name="channel" val="2" min="2" max="200"/>

</obj>

 

<obj href="/livingRoom/tv" is="/def/television">

  <int name="channel" val="8"/>

  <int name="volume"  val="22"/>

</obj>

In this example a Contract Object is identified with the URI “/def/television”. It has two children to store power and channel. The living room TV instance includes “/def/television” in its Contract List via the is attribute. In this Object, channel is overridden to 8 from its default value of 2. However since power was omitted, it is implied to default to false.

An override is always matched to its Contract via the name attribute. In the example above it was clear that ‘channel’ was being overridden, because an Object was declared with a name of ‘channel’. A second Object was also declared with a name of ‘volume’. Since volume wasn’t declared in the Contract, it is assumed to be a new definition specific to this Object.

7.4.3 Attributes and Facets

Also note that the Contract’s channel Object declares a min and max Facet. These two Facets are also inherited by the implementation. Almost all attributes are inherited from their Contract including Facets, val, of, in, and out. The href attribute is never inherited. The null attribute inherits as follows:

  1. If the null attribute is specified, then its explicit value is used;
  2. If a val attribute is specified and null is unspecified, then null is implied to be false;
  3. If neither a val attribute or a null attribute is specified, then the null attribute is inherited from the Contract;
  4. If the null attribute is specified and is true, then the val attribute is ignored.

This allows us to implicitly override a null Object to non-null without specifying the null attribute.

7.5 Override Rules

Contract overrides are required to obey the implicit and explicit Contract. Implicit means that the implementation Object provides the same semantics as the Contract it implements. In the example above it would be incorrect to override channel to store picture brightness. That would break the semantic Contract.

Overriding the explicit Contract means to override the value, Facets, or Contract List. However one can never override the Object to be an incompatible value type. For example if the Contract specifies a child as real, then all implementations must use real for that child. As a special case, obj may be narrowed to any other element type.

One must also be careful when overriding attributes to never break restrictions the Contract has defined. Technically this means the value space of a Contract can be specialized or narrowed, but never generalized or widened. This concept is called covariance. Returning to the example from above:

<int name="channel" val="2" min="2" max="200"/>

In this example the Contract has declared a value space of 2 to 200. Any implementation of this Contract must meet this restriction. For example it would an error to override min to –100 since that would widen the value space. However the value space can be narrowed by overriding min to a number greater than 2 or by overriding max to a number less than 200. The specific override rules applicable to each Facet are documented in section 4.2.7.

7.6 Multiple Inheritance

An Object’s Contract List may specify multiple Contract URIs to implement. This is actually quite common - even required in many cases. There are two topics associated with the implementation of multiple 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).

Table 7-4. Contract inheritance.

7.6.1 Flattening

It is common for Contract Objects themselves to implement Contracts, just like it is common in OO languages to chain the inheritance hierarchy. However due to the nature of accessing OBIX documents over a network, it is often desired to minimize round trip network requests which might be needed to “learn” about a complex Contract hierarchy. Consider this example:

<obj href="/A" />

<obj href="/B" is="/A" />

<obj href="/C" is="/B" />

<obj href="/D" is="/C" />

In this example if an OBIX Client were reading Object D for the first time, it would take three more requests to fully learn what Contracts are implemented (one for C, B, and A). Furthermore, if the Client was just looking for Objects that implemented B, it would difficult to determine this just by looking at D.

Because of these issues, Servers are REQUIRED to flatten their Contract inheritance hierarchy into a list when specifying the is, of, in, or out attributes. In the example above, the correct representation would be:

<obj href="/A" />

<obj href="/B" is="/A" />

<obj href="/C" is="/B /A" />

<obj href="/D" is="/C /B /A" />

This allows Clients to quickly scan D’s Contract List to see that D implements C, B, and A without further requests.

Because complex Servers often have a complex Contract hierarchy of Object types, the requirement to flatten the Contract hierarchy can lead to a verbose Contract List.  Often many of these Contracts are from the same namespace.  For example:

<obj name="VSD1" href="acme:VSD-1" is="acmeObixLibrary:VerySpecificDevice1 acmeObixLibrary:VerySpecificDeviceBase acmeObixLibrary:SpecificDeviceType acmeObixLibrary:BaseDevice acmeObixLibrary:BaseObject"/>

To save space, Servers MAY choose to combine the Contracts from the same namespace and present the Contract List with the namespace followed by a colon, then a brace-enclosed list of Contract names:

<real name="writableReal" is="obix:{Point WritablePoint}"/>

 

<obj name="vsd1" href="acme:VSD-1" is="acmeObixLibrary:{VerySpecificDevice1 VerySpecificDeviceBase SpecificDeviceType BaseDevice BaseObject}"/>

Clients MUST be able to consume this form of the Contract List and expand it to the standard form.

7.6.2 Mixins

Flattening is not the only reason a Contract List might contain multiple Contract URIs. OBIX also supports the more traditional notion of multiple inheritance using a mixin approach as in the following example:

<obj href="acme:Device"> 

  <str name="serialNo"/>

</obj>

 

<obj href="acme:Clock" is="acme:Device">

  <op name="snooze"/>

  <int name="volume" val="0"/>

</obj>

 

<obj href="acme:Radio" is="acme:Device ">

  <real name="station" min="87.0" max="107.5"/>

  <int name="volume" val="5"/>

</obj>

 

<obj href="acme:ClockRadio" is="acme:Radio acme:Clock acme:Device"/>

In this example ClockRadio implements both Clock and Radio. Via flattening of Clock and Radio, ClockRadio also implements Device. In OBIX this is called a mixinClock, Radio, and Device are mixed into (merged into) ClockRadio. Therefore ClockRadio inherits four children: serialNo, snooze, volume, and station. Mixins are a form of multiple inheritance akin to Java/C# interfaces (remember OBIX is about the type inheritance, not implementation inheritance).

Note that Clock and Radio both implement Device. This inheritance pattern where two types both inherit from a base, and are themselves both inherited by a single type, is called a “diamond” pattern from the shape it takes when the class hierarchy is diagrammed. From Device, ClockRadio inherits a child named serialNo. Furthermore notice that both Clock and Radio declare a child named volume. This naming collision could potentially create confusion for what serialNo and volume mean in ClockRadio.

OBIX solves this problem by flattening the Contract’s children using the following rules:

  1. Process the Contract definitions in the order they are listed
  2. If a new child is discovered, it is mixed into the Object’s definition
  3. If a child is discovered that has already been processed via a previous Contract definition, then the previous definition takes precedence. However it is an error if the duplicate child is not Contract compatible with the previous definition (see Section 7.7).

In the example above this means that Radio.volume is the definition used for ClockRadio.volume, because Radio has a higher precedence than Clock (it is first in the Contract List). Thus ClockRadio.volume has a default value of “5”. However it would be invalid if Clock.volume were declared as str, since it would not be Contract compatible with Radio’s definition as an int – in that case ClockRadio could not implement both Clock and Radio. It is the Server vendor’s responsibility not to create incompatible name collisions in Contracts.

The first Contract in a list is given specific significance since its definition trumps all others. In OBIX this Contract is called the Primary Contract. For this reason, the Primary Contract SHOULD implement all the other Contracts specified in the Contract List (this actually happens quite naturally by itself in many programming languages). This makes it easier for Clients to bind the Object into a strongly typed class if desired. Contracts MUST NOT implement themselves nor have circular inheritance dependencies.

7.7 Contract Compatibility

A Contract List which is covariantly substitutable with another Contract List is said to be Contract compatible. Contract compatibility is a useful term when talking about mixin rules and overrides for lists and operations. It is a concept similar to previously defined override rules – however, instead of the rules applied to individual Facet attributes, it is applied to an entire Contract List.

A Contract List X is compatible with Contract List Y, if and only if X narrows the value space defined by Y. This means that X can narrow the set of Objects which implement Y, but never expand the set. Contract compatibility is not commutative (X is compatible with Y does not imply Y is compatible with X). Practically, this can be expressed as:  X can add new URIs to Y’s list, but never take any away.

7.8 Lists and Feeds

Implementations derived from list or feed Contracts inherit the of attribute. Like other attributes an implementing Object can override the of attribute, but only if Contract compatible - a Server SHOULD include all of the URIs in the Contract’s of attribute, but it MAY add additional ones (see Section 7.7).

Lists and Feeds also have the special ability to implicitly define the Contract List of their contents. In the following example it is implied that each child element has a Contract List of /def/MissingPerson without actually specifying the is attribute in each list item:

<list of="/def/MissingPerson">

  <obj> <str name="fullName" val="Jack Shephard"/> </obj>

  <obj> <str name="fullName" val="John Locke"/> </obj>

  <obj> <str name="fullName" val="Kate Austen"/> </obj>

</list>

If an element in the list or Feed does specify its own is attribute, then it MUST be Contract compatible with the of attribute.

If an implementation wishes to specify that a list should contain references to a given type, then the implementation SHOULD include obix:ref  in the of attribute.  This MUST be the first URI in the of attribute.  For example, to specify that a list should contain references to obix:History Objects (as opposed to inline History Objects):

<list name="histories" of="obix:ref obix:History"/>

In many cases a Server will implement its own management of the URI scheme of the child elements of a list.  For example, the href attribute of child elements may be a database key, or some other string defined by the Server when the child is added.  Servers will not, in general, allow Clients to specify this URI during addition of child elements through a direct write to a list’s subordinate URI.

Therefore, in order to add child elements to a list which supports Client addition of list elements, Servers MUST support adding list elements by writing to the list URI with an Object of a type that matches the list’s Contract.  Servers MUST return the written resource (including any Server-assigned href) upon successful completion of the write.

For example, given a list of <real> elements, and presupposing a Server-imposed URI scheme:

<list href="/a/b" of="obix:real" writable="true"/>

Writing to the list URI itself will replace the entire list if the Server supports this behavior:

WRITE /a/b

<list of="obix:real">

 <real name="foo" val="10.0"/>

 <real name="bar" val="20.0"/>

</list>

returns:

<list href="/a/b" of="obix:real">

 <real name="foo" href="1" val="10.0"/>

 <real name="bar" href="2" val="20.0"/>

</list>

Writing a single element of type <real> will add this element to the list.

WRITE /a/b

<real name="baz" val="30.0"/>

returns:

<real name="baz" href="/a/b/3" val="30.0"/>

while the list itself is now:

<list href="/a/b" of="obix:real">

 <real name="foo" href="1" val="10.0"/>

 <real name="bar" href="2" val="20.0"/>

 <real name="baz" href="3" val="30.0"/>

</list>

Note that if a Client has the correct URI to reference a list child element, this can still be used to modify the value of the element directly:

WRITE /a/b/3

<real name="baz2" val="33.0"/>

returns:

<real name="baz2" href="/a/b/3" val="33.0"/>

and the list has been modified to:

<list href="/a/b" of="obix:real">

 <real name="foo" href="1" val="10.0"/>

 <real name="bar" href="2" val="20.0"/>

 <real name="baz" href="3" val="33.0"/>

</list>

8      Operations

OBIX Operations are the exposed actions that an OBIX Object can be commanded to take, i.e., they are things you can invoke to “do” something to the Object. Typically object-oriented languages express this concept as the publicly accessible methods on the object. They generally map to commands rather than a variable that has continuous state. Unlike Value Objects which represent an Object and its current state, the op element merely represents the definition of an operation you can invoke.

All operations take exactly one Object as a parameter and return exactly one Object as a result. The in and out attributes define the Contract List for the input and output Objects. If you need multiple input or output parameters, then wrap them in a single Object using a Contract as the signature. For example:

<op href="/addTwoReals" in="/def/AddIn" out="obix:real"/>

 

<obj href="/def/AddIn">

  <real name="a"/>

  <real name="b"/>

</obj>

Objects can override the operation definition from one of their Contracts. However the new in or out Contract List MUST be Contract compatible (see Section 7.7) with the Contract’s definition.

If an operation doesn’t require a parameter, then specify in as obix:Nil. If an operation doesn’t return anything, then specify out as obix:Nil. Occasionally an operation is inherited from a Contract which is unsupported in the implementation. In this case set the status attribute to disabled.

Operations are always invoked via their own href attribute (not their parent’s href). Therefore operations SHOULD always specify an href attribute if you wish Clients to invoke them. A common exception to this rule is Contract definitions themselves.

9      Object Composition

Object Composition describes how multiple OBIX Objects representing individual pieces are combined to form a larger unit.  The individual pieces can be as small as the various data fields in a simple thermostat, as described in Section 2, or as large as entire buildings, each themselves composed of multiple networks of devices.  All of the OBIX Objects are linked together via URIs, similar to the way that the World Wide Web is a group of HTML documents hyperlinked together through URIs  These OBIX Objects may be static documents like Contracts or device descriptions.  Or they may be real-time data or services.

Individual Objects are composed together in two ways to define this web. Objects may be composed together via containment or via reference.

9.1 Containment

Any OBIX Object may contain zero or more child Objects. This even includes Objects which might be considered primitives such as bool or int. All Objects are open ended and free to specify new Objects which may not be in the Object’s Contract. Containment is represented in the XML syntax by nesting the XML elements:

<obj href="/a/">

  <list name="b" href="b">

    <obj href="b/c"/>

  </list>

</obj> 

In this example the Object identified by “/a” contains “/a/b”, which in turn contains “/a/b/c”. Child Objects may be named or unnamed depending on if the name attribute is specified (Section 6.1). In the example, “/a/b” is named and “/a/b/c” is unnamed. Typically named children are used to represent fields in a record, structure, or class type. Unnamed children are often used in lists.

9.2 References

 

To understand references, it is useful to return to the World  Wide Web metaphor.  Individual HTML elements like <p> and <div> are grouped into HTML documents, which are the atomic entities passed over the network.  The documents are linked together using the <a> anchor element.  These anchors serve as placeholders, referencing outside documents via a URI.

An OBIX reference is similar to an HTML anchor. It serves as a placeholder to “link” to another OBIX Object via a URI. While containment is best used to model small trees of data, references may be used to model very large trees or graphs of Objects.

As a clue to Clients consuming OBIX references, the Server SHOULD specify the type of the referenced Object using the is attribute.  In addition, for the list element type, the Server SHOULD use the of attribute to specify the type of Objects contained by the list.  This allows the Client to prepare the proper visualizations, data structures, etc. for consuming the Object when it accesses the actual Object.  For example, a Server might provide a reference to a list of available points:

<ref name="points" is="obix:list" of="obix:Point"/>

9.3 Extents

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

<obj href="/a/">

  <obj name="b" href="b">

    <obj name="c"/>

    <ref name="d" href="/d"/>

  </obj>

  <ref name="e" href="/e"/>

</obj>

In the example above, there are five Objects named ‘a’ to ‘e’. Because ‘a’ includes an href, it has an associated extent, which encompasses ‘b’ and ‘c’ by containment and ‘d’ and ‘e’ by reference. Likewise, ‘b’ has an href which results in an extent encompassing ‘c’ by containment and ‘d’ by reference. Object ‘c’ does not provide a direct href, but exists in both the ‘a’ and ‘b’ Objects’ extents. Note an Object with an href has exactly one extent, but can be nested inside multiple extents.

When marshaling Objects into an OBIX document, it is required that an extent always be fully inlined into the document. The only valid Objects which may be references outside the document are ref Objects.  In order to allow conservation of bandwidth usage, processing time, and storage requirements, Servers SHOULD use non-ref Objects only for representing primitive children which have no further extent.  Refs SHOULD be used for all complex children that have further structure under them.  Clients MUST be able to consume the refs and then request the referenced object if it is needed for the application.  As an example, consider a Server which has the following object tree, represented here with full extent:

<obj name="myBuilding" href="/building/">

  <str name="address" val="123 Main Street"/>

  <obj name="floor1">

    <obj name="zone1">

      <obj name="room1"/>

    </obj>

  </obj>

</obj>

When marshaled into an OBIX document to respond to a Client Read request of the /building/ URI, the Server SHOULD inline only the address, and use a ref for Floor1:

<obj name="myBuilding" href="/building/">

  <str name="address" val="123 Main Street"/>

  <ref name="floor1" href="floor1"/>

</obj>

If the Object implements a Contract, then it is required that the extent defined by the Contract be fully inlined into the document (unless the Contract itself defined a child as a ref element). An example of a Contract which specifies a child as a ref is Lobby.about (Section 5.2).

9.4 Metadata

An OBIX Server MAY present additional metadata about Objects in its model through the use of Tags.  A Tag is simply a name-value pair represented as a child element of the Object about which the Tag is providing information.  Tags MUST be represented with an OBIX primitive matching the value type.  For the case of “marker” Tags which have no value, the OBIX <obj> element MUST be used.  If these Tags are defined in an external Tag space, e.g. Haystack, a building information model (BIM), etc., then the Tags MUST reference the Tag space by an identifier which MUST be declared in the Lobby, along with the URI for the semantic model it represents.  The format for the Lobby definition is discussed in Section 5.5.1.

Multiple tag spaces MAY be included simultaneously in an Object.  For example, a Server representing a building management system might present one of its Variable Air Volume (VAV) controllers using metadata from both HVAC and Building tag spaces as shown below.  The Lobby would express the models used, as in Section5.5.1:

<obj is="obix:Lobby">

  <!-- ... other lobby items ...-->

  <list name="tagspaces" of="obix:uri">

    <uri name="hvac" displayName="HVAC Tag Dictionary" val="http://example.com/tags/hvac">

      <str name="version" val="1.0.42"/>

    </uri>

    <uri name="bldg" displayName="Building Terms Dictionary" val="http://example.com/tags/building">

      <abstime name="retrieved" val="2014-07-01T10:39:00Z"/>

    </uri>

  </list>

</obj>

Then, the Object representing the VAV controller would reference these dictionaries using their names in the tagspace attribute, and the tags as defined in the dictionary as the name:

<real name="VAV-101" href="/MainCampus/BurnsHall/Floor1/Room101/VAV/" val="70.0">

  <real name="spaceTemp" href="spaceTemp/" val="70.0"/>

  <real name="setpoint" href="setpoint/" val="72.0"/>

  <bool name="heatCmd" href="heatCmd/" val="true"/>

  <enum name="sensorType" val="ThermistorType3"/>

  <obj name="temperature" ts="hvac"/>

  <obj name="vav" ts="hvac"/>

  <int name="roomNumber" ts="bldg" val="101"/>

  <int name="floor" ts="bldg" val="1"/>

  <str name="buildingName" ts="bldg" val="Montgomery Burns Science Labs"/>

  <uri name="ahuReference" ts="hvac" val="/MainCampus/BurnsHall/AHU/AHU1"/>

</real>

Servers SHOULD only provide this information to Clients that are properly authenticated and authorized, to avoid providing a vector for attack if usage of a particular model identifies the Server as an interesting target.

The metadata SHOULD be presented using the ref element, so this additional information can be skipped during normal encoding.  If a Client is able to consume the metadata, it SHOULD ask for the metadata by requesting the metadata hierarchy.

OBIX Clients SHALL ignore information that they do not understand.  In particular, a conformant Client that is presented with Tags that it does not understand MUST ignore those Tags.  No OBIX Server may require understanding of these Tags for interoperation.

10 Networking

The heart of OBIX is its object model and associated encoding. However, the primary use case for OBIX is to access information and services over a network. The OBIX architecture is based on a Client/Server 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.

Table 10-1. Network model for OBIX.

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

10.1 Service Requests

All service requests made against an OBIX Server can be distilled to 4 atomic operations, expressed in 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.

Table 10-2. OBIX Service Requests.

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

10.1.1 Read

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

10.1.2 Write

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

The Server is free to completely or partially ignore the write, so Clients SHOULD be prepared to examine the response to check if the write was successful. Servers may also return an err Object to indicate the write was unsuccessful.

Clients are not required to include the Object’s full extent in the request. Objects explicitly specified in the request object tree SHOULD be overwritten or “overlaid” over the Server’s actual object tree. Only the val attribute should be specified for a write request (outside of identification attributes such as name). The null attribute MAY also be used to set an Object to null. If the null attribute is not specified and the val attribute is specified, then it is implied that null is false.The behavior of a Server upon receiving a write request which provides Facets is unspecified with regards to the Facets. When writing int or reals with units, the write value MUST be in the same units as the Server specifies in read requests – Clients MUST NOT provide a different unit Facet and expect the Server to auto-convert (in fact the unit Facet SHOULD NOT be included in the request).

10.1.3 Invoke

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

10.1.4 Delete

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

10.2 Errors

Request errors are conveyed to Clients with the err element. Any time an OBIX Server successfully receives a request and the request cannot be processed, then the Server MUST return an err Object to the Client.  This includes improperly encoded requests, such as non-well-formed XML, if that encoding is used.  Returning a valid OBIX document with err SHOULD be used when feasible rather than protocol specific error handling (such as an HTTP response code). Such a design allows for consistency with batch request partial failures and makes protocol binding more pluggable by separating data transport from application level error handling.

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

Table 10-3. OBIX Error Contracts.

The Contracts for these errors are:

<err href="obix:BadUriErr"/>

<err href="obix:UnsupportedErr"/>

<err href="obix:PermissionErr"/>

If one of the above Contracts makes sense for an error, then it SHOULD be included in the err element’s is attribute. It is strongly encouraged to also include a useful description of the problem in the display attribute.

10.3 Localization

Servers SHOULD localize appropriate data based on the desired locale of the Client agent. Localization SHOULD include the display and displayName attributes. The desired locale of the Client SHOULD be determined through authentication or through a mechanism appropriate to the binding used. A suggested algorithm is to check if the authenticated user has a preferred locale configured in the Server’s user database, and if not then fallback to the locale derived from the binding.

Localization MAY include auto-conversion of units. For example if the authenticated user has configured a preferred unit system such as English versus Metric, then the Server might attempt to convert values with an associated unit facet to the desired unit system.

11 Core Contract Library

This chapter defines some fundamental Object Contracts that serve as building blocks for the OBIX specification.  This Core Contract Library is also called the Standard Library, and is expressed in the stdlib.obix file that is associated with this specification.

11.1 Nil

The obix:Nil Contract defines a standardized null Object. Nil is commonly used for an operation’s in or out attribute to denote the absence of an input or output. The definition:

<obj href="obix:Nil" null="true"/>

11.2 Range

The obix:Range Contract is used to define a bool or enum’s range. Range is a list Object that contains zero or more Objects called the range items. Each item’s name attribute specifies the identifier used as the literal value of an enum. Item ids are never localized, and MUST be used only once in a given range. You may use the optional displayName attribute to specify a localized string to use in a user interface. The definition of Range:

<list href="obix:Range" of="obix:obj"/>

An example:

<list href="/enums/offSlowFast" is="obix:Range">

  <obj name="off"  displayName="Off"/>

  <obj name="slow" displayName="Slow Speed"/>

  <obj name="fast" displayName="Fast Speed"/>

</list>

The range Facet may be used to define the localized text of a bool value using the ids of “true” and “false”:

<list href="/enums/onOff" is="obix:Range">

  <obj name="true"  displayName="On"/>

  <obj name="false" displayName="Off"/>

</list >

11.3 Weekday

The obix:Weekday Contract is a standardized enum for the days of the week:

<enum href="obix:Weekday" range="#Range">

  <list href="#Range" is="obix:Range">

    <obj name="sunday" />

    <obj name="monday" />

    <obj name="tuesday" />

    <obj name="wednesday" />

    <obj name="thursday" />

    <obj name="friday" />

    <obj name="saturday" />

  </list>

</enum>

11.4 Month

The obix:Month Contract is a standardized enum for the months of the year:

<enum href="obix:Month" range="#Range">

  <list href="#Range" is="obix:Range">

    <obj name="january" />

    <obj name="febuary" />

    <obj name="march" />

    <obj name="april" />

    <obj name="may" />

    <obj name="june" />

    <obj name="july" />

    <obj name="august" />

    <obj name="september" />

    <obj name="october"  />

    <obj name="november" />

    <obj name="december" />

  </list>

</enum>

11.5 Units

Representing units of measurement in software is a thorny issue. OBIX provides a unit framework for mathematically defining units within the object model. An extensive database of predefined units is also provided.

All units measure a specific quantity or dimension in the physical world. Most known dimensions can be expressed as a ratio of the seven fundamental dimensions:  length, mass, time, temperature, electrical current, amount of substance, and luminous intensity. These seven dimensions are represented in the [SI Units] system respectively as kilogram (kg), meter (m), second (sec), Kelvin (K), ampere (A), mole (mol), and candela (cd).

The obix:Dimension Contract defines the ratio of the seven SI units using a positive or negative exponent: 

<obj href="obix:Dimension">

  <int name="kg"  val="0"/>

  <int name="m"   val="0"/>

  <int name="sec" val="0"/>

  <int name="K"   val="0"/>

  <int name="A"   val="0"/>

  <int name="mol" val="0"/>

  <int name="cd"  val="0"/>

</obj>

A Dimension Object contains zero or more ratios of kg, m, sec, K, A, mol, or cd. Each of these ratio maps to the exponent of that base SI unit. If a ratio is missing then the default value of zero is implied. For example acceleration is m/s2, which would be encoded in OBIX as:

<obj is="obix:Dimension">

  <int name="m"   val="1"/>

  <int name="sec" val="-2"/>

</obj>

 

Units with equal dimensions are considered to measure the same physical quantity. This is not always precisely true, but is good enough for practice. This means that units with the same dimension are convertible. Conversion can be expressed by specifying the formula used to convert the unit to the 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 m2·kg·s-2. The kilojoule is 1000 joules and the watt-hour is 3600 joules. Most units can be mathematically converted to their normalized unit and to other units using the linear equations:

unit = dimension · scale + offset

toNormal = scalar · scale + offset

fromNormal = (scalar - offset) / scale

toUnit = fromUnit.fromNormal( toUnit.toNormal(scalar) )

There are some units which don’t fit this model including logarithm units and units dealing with angles. But this model provides a practical solution for most problem spaces. Units which don’t fit this model SHOULD use a dimension where every exponent is set to zero. Applications SHOULD NOT attempt conversions on these types of units.

The obix:Unit Contract defines a unit including its dimension and its toNormal equation:

<obj href="obix:Unit">

  <str  name="symbol"/>

  <obj  name="dimension" is="obix:Dimension"/>

  <real name="scale" val="1"/>

  <real name="offset" val="0"/>

</obj>

The unit element contains symbol, dimension, scale, and offset sub-Objects, as described in the 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.

Table 11-1. OBIX Unit composition.

The display attribute SHOULD be used to provide a localized full name for the unit based on the Client’s locale. If the display attribute is omitted, Clients SHOULD use symbol for display purposes.

 

An example for the predefined unit for kilowatt:

<obj href="obix:units/kilowatt" display="kilowatt">

  <str name="symbol" val="kW"/>

  <obj name="dimension">

    <int name="m" val="2"/>

    <int name="kg" val="1"/>

    <int name="sec" val="-3"/>

  </obj>

  <real name="scale" val="1000"/>

</obj>

Automatic conversion of units is considered a localization issue.

12 Watches

A key requirement of OBIX is access to real-time information. OBIX is designed to enable Clients to efficiently receive access to rapidly changing data. However, Clients should not be required to implement web Servers or expose a well-known IP address. In order to address this problem, OBIX provides a model for event propagation called Watches.

The Implicit Contract for Watch is described in the following lifecycle:

Watches allow a Client to maintain a real-time cache of the current state of one or more Objects. They are also used to access an event stream from a feed Object. Watches also serve as the standardized mechanism for managing per-Client state on the Server via leases.

12.1 Client Polled Watches

When the underlying binding does not allow the Server to send unsolicited messages, the Watch must be periodically polled by the Client.  The Implicit Contract for Watch in this scenario is extended as follows:

12.2 Server Pushed Watches

Some bindings, for example the [OBIX WebSocket] binding, may allow unsolicited transmission by either the Client or the Server.  If this is possible the standard Implicit Contract for Watch behavior is extended as follows:

·         Change events are sent by the Server directly to the Client as unsolicited updates.

·         The lease time property of the Watch MUST NOT be used for Server automatic removal of the Watch.  The Watch SHOULD remain active without the need for the Client to invoke the pollChanges or pollRefresh operations.

·         The Watch MUST be removed by the Server upon termination of the underlying session between the Client and Server, in addition to the normal removal upon explicit Client request.

·         The Server MUST return an empty list upon invocation of the pollChanges operation.

Watches used in Servers that can push events MUST provide three additional properties for configuring the Watch behavior:

·         bufferDelay: The implicit contract for bufferDelay is the period of time for which any events on watched objects will be buffered before being sent by the Server in an update. Clients must be able to regulate the flow of messages from the Server. A common scenario is an OBIX Client application on a mobile device where the bandwidth usage is important; for example, a Server sending updates every 50 milliseconds as a sensor value jitters around will cause problems. On the other hand, Server devices may be constrained in terms of the available space for buffering changes. Servers are free to set a maximum value on bufferDelay through the max Facet to constrain the maximum delay before the Server will report events.

·         maxBufferedEvents: Servers may also use the maxBufferedEvents property to indicate the maximum number of events that can be retained before the buffer must be sent to the Client to avoid missing events.

·         bufferPolicy: This enum property defines the handling of the buffer on the Server side when further events occur while the buffer is full. A value of violate means that the bufferDelay property is violated and the events are sent, allowing the buffer to be emptied.  A value of lifo (last-in-first-out) means that the most recently added buffer event is replaced with the new event.  A value of fifo (first-in-first-out) means that the oldest buffer event is dropped to make room for the new event.

·         NOTE: A Server using a bufferPolicy of either lifo or fifo will not send events when a buffer overrun occurs, and this means that some events will not be received by the Client.  It is up to the Client and Server to negotiate appropriate values for these three properties to ensure that events are not lost.

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

12.3 WatchService

The WatchService Object provides a well-known URI as the factory for creating new Watches. The WatchService URI is available directly from the Lobby Object. The Contract for WatchService:

<obj href="obix:WatchService">

  <op name="make" in="obix:Nil" out="obix:Watch"/>

</obj>

The make operation returns a new empty Watch Object as an output. The href of the newly created Watch Object can then be used for invoking operations to populate and poll the data set.

12.4 Watch

The Watch Object is used to manage a set of Objects which are subscribed by Clients to receive the latest events. The Explicit Contract definitions are:

<obj href="obix:Watch">

  <reltime name="lease" min="PT0S" writable="true"/>

  <reltime name="bufferDelay" min="PT0S" writable="true" null="true"/>

  <int name="maxBufferedEvents" null="true"/>

  <enum name="bufferPolicy" is="obix:WatchBufferPolicy" null="true"/>

  <op name="add"    in="obix:WatchIn" out="obix:WatchOut"/>

  <op name="remove" in="obix:WatchIn"/>

  <op name="pollChanges" out="obix:WatchOut"/>

  <op name="pollRefresh" out="obix:WatchOut"/>

  <op name="delete"/>

</obj>

 

<enum href="obix:WatchBufferPolicy" range="#Range">

  <list href="#Range" is="obix:Range">

    <obj name="violate" />

    <obj name="lifo" />

    <obj name="fifo" />

  </list>

</enum>

 

<obj href="obix:WatchIn">

  <list name="hrefs" of="obix:WatchInItem"/>

</obj>

 

<uri href="obix:WatchInItem">

  <obj name="in"/>

</uri>

 

<obj href="obix:WatchOut">

  <list name="values" of="obix:obj"/>

</obj>

Many of the Watch operations use two Contracts: obix:WatchIn and obix:WatchOut. The Client identifies Objects to add and remove from the poll list via WatchIn. This Object contains a list of URIs. Typically these URIs SHOULD be Server relative.

The Server responds to add, pollChanges, and pollRefresh operations via the WatchOut Contract. This Object contains the list of subscribed Objects -  each Object MUST specify an href URI using the exact same string as the URI identified by the Client in the corresponding WatchIn. Servers MUST NOT perform any case conversions or normalization on the URI passed by the Client. This allows Client software to use the URI string as a hash key to match up Server responses.

12.4.1 Watch.add

Once a Watch has been created, the Client can add new Objects to the Watch using the add operation.  The Objects returned are required to specify an href using the exact string representation input by the Client. If any Object cannot be processed, then a partial failure SHOULD be expressed by returning an err Object with the respective href. Subsequent URIs MUST NOT be affected by the failure of one invalid URI. The add operation MUST never return Objects not explicitly included in the input URIs (even if there are already existing Objects in the watch list). No guarantee is made that the order of Objects in WatchOut matches the order in of URIs in WatchIn – Clients must use the URI as a key for matching.

Note that the URIs supplied via WatchIn may include an optional in parameter. This parameter is only used when subscribing a Watch to a feed Object. Feeds also differ from other Objects in that they return a list of historic events in WatchOut. Feeds are discussed in detail in Section12.6.

It is invalid to add an op’s href to a Watch; the Server MUST report an err.

If an attempt is made to add a URI to a Watch which was previously already added, then the Server SHOULD return the current Object’s value in the WatchOut result, but treat poll operations as if the URI was only added once – polls SHOULD only return the Object once. If an attempt is made to add the same URI multiple times in the same WatchIn request, then the Server SHOULD only return the Object once.

12.4.1.1 Watch Object URIs

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

12.4.2 Watch.remove

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

12.4.3 Watch.pollChanges

Clients SHOULD periodically poll the Server using the pollChanges operation. This operation returns a list of the subscribed Objects which have changed. Servers SHOULD only return the Objects which have been modified since the last poll request for the specific Watch. As with add, every Object MUST specify an href using the exact same string representation the Client passed in the original add operation. The entire extent of the Object SHOULD be returned to the Client if any one thing inside the extent has changed on the Server side.

Invalid URIs MUST never be included in the response (only in add and pollRefresh). An exception to this rule is when an Object which is valid is removed from the URI space. Servers SHOULD indicate an Object has been removed via an err with the BadUriErr Contract.

12.4.4 Watch.pollRefresh

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

12.4.5 Watch.lease

All Watches have a lease time, specified by the lease child. If the lease time elapses without the Client initiating a request on the Watch, and the Watch is a Client-polled Watch, then the Server MAY expire the Watch. Every new poll request resets the lease timer. So as long as the Client polls at least as often as the lease time, the Server SHOULD maintain the Watch. The following requests SHOULD reset the lease timer: read of the Watch URI itself or invocation of the add, remove, pollChanges, or pollRefresh operations.

Clients may request a different lease time by writing to the lease Object (requires Servers to assign an href to the lease child). The Server is free to honor the request, cap the lease within a specific range, or ignore the request. In all cases the write request will return a response containing the new lease time in effect.

Servers SHOULD report expired Watches by returning an err Object with the BadUriErr Contract. As a general principle Servers SHOULD honor Watches until the lease runs out (for Client-polled Watches) or the Client explicitly invokes delete. However, Servers are free to cancel Watches as needed (such as power failure) and the burden is on Clients to re-establish a new Watch.

12.4.6 Watch.delete

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

12.5 Watch Depth

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

12.6 Feeds

Servers may expose event streams using the feed Object. The event instances are typed via the Feed’s of attribute. Clients subscribe to events by adding the Feed’s href to a Watch, optionally passing an input parameter which is typed via the Feed’s in attribute. The Object returned from Watch.add is a list of historic events (or the empty list if no event history is available). Subsequent calls to pollChanges return the list of events which have occurred since the last poll.

Let’s consider a simple example for an Object which fires an event when its geographic location changes:

<obj href="/car/">

  <feed href="moved" of="/def/Coordinate"/>

<obj>

 

<obj href="/def/Coordinate">

  <real name="lat"/>

  <real name="long"/>

</obj>

The Client subscribes to the moved event Feed by adding “/car/moved” to a Watch. The WatchOut will include the list of any historic events which have occurred up to this point in time. If the Server does not maintain an event history this list will be empty:

<obj is="obix:WatchIn">

  <list name="hrefs">

    <uri val="/car/moved" />

  </list>

</obj>

 

<obj is="obix:WatchOut">

  <list name="values">

    <feed href="/car/moved" of="/def/Coordinate/" />  <!-- empty history -->

  </list>

</obj>

Now every time the Client pollChanges for the Watch, the Server will return the list of event instances which have accumulated since the last poll:

<obj is="obix:WatchOut">

  <list name="values">

    <feed href="/car/moved" of="/def/Coordinate">

      <obj>

        <real name="lat"  val="37.645022"/>

        <real name="long" val="-77.575851"/>

      </obj>

      <obj>

        <real name="lat"  val="37.639046"/>

        <real name="long" val="-77.61872"/>

      </obj>

    </feed>

  </list>

</obj>

Note the Feed’s of attribute works just like the list’s of attribute. The children event instances are assumed to inherit the Contract defined by of unless explicitly overridden. If an event instance does override the of Contract, then it MUST be Contract compatible. Refer to the rules defined in Section 7.8.

Invoking a pollRefresh operation on a Watch with a Feed that has an event history, SHOULD return all the historical events as if the pollRefresh was an add operation. If an event history is not available, then pollRefresh SHOULD act like a normal pollChanges and just return the events which have occurred since the last poll.

13 Points

Anyone familiar with automation systems immediately identifies with the term Point (sometimes called tags in the industrial space). Although there are many different definitions, generally points map directly to a sensor or actuator (called Hard Points). Sometimes a Point is mapped to a configuration variable such as a software setpoint (called Soft Points). In some systems Point is an atomic value, and in others it encapsulates a great deal of status and configuration information.

OBIX allows an integrator to normalize the representation of Points without forcing an impedance mismatch on implementers trying to make their native system OBIX accessible. To meet this requirement, OBIX defines a low level abstraction for Point - simply one of the primitive value types with associated status information. Point is basically just a marker Contract used to tag an Object as exhibiting “Point” semantics:

<obj href="obix:Point"/>     

This Contract MUST only be used with the value primitive types: bool, real, enum, str, abstime, and reltime. Points SHOULD use the status attribute to convey quality information. This Table specifies 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"/>

Table 13-1. Base Point types.

13.1 Writable Points

Different control systems handle Point writes using a wide variety of semantics. Sometimes a Client desires to write a Point at a specific priority level. Sometimes the Client needs to override a Point for a limited period of time, after which the Point falls back to a default value. The OBIX specification does not attempt to impose a specific model on implementers. Rather OBIX provides a standard WritablePoint Contract which may be extended with additional mixins to handle special cases. WritablePoint defines write as an operation which takes a WritePointIn structure containing the value to write. The Contracts are:

<obj href="obix:WritablePoint" is="obix:Point">

  <op name="writePoint" in="obix:WritePointIn" out="obix:Point"/>

</obj>

 

<obj href="obix:WritePointIn">

  <obj name="value"/>

</obj>

 

It is implied that the value passed to writePoint MUST match the type of the Point. For example if WritablePoint is used with an enum, then writePoint MUST pass an enum for the value.

14 History

Most automation systems have the ability to persist periodic samples of point data to create a historical archive of a point’s value over time. This feature goes by many names including logs, trends, or histories. In OBIX, a history is defined as a list of time stamped point values. The following features are provided by 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

Table 14-1. Features of OBIX Histories.

14.1 History Object

Any Object which wishes to expose itself as a standard OBIX history implements the obix:History Contract:

<obj href="obix:History">

  <int     name="count"     min="0" val="0"/>

  <abstime name="start"     null="true"/>

  <abstime name="end"       null="true"/>

  <str     name="tz"        null="true"/>

  <obj     name="prototype" null="true"/>

  <enum    name="collection" null=true" range="obix:HistoryCollection"/>

  <list    name="formats"   of="obix:str" null="true"/>

  <op      name="query"     in="obix:HistoryFilter" out="obix:HistoryQueryOut"/>

  <feed    name="feed"      in="obix:HistoryFilter" of="obix:HistoryRecord"/>

  <op      name="rollup"    in="obix:HistoryRollupIn" out="obix:HistoryRollupOut"/>

  <op      name="append"    in="obix:HistoryAppendIn" out="obix:HistoryAppendOut"/>

</obj>

 

<list href="obix:HistoryCollection" is="obix:Range">

  <obj name="interval" displayName="Interval"/>

  <obj name="cov" displayName="Change of Value"/>

  <obj name="triggered" displayName="Triggered"/>

</list>

The child properties of obix:History are:

 

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).

collection

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

Table 14-2. Properties of obix:History.

An example of a history which contains an hour of 15 minute temperature data:

<obj href="http://x/outsideAirTemp/history/" is="obix:History">

  <int     name="count"  val="5"/>

  <abstime name="start"  val="2005-03-16T14:00:00-05:00" tz="America/New_York"/>

  <abstime name="end"    val="2005-03-16T15:00:00-05:00" tz="America/New_York"/>

  <str     name="tz"     val="America/New_York"/>

  <list    name="formats" of="obix:str">

    <str val="text/csv"/>

  </list>

  <op      name="query"  href="query"/>

  <op      name="rollup" href="rollup"/>

</obj>

14.2 History Queries

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

14.2.1 HistoryFilter

The History.query input Contract:

<obj href="obix:HistoryFilter">

  <int     name="limit"        null="true"/>

  <abstime name="start"        null="true"/>

  <abstime name="end"          null="true"/>

  <str     name="format"       null="true"/>

</obj>

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.

Table 14-3. Properties of obix:HistoryFilter.

14.2.2 HistoryQueryOut

The History.query output Contract:

<obj href="obix:HistoryQueryOut">

  <int     name="count" min="0" val="0"/>

  <abstime name="start" null="true"/>

  <abstime name="end"   null="true"/>

  <list    name="data"  of="obix:HistoryRecord" null="true"/>

  <uri     name="dataRef" null="true"/>

</obj>

Just like History, every HistoryQueryOut returns count, start, and end. But unlike History, these values are for the query result, not the entire history. The actual history data is stored as a list of HistoryRecords in the data field. Remember that child order is not guaranteed in OBIX, therefore it might be common to have count after data. The start, end, and data HistoryRecord timestamps MUST have a timezone which matches History.tz.

When using a Client-requested format, the Server MUST provide a URI that can be followed by the Client to obtain the history data in the alternate format.  The exact definition of this format is out of scope of this specification, but SHOULD be agreed upon by both the Client and Server.

14.2.3 HistoryRecord

The HistoryRecord Contract specifies a record in a history query result:

<obj href="obix:HistoryRecord">

  <abstime name="timestamp" null="true"/>

  <obj     name="value"     null="true"/>

</obj>

Typically the value SHOULD be one of the value types used with obix:Point.

14.2.4 History Query Examples

Consider an example query from the “/outsideAirTemp/history” example above.

14.2.4.1 History Query as OBIX Objects

First examine how a Client and Server interact using the standard history query mechanism:

Client invoke request:

INVOKE http://x/outsideAirTemp/history/query

<obj name="in" is="obix:HistoryFilter">

  <int     name="limit" val="5"/>

  <abstime name="start" val="2005-03-16T14:00:00-05:00" tz="America/New_York"/>

</obj>

Server response:

<obj href="http://x/outsideAirTemp/history/query" is="obix:HistoryQueryOut">

  <int name="count" val="5"/>

  <abstime name="start" val="2005-03-16T14:00:00-05:00" tz="America/New_York"/>

  <abstime name="end"   val="2005-03-16T15:00:00-05:00" tz="America/New_York"/>

  <reltime name="interval" val="PT15M"/>

  <list name="data" of="#RecordDef obix:HistoryRecord">

    <obj> <abstime name="timestamp" val="2005-03-16T14:00:00-05:00"/>

          <real name="value" val="40"/> </obj>

    <obj> <abstime name="timestamp"  val="2005-03-16T14:15:00-05:00"/>

          <real name="value" val="42"/> </obj>

    <obj> <abstime name="timestamp" val="2005-03-16T14:30:00-05:00"/>

          <real name="value" val="43"/> </obj>

    <obj> <abstime name="timestamp" val="2005-03-16T14:45:00-05:00"/>

          <real name="value" val="47"/> </obj>

    <obj> <abstime name="timestamp" val="2005-03-16T15:00:00-05:00"/>

          <real name="value" val="44"/> </obj>

  </list>

  <obj href="#RecordDef" is="obix:HistoryRecord">

    <abstime name="timestamp" tz="America/New_York"/>

    <real name="value" unit="obix:units/fahrenheit"/>

  </obj>

</obj>

Note in the example above how the data list uses a document local Contract to define Facets common to all the records (although the Contract List must still be flattened).

14.2.4.2 History Query as Preformatted List

Now consider how this might be done in a more compact format.  The Server in this case is able to return the history data as a CSV list.

Client invoke request:

INVOKE http://myServer/obix/outsideAirTemp/history/query

<obj name="in" is="obix:HistoryFilter">

  <int     name="limit" val="5"/>

  <abstime name="start" val="2005-03-16T14:00:00-05:00" tz="America/New_York"/>

  <str name="format" val="text/csv"/>

</obj>

Server response:

<obj href="http://myServer/obix/outsideAirTemp/history/query" is="obix:HistoryQueryOut">

  <int name="count" val="5"/>

  <abstime name="start" val="2005-03-16T14:00:00-05:00" tz="America/New_York"/>

  <abstime name="end"   val="2005-03-16T15:00:00-05:00" tz="America/New_York"/>

  <uri name="dataRef" val="http://x/outsideAirTemp/history/query?text/csv"/>

</obj>

 

Client then reads the dataRef URI:

GET http://x/outsideAirTemp/history/query?text/csv

Server response:

2005-03-16T14:00:00-05:00,40

2005-03-16T14:15:00-05:00,42

2005-03-16T14:30:00-05:00,43

2005-03-16T14:45:00-05:00,47

2005-03-16T15:00:00-05:00,44

Note that the Client’s second request is NOT an OBIX request, and the subsequent Server response is NOT an OBIX document, but just arbitrarily formatted data as requested by the Client – in this case text/csv.  Also it is important to note that this is simply an example.  While the usage of the format and dataRef properties is normative, the usage of the text/csv MIME type and how the data is actually presented is purely non-normative.  It is not intended to suggest CSV as a mechanism for how the data should be formatted, as that is an agreement to be made between the Client and Server. The Server and Client are free to use any agreed-upon format, for example, one where the timestamps are inferred rather than repeated, for maximum brevity.

14.3 History Rollups

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

14.3.1 HistoryRollupIn

The History.rollup input Contract extends HistoryFilter to add an interval parameter:

<obj href="obix:HistoryRollupIn" is="obix:HistoryFilter">

  <reltime name="interval"/>

</obj>

14.3.2 HistoryRollupOut

The History.rollup output Contract:

<obj href="obix:HistoryRollupOut">

  <int     name="count" min="0" val="0"/>

  <abstime name="start" null="true"/>

  <abstime name="end"   null="true"/>

  <list name="data" of="obix:HistoryRollupRecord"/>

</obj>

The HistoryRollupOut Object looks very much like HistoryQueryOut except it returns a list of HistoryRollupRecords, rather than HistoryRecords. Note: unlike HistoryQueryOut, the start for HistoryRollupOut is exclusive, not inclusive. This issue is discussed in greater detail next. The start, end, and data HistoryRollupRecord timestamps MUST have a timezone which matches History.tz.

14.3.3 HistoryRollupRecord

A history rollup returns a list of HistoryRollupRecords:

<obj href="obix:HistoryRollupRecord"> 

  <abstime name="start"/>

  <abstime name="end"  />

  <int  name="count"/>

  <real name="min" />

  <real name="max" />

  <real name="avg" />

  <real name="sum" />

</obj>

The children are defined in the Table below:

Property

Description

start

The exclusive start time of the record’s rollup interval

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

Table 14-4. Properties of obix:HistoryRollupRecord.

14.3.4 Rollup Calculation

The best way to understand how rollup calculations work is through an example. Let’s consider a history of meter data which contains two hours of 15 minute readings of kilowatt values:

<obj is="obix:HistoryQueryOut">

  <int     name="count" val="9">

  <abstime name="start" val="2005-03-16T12:00:00+04:00" tz="Asia/Dubai"/>

  <abstime name="end"   val="2005-03-16T14:00:00+04:00" tz="Asia/Dubai"/>

  <list name="data" of="#HistoryDef obix:HistoryRecord">

    <obj> <abstime name="timestamp" val="2005-03-16T12:00:00+04:00"/>

          <real name="value" val="80"> </obj>

    <obj> <abstime name="timestamp" val="2005-03-16T12:15:00+04:00"/>

          <real name="value" val="82"></obj>

    <obj> <abstime name="timestamp" val="2005-03-16T12:30:00+04:00"/>

          <real name="value" val="90"> </obj>

    <obj> <abstime name="timestamp" val="2005-03-16T12:45:00+04:00"/>

          <real name="value" val="85"> </obj>

    <obj> <abstime name="timestamp" val="2005-03-16T13:00:00+04:00"/>

          <real name="value" val="81"> </obj>

    <obj> <abstime name="timestamp" val="2005-03-16T13:15:00+04:00"/>

          <real name="value" val="84"> </obj>

    <obj> <abstime name="timestamp" val="2005-03-16T13:30:00+04:00"/>

          <real name="value" val="91"> </obj>

    <obj> <abstime name="timestamp" val="2005-03-16T13:45:00+04:00"/> 

          <real name="value" val="83"> </obj>

    <obj> <abstime name="timestamp" val="2005-03-16T14:00:00+04:00"/>

          <real name="value" val="78"> </obj>

  </list>

  <obj href="#HistoryRecord" is="obix:HistoryRecord">

    <abstime name="timestamp" tz="Asia/Dubai"/>

    <real name="value" unit="obix:units/kilowatt"/>

  <obj>

</obj>

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 result would be:

<obj is="obix:HistoryRollupOut obix:HistoryQueryOut">

  <int     name="count" val="2">

  <abstime name="start" val="2005-03-16T12:00:00+04:00 tz="Asia/Dubai"/>

  <abstime name="end"   val="2005-03-16T14:00:00+04:00" tz="Asia/Dubai"/>

  <list name="data" of="obix:HistoryRollupRecord">

    <obj>

      <abstime name="start" val="2005-03-16T12:00:00+04:00"

               tz="Asia/Dubai"/>

      <abstime name="end"   val="2005-03-16T13:00:00+04:00"

               tz="Asia/Dubai"/>

      <int  name="count" val="4"    />

      <real name="min"   val="81"   />

      <real name="max"   val="90"   />

      <real name="avg"   val="84.5" />

      <real name="sum"   val="338"  />

    </obj>

    <obj>

      <abstime name="start" val="2005-03-16T13:00:00+04:00"                               

               tz="Asia/Dubai"/>

      <abstime name="end"   val="2005-03-16T14:00:00+04:00"

               tz="Asia/Dubai"/>

      <int  name="count" val="4"   />

      <real name="min"   val="78"  />

      <real name="max"   val="91"  />

      <real name="avg"   val="84"  />

      <real name="sum"   val="336" />

    </obj>

  </list>

</obj>

The first item to notice is that the first raw record of 80kW was never used in the rollup. This is because start time is always exclusive. The reason start time has to be exclusive is because discrete samples are being summarized into a contiguous time range. It would be incorrect to include a record in two different rollup intervals!  To avoid this problem, start time MUST always be exclusive and end time MUST always 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

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

14.4 History Feeds

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

14.5 History Append

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

14.5.1 HistoryAppendIn

The History.append input Contract:

<obj href="obix:HistoryAppendIn">

  <list name="data" of="obix:HistoryRecord"/>

</obj>

The HistoryAppendIn is a wrapper for the list of HistoryRecords to be inserted into the History. The HistoryRecords SHOULD use a timestamp which matches History.tz. If the timezone doesn’t match, then the Server MUST normalize to its configured timezone based on absolute time. The HistoryRecords in the data list MUST be sorted by timestamp from oldest to newest, and MUST not include a timestamp equal to or older than History.end.

14.5.2 HistoryAppendOut

The History.append output Contract:

<obj href="obix:HistoryAppendOut">

  <int     name="numAdded"/>

  <int     name="newCount"/>

  <abstime name="newStart" null="true"/>

  <abstime name="newEnd"   null="true"/>

</obj>

The output of the append operation returns the number of new records appended to the History and the new total count, start time, and end time of the entire History. The newStart and newEnd timestamps MUST have a timezone which matches History.tz.

15 Alarming

OBIX  specifies a normalized model to query, Watch, and acknowledge alarms. In OBIX, an alarm indicates a condition which requires notification of either a user or another application. In many cases an alarm requires acknowledgement, indicating that someone (or something) has taken action to resolve the alarm condition. The typical lifecycle of an alarm is:

  1. Source Monitoring: Algorithms in a Server monitor an alarm source. An alarm source is an Object with an href which has the potential to generate an alarm. Example of alarm sources might include sensor points (this room is too hot), hardware problems (disk is full), or applications (building is consuming too much energy at current energy rates)
  2. Alarm Generation:  If the algorithms in the Server detect that an alarm source has entered an alarm condition, then an alarm record is generated. Every alarm is uniquely identified using an href and represented using the obix:Alarm Contract. The transition to an alarm state is called off-normal.
  3. To Normal: Many alarm sources are said to be stateful - eventually the alarm source exits the alarm state, and is said to return to-normal. Stateful alarms implement the obix:StatefulAlarm Contract. When the alarm source transitions to normal, the alarm’s normalTimestamp is updated.
  4. Acknowledgement:  A common requirement for alarming is that a user or application acknowledges that they have processed an alarm. These alarms implement the obix:AckAlarm Contract. When the alarm is acknowledged, the alarm’s ackTimestamp and ackUser are updated.

15.1 Alarm States

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.

Table 15-1. Alarm states in OBIX.

Either of these states may transition independent of the other. For example an alarm source can return to normal before or after an alarm has been acknowledged. Furthermore it is not uncommon to transition between normal and off-normal multiple times generating several alarm records before any acknowledgements occur.

Note not all alarms have state. An alarm which implements neither StatefulAlarm nor the AckAlarm Contracts is completely stateless – these alarms merely represent event. An alarm which implements StatefulAlarm but not AckAlarm will have an in-alarm state, but not acknowledgement state. Conversely an alarm which implements AckAlarm but not StatefulAlarm will have an acknowledgement state, but not in-alarm state.

15.1.1 Alarm Source

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

15.1.2 StatefulAlarm and AckAlarm

An Alarm record is used to summarize the entire lifecycle of an alarm event. If the alarm implements StatefulAlarm it tracks transition from off-normal back to normal. If the alarm implements AckAlarm, then it also summarizes the acknowledgement. This allows for four discrete alarm states, which are 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

Table 15-2. Alarm lifecycle states in OBIX.

15.2 Alarm Contracts

15.2.1 Alarm

The core Alarm Contract is:

<obj href="obix:Alarm"> 

  <ref name="source"/>

  <abstime name="timestamp"/>

</obj>

 

The child Objects are:

15.2.2 StatefulAlarm

Alarms which represent an alarm state which may transition back to normal SHOULD implement the StatefulAlarm Contract:

<obj href="obix:StatefulAlarm" is="obix:Alarm"> 

  <abstime name="normalTimestamp" null="true"/>

</obj>

The child Object is:

15.2.3 AckAlarm

Alarms which support acknowledgment SHOULD implement the AckAlarm Contract:

<obj href="obix:AckAlarm" is="obix:Alarm"> 

  <abstime name="ackTimestamp" null="true"/>

  <str name="ackUser" null="true"/>

  <op name="ack" in="obix:AckAlarmIn" out="obix:AckAlarmOut"/>

</obj>

 

<obj href="obix:AckAlarmIn"> 

  <str name="ackUser" null="true"/>

</obj>

 

<obj href="obix:AckAlarmOut"> 

  <obj name="alarm" is="obix:AckAlarm obix:Alarm"/>

</obj>

The child Objects are:

The ack operation is used to programmatically acknowledge the alarm. The Client may optionally specify an ackUser string via AckAlarmIn. However, the Server is free to ignore this field depending on security conditions. For example a highly trusted Client may be allowed to specify its own ackUser, but a less trustworthy Client may have its ackUser predefined based on the authentication credentials of the protocol binding. The ack operation returns an AckAlarmOut which contains the updated alarm record. Use the Lobby.batch operation to efficiently acknowledge a set of alarms.

15.2.4 PointAlarms

It is very common for an alarm source to be an obix:Point. The PointAlarm Contract provides a normalized way to report the Point whose value caused the alarm condition:

<obj href="obix:PointAlarm" is="obix:Alarm">

  <obj name="alarmValue"/>

</obj>

The alarmValue Object SHOULD be one of the value types defined for obix:Point in Section 13.

15.3 AlarmSubject

Servers which implement OBIX alarming MUST provide one or more Objects which implement the AlarmSubject Contract. The AlarmSubject Contract provides the ability to categorize and group the sets of alarms a Client may discover, query, and watch. For instance a Server could provide one AlarmSubject for all alarms and other AlarmSubjects based on priority or time of day. The Contract for AlarmSubject is:

<obj href="obix:AlarmSubject">

  <int     name="count"  min="0" val="0"/>

  <op      name="query" in="obix:AlarmFilter" out="obix:AlarmQueryOut"/>

  <feed    name="feed"  in="obix:AlarmFilter" of="obix:Alarm"/>

</obj>

 

<obj href="obix:AlarmFilter">

  <int     name="limit"  null="true"/>

  <abstime name="start"  null="true"/>

  <abstime name="end"    null="true"/>

</obj>

 

<obj href="obix:AlarmQueryOut">

  <int     name="count" min="0" val="0"/>

  <abstime name="start" null="true"/>

  <abstime name="end"   null="true"/>

  <list    name="data"  of="obix:Alarm"/>

</obj>

The AlarmSubject follows the same design pattern as History. The AlarmSubject specifies the active count of alarms;  however, unlike History it does not provide the start and end bounding timestamps. It contains a query operation to read the current list of alarms with an AlarmFilter to filter by time bounds. AlarmSubject also contains a Feed Object which may be used to subscribe to the alarm events.

15.4 Alarm Feed Example

The following example illustrates how a Feed works with this AlarmSubject:

<obj is="obix:AlarmSubject" href="/alarms/">

  <int  name="count" val="2"/>

  <op   name="query" href="query"/>

  <feed name="feed"  href="feed" />

</obj>

The Server indicates it has two open alarms under the specified AlarmSubject. If a Client were to add the AlarmSubject’s Feed to a watch:

<obj is="obix:WatchIn">

 <list name="hrefs"/>

  <uri val="/alarms/feed">

    <obj name="in" is="obix:AlarmFilter">

      <int name="limit" val="25"/>

    </obj>

  </uri>

 </list>

</obj>

 

<obj is="obix:WatchOut">

 <list name="values">

   <feed href="/alarms/feed" of="obix:Alarm">

    <obj href="/alarmdb/528" is="obix:StatefulAlarm obix:PointAlarm obix:Alarm">

      <ref name="source" href="/airHandlers/2/returnTemp"/>

      <abstime name="timestamp" val="2006-05-18T14:20:00Z"/>

      <abstime name="normalTimestamp"  null="true"/>

      <real name="alarmValue" val="80.2"/>

    </obj>

    <obj href="/alarmdb/527" is="obix:StatefulAlarm obix:PointAlarm obix:Alarm">

      <ref name="source" href="/doors/frontDoor"/>

      <abstime name="timestamp" val="2006-05-18T14:18:00Z"/>

      <abstime name=" normalTimestamp" null="true"/>

      <real name="alarmValue" val="true"/>

    </obj>

  </feed>

 </list>

</obj>

The Watch returns the historic list of alarm events which is two open alarms. The first alarm indicates an out of bounds condition in AirHandler-2’s return temperature. The second alarm indicates that the system has detected that the front door has been propped open.

The system next detects that the front door is closed, and the alarm point transitions to the normal state. When the Client next polls the Watch the alarm would be included in the Feed list (along with any additional changes or new alarms not shown here):

<obj is="obix:WatchOut">

 <list name="values">

   <feed href="/alarms/feed" of="obix:Alarm">>

    <obj href="/alarmdb/527" is="obix:StatefulAlarm obix:PointAlarm obix:Alarm">

      <ref name="source" href="/doors/frontDoor"/>

      <abstime name="timestamp" val="2006-05-18T14:18:00Z"/>

      <abstime name=" normalTimestamp" val="2006-05-18T14:45:00Z"/>

      <real name="alarmValue" val="true"/>

    </obj>

   </feed>

 </list>

</obj>

16 Security

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

Table 16-1. Security concepts for OBIX.

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

16.1 Error Handling

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

16.2 Permission-based Degradation

Servers SHOULD strive to present their object model to a Client based on the privileges available to the Client. This behavior is called permission based degradation. The following rules summarize effective permission based degradation:

  1. If an Object cannot be read, then it SHOULD NOT be discoverable through Objects which are available.
  2. Servers SHOULD attempt to group standard Contracts within the same privilege level – for example don’t split obix:History’s start and end into two different security levels such that a Client might be able to read start, and not end.
  3. Servers SHOULD NOT include a Contract in an Object’s is attribute if the Contract’s children are not readable to the Client.
  4. If an Object isn’t writable, then the writable attribute SHOULD be set to false (either explicitly or through a Contract default).
  5. If an op inherited from a visible Contract cannot be invoked, then the Server SHOULD set the null attribute to true to disable it.

17 Conformance

17.1 Conditions for a Conforming OBIX Server

An implementation conforms to this specification as an OBIX Server if it meets the conditions described in the following subsections.  OBIX Servers MUST implement the OBIX Lobby Object.

17.1.1 Lobby

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

17.1.2 Tag Spaces

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

1.     The Server MUST use the tagspaces element to declare any semantic model or tag dictionary it uses.

2.     The Server MUST use the name defined in the name attribute of the uri in the tagspaces Lobby element when referencing the Tagspace.

3.     The uri MUST contain a val that provides the reference location of the semantic model or tag dictionary.

4.     If available the version of the reference MUST be included as a child str element with name ‘version’, in the uri for that Tagspace.

5.     If the version is not available, the uri MUST contain a child abstime element with the name ‘retrievedAt’ and value containing the date when the dictionary used by the Server was retrieved from the publication source.

17.1.3 Bindings

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

17.1.4 Encodings

A conformant OBIX Server implementation SHOULD support at least one of the encodings defined in the companion specification to this specification, [OBIX Encodings].  Any encodings used by the implementation MUST be listed in the Encodings section of the Server’s Lobby Object.

An implementation MUST support negotiation of the encoding to be used with a Client according to the mechanism defined for the specific binding used. A conforming binding specification MUST specify how negotiation of the encoding to be used is performed.  A conforming implementation MUST conform to the negotiation rules defined in the specification for each binding that it uses.

An implementation MUST return values according to the type representations defined in Section 4.2.

17.1.5 Contracts

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

17.2 Conditions for a Conforming OBIX Client

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

17.2.1  Bindings

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

17.2.2 Encodings

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

17.2.3 Naming

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

17.2.4 Contracts

A conformant OBIX Client implementation MUST be able to consume and use OBIX Contracts defined by OBIX Server implementations with which it interacts, according to the Contract design and semantics defined in Section 7.  A Client MUST be able to consume space-separated Contract Lists defining the implemented OBIX Contracts reported by Servers, according to the rules defined in Section 7.

17.3 Interaction with other Implementations

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

17.3.1 Unknown Elements and Attributes

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

 

Appendix A. Acknowledgments

The following individuals have participated in the creation of this specification and are gratefully acknowledged:

Participants:

Ron Ambrosio, IBM

Brad Benson, Trane

Ron Bernstein, LonMark International*

Ludo Bertsch, Continental Automated Buildings Association (CABA)

Chris Bogen, US Department of Defense

Rich Blomseth, Echelon Corporation

Anto Budiardjo, Clasma Events, Inc.

Jochen Burkhardt, IBM

JungIn Choi, Kyungwon University

David Clute, Cisco Systems, Inc.*

Toby Considine, University of North Carolina at Chapel Hill

William Cox, Individual

Robert Dolin, Echelon Corporation

Marek Dziedzic, Treasury Board of Canada, Secretariat

Brian Frank, SkyFoundry

Craig Gemmill, Tridium, Inc.

Matthew Giannini, SkyFoundry

Markus Jung, Vienna University of Technology

Christopher Kelly, Cisco Systems

Wonsuk Ko, Kyungwon University

Perry Krol, TIBCO Software Inc.

Corey Leong, Individual

Ulf Magnusson, Schneider Electric

Brian Meyers, Trane

Jeremy Roberts, LonMark International

Thorsten Roggendorf, Echelon Corporation

Anno Scholten, Individual

John Sublett, Tridium, Inc.

Dave Uden, Trane

Ron Zimmer, Continental Automated Buildings Association (CABA)*

Rob Zivney, Hirsch Electronics Corporation

 

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

(from Aaron Hansen)

Add iCalendar scheduling

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-wd05

01 Jun 10

Toby Considine

Updated to current OASIS Templates, requirements

oBIX-1-1-spec-wd06

08 Jun 10

Brad Benson

Custom facets within binary encoding

oBIX-1-1-spec-wd07

03 Mar 2013

Craig Gemmill

Update to current OASIS templates, fixes

oBIX-1-1-spec-wd08

27 Mar 2013

Craig Gemmill

Changes from feedback

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 2013

Craig Gemmill

Add CompactHistoryRecord

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-CSPRD01

11 July 2013

Paul Knight

Public Review Draft 1

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 2014

Craig Gemmill

More PR02 corrections

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-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