TOC

  1. Intro
  2. TagModel
  3. Structure
  4. TimeZones
  5. Units
  6. Grids
  7. Filters
  8. Zinc
  9. Json
    1. Overview
    2. Type Mapping
    3. Grid Format
  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
Zinc Trio

Json

Overview

JSON stands for JavaScript Object Notation. It is a plain text format commonly used for serialization of data. It is specified in RFC 4627. The JSON format is designed to support 100% fidelity with with the full Haystack type system.

Type Mapping

The following is the mapping between Haystack and JSON types:

Haystack      JSON
--------      ----
Grid          Object (specified below)
List          Array
Dict          Object
null          null
Bool          Boolean
Marker        "m:"
Remove        "-:"
NA            "z:"
Number        "n:<float> [unit]" "n:45.5" "n:73.2 °F" "n:-INF"
Ref           "r:<id> [dis]"  "r:abc-123" "r:abc-123 RTU #3"
Str           "hello" "s:hello"
Date          "d:2014-01-03"
Time          "h:23:59"
DateTime      "t:2015-06-08T15:47:41-04:00 New_York"
Uri           "u:http://project-haystack.org/"
Coord         "c:<lat>,<lng>" "c:37.545,-77.449"
XStr          "x:Type:value"

Notes:

Here is an example:

// Haystack
dis: "Site-A", site, area: 5000ft², built: 1992-01-23

// JSON
{"dis":"Site-A", "site":"m:", "area":"n:5000 ft²", "built":"d:1992-01-23"}

The Haystack and JSON models are very similiar since they both support the same core list and object/dict types. The difference is that Haystack has a richer set of scalar types such as Date, Time, Uri which are not supported directly by JSON; so we encode them as strings using a special type code prefix.

Grid Format

In addition to the flexible type mapping defined above, we have a standard mapping of Grid into JSON which is used by the REST API.

The Grid to JSON mapping is as follows:

Example:

// Zinc
ver:"3.0" projName:"test"
dis dis:"Equip Name",equip,siteRef,installed
"RTU-1",M,@153c-699a "HQ",2005-06-01
"RTU-2",M,@153c-699a "HQ",1999-07-12

// JSON
{
  "meta": {"ver":"3.0", "projName":"test"},
  "cols":[
    {"name":"dis", "dis":"Equip Name"},
    {"name":"equip"},
    {"name":"siteRef"},
    {"name":"installed"}
  ],
  "rows":[
    {"dis":"RTU-1", "equip":"m:", "siteRef":"r:153c-699a HQ", "installed":"d:2005-06-01"},
    {"dis":"RTU-2", "equip":"m:", "siteRef":"r:153c-699a HQ", "installed":"d:999-07-12"}
  ]
}

Here is another example with nested lists, dicts, and grids:

// Zinc
ver:"3.0"
type,val
"list",[1,2,3]
"dict",{dis:"Dict!" foo}
"grid",<<
  ver:"2.0"
  a,b
  1,2
  3,4
  >>
"scalar","simple string"


// JSON
{
  "meta": {"ver":"2.0"},
  "cols":[
    {"name":"type"},
    {"name":"val"}
  ],
  "rows":[
    {"type":"list", "val":["n:1", "n:2", "n:3"]},
    {"type":"dict", "val":{"dis":"Dict!", "foo":"m:"}},
    {"type":"grid", "val":{
      "meta": {"ver":"2.0"},
      "cols":[
        {"name":"b"},
        {"name":"a"}
      ],
      "rows":[
        {"b":"n:20", "a":"n:10"}
      ]
    }},
    {"type":"scalar", "val":"simple string"}
  ]
}
Zinc Trio