JSON Schema

JSON Schema is a declarative language that allows you to annotate and validate JSON documents

Why JSON Schema?

There are a few drivers behind choosing JSON Schema for Connhex Resources:

• one should have a unified representation for resources. Yet this representation should be flexible enough to allow for different use cases. JSON Schema is a perfect fit for this.
• Connhex Resources should take care of everything involved in managing resource registries. Some key components are UI, validation and database schemas. JSON Schema is an appropriate basis to build solutions for all of these needs.
• JSON Schema is a standard. It's widely used and supported by many tools.

JSON Schema example

Let's see an example of modeling a device resource using JSON Schema. Suppose it could be described by the following interface:

enum DeviceType {
  Valve = 'valve',
}

interface Plant {
  name: string;
  location: string;
}

interface Tag {
  name: string;
  color: string;
}

interface Device {
  serial: string;
  type: DeviceType;
  connhexId: string;
  metadata: string;
  plant: Plant;
  tags: Tag[];
}

The corresponding JSON Schema would be:

{
  "schema": {
    "$id": "https://connhex.com/example/device.schema.json",
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "serial": {
        "type": "string",
        "title": "Serial",
        "readOnly": true
      },
      "type": {
        "type": "string",
        "enum": ["valve"],
        "title": "Device type",
        "readOnly": true
      },
      "connhexId": {
        "type": "string",
        "title": "ConnhexId",
        "readOnly": true
      },
      "metadata": {
        "type": "string",
        "title": "metadata"
      },
      "plant": {
        "type": "string",
        "title": "plant",
        "connhex": {
          "id": "plant"
        }
      },
      "tags": {
        "type": "array",
        "title": "tags",
        "items": {
          "type": "string",
          "connhex": {
            "id": "tag"
          }
        }
      }
    }
  }
}

Identifying resources and attributes

You can easily identify resources and attributes by using the connhex.id property. In the example above, the plant attribute is a reference to a resource of type plant and the tags attribute is an array of references to resources of type tag.

References are modeled as strings or array of strings: this is because the represent the ids of the references resources. You can read more about how to leverage this behavior here.