DIF schema and example files

DIF declares its data objects in two JSON schema files:

The following files show topology and entity objects in the context of example entities:

Proxy Virtual Machine entity with vMem metrics
Database Server entity hosted on a Virtual Machine

For more information about the properties in these data objects, see the following topics:

You can also find several examples of DIF integrations in the DIF GitHub repository.

dif-topology-schema.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "http://turbonomic.com/dif-topology.json",
  "title": "DIF Topology File",
  "description": "Format for a DIF topology",
  "type": "object",
  "properties": {
    "version": {
      "description": "",
      "type": "string"
    },
    "updateTime": {
      "description": "Epoch timestamp for when files are generated",
      "type": "integer"
    },
    "topology": {
      "description": "List of topology entities",
      "type" : "array",
      "items": {
        "$ref": "#/definitions/entity"
      },
      "minItems" : 1
    }
  },
  "required": [
    "version",
    "updateTime",
    "topology"
  ],

  "definitions": {
    "entity" : {
      "description": "Format for a DIF topology entity and metrics",
      "type": "object",
      "properties": {
        "type": {
          "description": "Entity type of the entity",
          "$ref" : "dif-entity-schema.json#/definitions/entityType"
        },
        "uniqueId": {
          "description": "Unique identifier for the entity, within the scope of the target",
          "type": "string"
        },
        "name": {
          "description": "Entity name",
          "type": "string"
        },
        "matchIdentifiers": {
          "description": "Attributes used to find the entity that matches this entity",
          "type": "object",
          "properties": {
            "ipAddress": {
              "description": "IP Address of the entity used to find the matching entity",
              "type": "string"
            }
          }
        },
        "hostedOn": {
          "description": "Attributes used to find the entity that hosts this entity",
          "type": "object",
          "properties": {
            "hostType" : {
              "description": "List of entity types of the possible underlying host entity. The order in which the entity types is specified is used to find the host entity.",
              "type": "array",
              "items": {"$ref" : "dif-entity-schema.json#/definitions/hostEntityType"}
            },
            "hostUuid": {
              "description": "Unique identifier for the host entity",
              "type": "string"
            },
            "ipAddress": {
              "description": "IP Address of the host entity",
              "type": "string"
            }
          },
          "required": [
            "hostType"
          ]
        },
        "partOf": {
          "description": "Attributes used to find all the entities that this entity is part of",
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "entity": {
                "description": "Entity type of the parent entity ",
                "$ref": "dif-entity-schema.json#/definitions/entityType"
              },
              "uniqueId": {
                "description": "Unique identifier for the parent entity within the scope of this target",
                "type": "string"
              }
            }
          }
        },
        "metrics": {
          "description": "List of metrics and values for the entity",
          "type" : "array",
          "items": {
            "$ref": "dif-entity-schema.json#/definitions/metricsEntry"
          },
          "minItems" : 1
        }
      },

      "required": [
        "type",
        "uniqueId",
        "name"
      ]
    }
  }
}

dif-entity-schema.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id":  "http://turbonomic.com/dif-entity.json",
  "title": "DIF Entity File",
  "description": "Format for a DIF topology entity and metrics",
  "type": "object",
  "properties": {
    "type": {
      "description": "Entity type of the entity",
      "$ref" : "#/definitions/entityType"
    },
    "uniqueId": {
      "description": "Unique identifier for the entity, within the scope of the target",
      "type": "string"
    },
    "name": {
      "description": "Entity name",
      "type": "string"
    },
    "matchIdentifiers": {
      "description": "Attributes used to find the entity that matches this entity",
      "type": "object",
      "properties": {
        "ipAddress": {
          "description": "IP Address of the entity used to find the matching entity",
          "type": "string"
        }
      }
    },
    "hostedOn": {
      "description": "Attributes used to find the entity that hosts this entity",
      "type": "object",
      "properties": {
        "hostType" : {
          "description": "List of entity types of the possible underlying host entity. The order in which the entity types is specified is used to find the host entity.",
          "type": "array",
          "items": {"$ref" : "#/definitions/hostEntityType"}
        },
        "hostUuid": {
          "description": "Unique identifier for the host entity",
          "type": "string"
        },
        "ipAddress": {
          "description": "IP Address of the host entity",
          "type": "string"
        }
      },
      "required": [
        "hostType"
      ]
    },
    "partOf": {
      "description": "Attributes used to find all the entities that this entity is part of",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "entity": {
            "description": "Entity type of the parent entity ",
            "$ref": "#/definitions/entityType"
          },
          "uniqueId": {
            "description": "Unique identifier for the parent entity within the scope of this target",
            "type": "string"
          }
        }
      }
    },

    "metrics": {
      "description": "List of metrics and values for the entity",
      "type" : "array",
      "items": {
        "$ref": "#/definitions/metricsEntry"
      },
      "minItems" : 1
    }
  },
  "required": [
    "type",
    "uniqueId",
    "name"
  ],

  "definitions": {
    "entityType": {
      "description": "Entity type",
      "type": "string",
      "enum": [
        "businessApplication",
        "businessTransaction",
        "service",
        "databaseServer",
        "application"
      ]
    },
    "hostEntityType": {
      "description": "Entity type of the host that underlies this entity",
      "type": "string",
      "enum": [
        "container",
        "virtualMachine"
      ]
    },
    "metricUnit" : {
      "description": "Units for different metrics",
      "type": "string",
      "enum" : ["count", "tps", "ms", "mb", "mhz", "pct"]
    },
    "metricValue": {
      "type": "object",
      "properties": {
        "average": { "type": "number" },
        "min": { "type": "number" },
        "max": { "type": "number" },
        "capacity": { "type": "number" },
        "key": { "type": "string" },
        "resizable": { "type": "boolean" },
        "unit": { "$ref": "#/definitions/metricUnit" }
      },
      "required": [
        "average", "unit"
      ]
    },
    "metricsEntry": {
      "description": "Supported metrics, TODO - add schemas for other supported metrics",
      "type": "object",
      "oneOf" : [
        { "$ref": "#/definitions/_responseTime"},
        { "$ref": "#/definitions/_transaction"},
        { "$ref": "#/definitions/_connection"},
        { "$ref": "#/definitions/_heap"},
        { "$ref": "#/definitions/_remainingGCCapacity"},
        { "$ref": "#/definitions/_kpi"},
        { "$ref": "#/definitions/_cpu"},
        { "$ref": "#/definitions/_memory"},
        { "$ref": "#/definitions/_threads"},
        { "$ref": "#/definitions/_dbCacheHitRate"},
        { "$ref": "#/definitions/_dbMem"}
      ]
    },

    "_responseTime" : {
      "description": "Specification for Response Time metrics",
      "type": "object",
      "properties": {
        "responseTime": {
          "$ref": "#/definitions/metricValue"
        }
      },
      "required": [
        "responseTime"
      ]
    },
    "_transaction" : {
      "description": "Specification for Transaction metrics",
      "type": "object",
      "properties": {
        "transaction": {
          "$ref": "#/definitions/metricValue"
        }
      },
      "required": [
        "transaction"
      ]
    },
    "_connection" : {
      "description": "Specification for Connections metrics",
      "type": "object",
      "properties": {
        "connection": {
          "$ref": "#/definitions/metricValue"
        }
      },
      "required": [
        "connection"
      ]
    },
    "_heap" : {
      "description": "Specification for Heap metrics",
      "type": "object",
      "properties": {
        "heap": {
          "$ref": "#/definitions/metricValue"
        }
      },
      "required": [
        "heap"
      ]
    },
    "_remainingGCCapacity" : {
      "description": "Specification for Collection Time metrics",
      "type": "object",
      "properties": {
        "remainingGCCapacity": {
          "$ref": "#/definitions/metricValue"
        }
      },
      "required": [
        "remainingGCCapacity"
      ]
    },
    "_threads" : {
      "description": "Specification for Threads metrics",
      "type": "object",
      "properties": {
        "threads": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/metricValue"
          },
          "uniqueItems": true,
          "minItems": 1
        }
      },
      "required": [
        "threads"
      ]
    },
    "_dbCacheHitRate" : {
      "description": "Specification for DB Cache Hit Rate metrics",
      "type": "object",
      "properties": {
        "dbCacheHitRate": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/metricValue"
          },
          "uniqueItems": true,
          "minItems": 1
        }
      },
      "required": [
        "dbCacheHitRate"
      ]
    },
    "_dbMem" : {
      "description": "Specification for DB Memory metrics",
      "type": "object",
      "properties": {
        "dbMem": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/metricValue"
          },
          "uniqueItems": true,
          "minItems": 1
        }
      },
      "required": [
        "dbMem"
      ]
    },
    "_cpu" : {
      "description": "Specification for CPU metrics",
      "type": "object",
      "properties": {
        "cpu": {
          "$ref": "#/definitions/metricValueWithRawData"
        }
      },
      "required": ["cpu"]
    },
    "_memory" : {
      "description": "Specification for Memory metrics",
      "type": "object",
      "properties": {
        "memory": {
          "$ref": "#/definitions/metricValueWithRawData"
        }
      },
      "required": ["memory"]
    },
    "_kpi" : {
      "description": "Specification for the custom metrics",
      "type": "object",
      "properties": {
        "kpi": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/metricValueWithKey"
          },
          "uniqueItems": true,
          "minItems": 1
        }
      },
      "required": ["kpi"]
    },

    "metricValueWithKey": {
      "type": "object",
      "properties": {
        "description": { "type": "string" },
        "key": { "type": "string" },
        "average": { "type": "number" },
        "capacity": { "type": "number" },
        "unit": { "$ref": "#/definitions/metricUnit" }
      },
      "required": [
        "average", "unit", "key"
      ]
    },

    "metricValueWithRawData": {
      "type": "object",
      "properties": {
        "average": { "type": "number" },
        "min": { "type": "number" },
        "max": { "type": "number" },
        "capacity": { "type": "number" },
        "unit": { "$ref": "#/definitions/metricUnit" },
        "rawData" : {
          "type": "object",
          "properties": {
            "utilization": {
              "type": "array",
              "items" : {
                "type": "object"
              },
              "minItems":1
            },
            "units:" : {"$ref": "#/definitions/metricUnit"}
          },
          "required": [
            "utilization"
          ]
        }
      },
      "required": [
        "average", "unit"
      ]
    }
  }
}

Proxy Virtual Machine entity with vMem metrics

{
  "version": "v1",
  "updateTime": 1595519486,
  "scope": "",
  "source": "",
  "topology": [
    {
      "uniqueId": "spcfq9keqj-worker-1",
      "type": "virtualMachine",
      "name": "spcfq9keqj-worker-1",
      "hostedOn": null,
      "matchIdentifiers": {
        "ipAddress": "172.23.0.5"
      },
      "partOf": [
        {
          "uniqueId": "DatabaseServer-10.10.169.38-turbonomic",
          "entity": "databaseServer"
        }
      ],
      "metrics": {
        "memory": [
          {
            "average": 1363148.8,
            "capacity": 3670016
          }
        ]
      }
    }
  ]
}

Database Server entity hosted on a Virtual Machine

{
  "version": "v1",
  "updateTime": 1595519551,
  "scope": "Prometheus",
  "source": "",
  "topology": [
    {
      "uniqueId": "DatabaseServer-10.10.169.38-turbonomic",
      "type": "databaseServer",
      "name": "DatabaseServer-10.10.169.38-turbonomic",
      "hostedOn": {
        "hostType": [
          "virtualMachine"
        ],
        "ipAddress": "10.10.169.38"
      },
      "metrics": {
        "connection": [
          {
            "average": 14,
            "capacity": 151
          }
        ],
        "dbCacheHitRate": [
          {
            "average": 100
          }
        ],
        "dbMem": [
          {
            "average": 16636512,
            "capacity": 16777216
          }
        ],
        "memory": [
          {
            "average": 16636512,
            "capacity": 16777216
          }
        ],
        "transaction": [
          {
            "average": 0.5388918827326818
          }
        ]
      }
    }
  ]
}