TagModel

Metamodel

In Project Haystack we are defining a model of building equipment and operations. But like every model, we have to use some framework for our model. Or put another way, what is the model of the model - the metamodel?

If we were building the model in a programming language like Java, the metamodel would be Java classes and our taxonomy would be defined as an object oriented class hierarchy. If using a relational database, relational schemas would be our metamodel. In oBIX the metamodel is oBIX contracts. In RDF the metamodel is subject-predicate-object triples.

It is likely that original source of our operational data is already in one of the metamodels defined above. However, the rigid structures imposed by OO class hierarchies or relational database schemes is ill suited to the domain of building automation systems where each project is essentially unique. Consider an AHU (Air Handling Unit), is there one class hierarchy which could describe every unique combination of AHU features? Since AHUs tend to be custom built-up for each facility, any one single fixed schema would be impossible to use across multiple projects.

To tackle these unique challenges, Project Haystack uses a very simple metamodel: tags. Tags are name/value pairs which may be associated with an entity like an AHU. Because tags are simple and dynamic, they can be incredibly flexible for building standardized models which are easily customized on a per-project or per-equipment basis. Furthermore the tagging model is easily integrated or layered above legacy models such as OO classes or relational schemas.

Entities

An entity is an abstraction for some physical object in the real world. Entities include sites, equipment, sensor points, weather stations, etc. In software systems, an entity might be a modeled as a record in a database, an object in a building automation system, or maybe just a row in a CSV file.

Haystack doesn't prescribe any specific design on how entities are stored or managed, rather it defines how to tag those entities with specific name/value pairs. By using a library of standardized tags we can build a taxonomy that allows semantic understanding across the industry. The end result: we can all save money on the labor intensive task of mapping data from one proprietary system to another.

If a specific definition of an entity is stored in a database, then we will use the term record or rec interchangabley with the term entity. We often the use the term rec in dicussions of the REST API where clients interact with a server database of haystack entities.

Tags

A tag is a name/value pair applied to an entity. A tag defines a fact or attribute about an entity. For example if we apply the site tag to an entity, then we are declaring that the entity represents a building. If we also add the geoAddr tag we are declaring the street address of the building.

Tag Names

Tag names are restricted to the following characters:

Must start with ASCII lower case letter (a-z)
Must contain only ASCII letters, digits, or underbar (a-z, A-Z, 0-9, _)
By convention use camel case (fooBarBaz)

Restricting tag names, ensures they may be easily used as identifiers in programming languages and databases.

Tag Kinds

A kind is one of the permitted value types of a tag. The following are the atomic scalar tag kinds:

Marker: the tag is merely a marker annotation and has no meaningful value. Marker tags are used to indicate a "type" or "is-a" relationship.
Bool: boolean "true" or "false".
NA: singleton value which represents not available for missing data
Number: integer or floating point number annotated with an optional unit of measurement.
Str: a string of Unicode characters.
Uri: a Unversial Resource Identifier.
Ref: reference to another entity. Haystack doesn't prescribe a specific identity or reference mechanism, but they should be some way to cross link entities. Also see Containment. We format refs with a leading "@" and require a specific subset of ASCII characters be used: a-z, A-Z, 0-9, underbar, colon, dash, dot, or tilde.
Bin: a binary blob with a MIME type formatted as Bin(text/plain)
Date: an ISO 8601 date as year, month, day: 2011-06-07.
Time: an ISO 8601 time as hour, minute, seconds: 09:51:27.354.

DateTime: an ISO 8601 timestamp followed by timezone name:

2011-06-07T09:51:27-04:00 New_York
2012-09-29T14:56:18.277Z UTC

Coord: geographic coordinate in latitude/longitude formatted as C(lat,lng)
XStr: extended typed string which specifies a type name a string encoding

There are three collection tag kinds:

List: list of zero or more values
Dict: an associated array of name/value tag pairs
Grid: a two dimensional table of columns and rows, see Grids

Id

The id tag is used model the unique identifier of an entity in system using a Ref value type. The scope of an entity is undefined, but must be unique with a given system or project. This identifier may be used by other entities to cross-reference using tags such as siteRef, ahuRef, etc.

Dis

The dis tag is used with all entities as the standard way to define the display text used to describe the entity. Dis values should be short (less than 30 or 40 characters), but fully descriptive of the entity.

Example

Let's look a simple example for an entity describing a site:

id: @whitehouse
dis: "White House"
site
area: 55000ft²
geoAddr: "1600 Pennsylvania Avenue NW,  Washington, DC"
tz: "New_York"
weatherRef: @weather.washington

In the example above we have an entity with seven tags: id, site, dis, area, geoAddr, tz, and weatherRef. By convention when writing examples we will list each tag on their own line or separated by a comma. The site tag has no explicit value, so it is assumed to be marker tag. The dis, geoAddr, and tz tags have string values indicated by double quotes. The area tag has a number value indicated by a scalar with unit of square feet. The weatherRef tag is a reference to another entity, which we indicate using the "@" character.

◄Intro Structure►