Toying around with a Siren description language.

describe-zetta.json

{
  "type": "api",
  "identifier": "zetta",
  "description": "The Zetta IoT API",
  "descriptors": [
    {
      "type": "class",
      "identifier": "root",
      "description": "The root resource of a Zetta API.",
      "descriptors": [
        {
          "type": "link",
          "ref": "http://rels.zettajs.io/server",
          "occurrence": "*"
        },
        {
          "type": "link",
          "ref": "http://rels.zettajs.io/peer",
          "occurrence": "*"
        },
        {
          "type": "link",
          "ref": "http://rels.zettajs.io/peer-management",
          "occurrence": "*"
        }
      ]
    },
    {
      "type": "class",
      "identifier": "server",
      "description": "A single server representation.",
      "descriptors": [
        {
          "type": "entity",
          "ref": "http://rels.zettajs.io/device",
          "description": "A list of devices attached to a server.",
          "occurrence": "*"
        },
        {
          "type": "action",
          "identifier": "query-devices",
          "description": "Query devices using the Calypso Query Language.",
          "descriptors": [
            {
              "type": "field",
              "identifier": "ql",
              "description": "The query filter."
            }
          ]
        }
      ]
    },
    {
      "type": "class",
      "identifier": "device",
      "description": "A Zetta device.",
      "descriptors": [
        {
          "type": "property",
          "identifier": "id",
          "occurrence": "1"
        },
        {
          "type": "property",
          "identifier": "type",
          "occurrence": "1"
        },
        {
          "type": "property",
          "identifier": "state",
          "occurrence": "?"
        },
        {
          "type": "link",
          "ref": "up",
          "occurrence": "1"
        }
      ]
    },
    {
      "type": "relation",
      "identifier": "http://rels.zettajs.io/server",
      "description": "An owned instance of an available Zetta server"
    },
    {
      "type": "relation",
      "identifier": "http://rels.zettajs.io/peer",
      "description": "A linked instance of an available Zetta server"
    },
    {
      "type": "relation",
      "identifier": "http://rels.zettajs.io/device",
      "description": "A Zetta device attached to a server."
    }
  ]
}