1. Intro
  2. TagModel
    1. Metamodel
    2. Entities
    3. Tags
      1. Tag Names
      2. Tag Kinds
    4. Id
    5. Dis
    6. Example
  3. Structure
  4. TimeZones
  5. Units
  6. Grids
  7. Filters
  8. Zinc
  9. Json
  10. Trio
  11. Csv
  12. Rest
  13. Ops
  14. Auth
  15. VFDs
  16. Networks
  17. Energy
  18. Zones
  19. AHUs
  20. VAVs
  21. UnitaryEquips
  22. Chillers
  23. Boilers
  24. Tanks
  25. ElecPanels
  26. Lighting
  27. Builds
  28. Bacnet
  29. ChangeLog
  30. License



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.


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.


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:

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:

There are three collection tag kinds:


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.


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.


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

id: @whitehouse
dis: "White House"
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.