The Haystack Labs WG is proposing a new first class object type called an Attribute or attr. The purpose of an attr would be to provide a method for storing infrequently changing information about another entity using standard Haystack tags to identify that information. An attrOf tag would be used in conjunction with the attr tag to reference the object the information pertains to.

An example would be documenting the rated heating capacity of a package rooftop unit.

{equip ahu rtu id:@ahu naturalGasHeating}
  {attr attrOf:@ahu heat energy max rated output val: 425kBTU}

Another example is the design max occupancy of a space.

{space room navName: “Rm 221 Meeting Rm C” area: 295ft² id:@rm221}
  {attr attrOf: @rm221 occupancy max design val: 21} 

This format will allow all the standard tags to be leveraged in describing the information the attr stores; however, as use cases evolve we anticipate the need for additional tags to be developed as well, such as design and rated tags used in the above examples.

design- Marker tag indicating the information represents the intended design, such as information from documentation such as engineered drawings.

rated- Marker tag indicating the information represents a manufacturer’s ratings, such as information from an equipment data plate or cut sheet.

Defs

def: ^attr,
doc: Object to describe and store information that rarely changes.
is: ^entity
---
def: ^attrOf
doc: Reference to the entity an ‘attr’ pertains to. 
is:  ^ref
tagOn: ^attr
of: ^entity
---
def: ^design
doc: Marker tag indicating the information represents the intended design, such as 
information from documentation such as engineered drawings.
is: ^marker
tagOn: [^attr, ^point]
---
def: ^rated
doc: Marker tag indicating the information represents a manufacturer’s ratings, 
such as information from an equipment data plate or cut sheet.
is: ^marker
tagOn: [^attr, ^point]

We welcome feedback on this new concept, if accepted the next step will be creating protos for typical use cases.

Thanks for posting this Leroy! This has been an ongoing effort within the Labs WG for several months, so its great to see it finally become an official proposal to the wider community.

I just want to add my take on the importance of this direction. For a long time we have struggled how to model equipment data which doesn't cleanly fit the point model. Its been tempting to coin a bunch of new tags you might stick on an equip such as heatEnergyMaxRatedOutput. But you can see how that is not really extensible, nor future proof. In the Haystack 4 WG we discussed at length using nested dicts in entities too. But for lots of reasons keeping entities flat like you would in a RDBMS or spreadsheet is more aligned with how Haystack is used. So with this direction we double down on two core Haystack principles: keeping entities flat and combining marker tags for consistent terminology.

I like to think of attributes as a list of marker tags + value attached to an entity via the attrOf tag. Its really a compound tag name with a value. I'm actually imagining that we will provide some special UI support for this in our product.

The next phase of this proposal is to develop a list of children prototypes which are formalized on equip and spaces to drive tooling and validation.

We have been discussing this proposal internally and a question was raised about some of the non-marker tags on sites such as area, yearBuilt, geoAddr etc. These are all basically attributes. As part of this roll out, would we want to change those non-marker (essentially meta data tags) from tags into attributes? These seems especially relevant for a compound tag such as yearBuilt.

As part of this roll out, would we want to change those non-marker (essentially meta data tags) from tags into attributes?

I think its an important issue to discuss. Here are my thoughts...

Any information model has to decide what is a first class "object" versus a scalar value. In XML you decide if something is an attribute or an element. In a RDBMS or spreadsheet you decide if something is a column or its own row.

If we take the RDMBS/Spreadsheet example I think most people would intuitively expect sites to look like this:

dis      yearBuilt  geoCity
------   ---------  -------
Site-A   1990       "Denver"
Site-B   2007       "Austin" 

In which yearBuilt and geoCity are scalar values/fields directly on the site. Beyond the intuitive sense, there are two other important factors to consider:

• performance would suffer and memory would go up to model every single scalar value as a first class entity
• it would be a very, very breaking change to backward compatibility

So I would not be in favor or modeling all scalar values as first class entities (attributes).

And for the same reasons, adding attributes opens up a can of worms. I've been thinking about performance of this feature and doubting if this is the right direction. But maybe something to discuss in person the next labs call.

I did a quick review of several standards, but did not find any formal definitions for design or rated that could be generalized, so here are my suggestions.

design - Marker tag indicating the attribute is for operating conditions, such as those used for sizing by a design engineer.

rated - Marker tag indicating the attribute is for test conditions, such as those used by a manufacturer or rating organization, for comparing different devices under the same conditions.

Here's a summary of the standards I looked at for reference, which are not exhaustive.

---

Electrical

IEEE

• IEEE 100 The Authoritative Dictionary of IEEE Standards Terms
• Taxonomy
• Thesaurus

NEMA

• ANSI/NEMA MG 1-2016, Motor and Generators

NFPA

• NEC 70-2020

---

Mechanical

AHRI / Standard 550/590

Rating Conditions. Any set of operating conditions under which a single level of performance results and which causes only that level of performance to occur.

Standard Rating Conditions. Rating Conditions used as the basis of comparison for performance characteristics.

ASHRAE

design conditions specified environmental conditions, such as temperature and light intensity, required to be produced and maintained by a system and under which the system must operate.

rated airflow the airflow rate in m3/s (cfm) at which the device is tested.

design and rated merged in https://github.com/Project-Haystack/haystack-defs/commit/84d58a161f58332b97aea7609e02520a750cc2c3.