# Ontology definition

This article provides a breakdown of the structure for ontology definition items.

## Supported formats

Ontology items support the JSON format.

## Definition parts

This table lists the ontology definition parts.

Several parts include an entity type ID value. The entity type ID is a positive 64-bit integer that's unique across the ontology instance.

| Definition part path | Type | Required | Description |
|----|----|----|----|
| `definition.json` | DefinitionDetails (JSON) | true | Empty definition. |
| `.platform` | PlatformDetails (JSON) | true | Describes common details of the item. |
| `EntityTypes/{ID}` | Directory | false | Contains the definition.json file for the entity type which describes details of the entity type. The entity type ID is a positive 64-bit integer that's unique across the ontology instance. |
| `EntityTypes/{ID}/DataBindings` | Directory | false | Contains a list of data binding files that are part of the entity type. Each data binding operation file (JSON) describes details of the data binding. |
| `EntityTypes/{ID}/Documents` | Directory | false | Contains a list of document files that are part of the entity type. Each document operation file (JSON) describes details of the document. |
| `EntityTypes/{ID}/Overviews` | Directory | false | Contains the definition.json file for the overviews of the entity type. |
| `RelationshipTypes/{ID}` | Directory | false | Contains the definition.json file for the relationship type which describes details of the relationship type. |
| `RelationshipTypes/{ID}/Contextualizations` | Directory | false | Contains a list of contextualization files that are part of the relationship type. Each contextualization file (JSON) describes details of the contextualization. |

## Definition example

```json
{
  "parts": [
    {
      "path": ".platform",
      "payload": "eyANCiAgIm1ldGFkYXRhIjogeyANCiAgICAidHlwZSI6ICJPbnRvbG9neSIsIA0KICAgICJkaXNwbGF5TmFtZSI6ICJvbnRvbG9neSIgDQogIH0gDQp9",
      "payloadType": "InlineBase64"
    },
    { 
      "path": "definition.json",
      "payload": "e30=",
      "payloadType": "InlineBase64"
    }
  ]
}
```

### Definition example with optional definition parts

```json
{
  "parts": [
    {
      "path": ".platform",
      "payload": "eyANCiAgIm1ldGFkYXRhIjogeyANCiAgICAidHlwZSI6ICJPbnRvbG9neSIsIA0KICAgICJkaXNwbGF5TmFtZSI6ICJvbnRvbG9neSIgDQogIH0gDQp9",
      "payloadType": "InlineBase64"
    },
    { 
      "path": "definition.json",
      "payload": "e30=",
      "payloadType": "InlineBase64"
    }, 
    {
      "path": "EntityTypes/8813598896083/definition.json",
      "payload": "   ",
      "payloadType": "InlineBase64"
    },
    {
      "path": "EntityTypes/8813598896083/DataBindings/66253a71-c26f-4c9d-877f-3af5632a4be2.json",
      "payload": " ",
      "payloadType": "InlineBase64"
    },
    {
      "path": "EntityTypes/8813598896083/DataBindings/39a3889b-77e4-4851-8960-e3b779a5d9ba.json",
      "payload": " ",
      "payloadType": "InlineBase64"
    },  
    {
      "path": "EntityTypes/8813598896083/Documents/document1.json",
      "payload": "eyANCiAgImRpc3BsYXlUZXh0IjogImRvYzEiLCANCiAgInVybCI6ICJleGFtcGxldXJsMSIgDQp9",
      "payloadType": "InlineBase64"
    },
    {
      "path": "EntityTypes/8813598896083/Overviews/definition.json",
      "payload": "ew0KICAid2lkZ2V0cyI6IFsNCiAgICB7DQogICAgICAidHlwZSI6ICJsaW5lQ2hhcnQiLA0KICAgICAgInlBeGlzUHJvcGVydHlJZCI6ICIzMTE0NTg0OTc3NTYyNjc5NjcyIiwNCiAgICAgICJpZCI6ICI2ZDczMzAxOC1jMTc3LTQ3YjUtODdiYS02MDI0Y2MxNDM3NzYiLA0KICAgICAgInRpdGxlIjogInRlbXBlcmF0dXJlIGRhdGEiDQogICAgfQ0KICBdLA0KICAic2V0dGluZ3MiOiB7DQogICAgInR5cGUiOiAiZml4ZWRUaW1lIiwNCiAgICAiZml4ZWRUaW1lUmFuZ2UiOiAiTGFzdDFIb3VyIiwNCiAgICAiaW50ZXJ2YWwiOiAiT25lSG91ciIsDQogICAgImFnZ3JlZ2F0aW9uIjogIkF2ZXJhZ2UiDQogIH0NCn0=",
      "payloadType": "InlineBase64"
    },
    {
      "path": "EntityTypes/159990879905613/definition.json",
      "payload": " ",
      "payloadType": "InlineBase64"
    },
    {
      "path": "EntityTypes/159990879905613/DataBindings/60efb0e8-2225-4a1b-84c8-1987d37ee422.json",
      "payload": " ",
      "payloadType": "InlineBase64"
    },
    {
      "path": "EntityTypes/159990879905613/DataBindings/0542df13-5b4b-4590-8dcf-ea2435d90a73.json",
      "payload": "  ",
      "payloadType": "InlineBase64"
    },
    {
      "path": "RelationshipTypes/3110733855942077719/definition.json",
      "payload": "ew0KICAibmFtZXNwYWNlIjogInVzZXJ0eXBlcyIsDQogICJpZCI6ICIzMTEwNzMzODU1OTQyMDc3NzE5IiwNCiAgIm5hbWUiOiAiY29udGFpbnMiLA0KICAibmFtZXNwYWNlVHlwZSI6ICJDdXN0b20iLA0KICAic291cmNlIjogew0KICAgICJlbnRpdHlUeXBlSWQiOiAiODgxMzU5ODg5NjA4MyINCiAgfSwNCiAgInRhcmdldCI6IHsNCiAgICAiZW50aXR5VHlwZUlkIjogIjE1OTk5MDg3OTkwNTYxMyINCiAgfQ0KfQ==",
      "payloadType": "InlineBase64"
    },
    {
      "path": "RelationshipTypes/3110733855942077719/Contextualizations/62bbbf52-39a4-47ed-b7bf-651debaca6ab.json",
      "payload": " ",
      "payloadType": "InlineBase64"
    }
  ]
}
```

## DefinitionDetails 

The DefinitionDetails file name is *definition.json*. It is an empty definition.

### DefinitionDetails file example 

```json
{}
```

## EntityTypes/{ID} directory: EntityType file

The EntityType file name is the *definition.json*.

| Property | Type | Required | Description |
|----|----|----|----|
| `id` | BigInt | true | Unique ID of the entity type. The entity type ID is a positive 64-bit integer that's unique across the ontology instance. |
| `namespace` | string | true | Allowed value: *usertypes*. |
| `baseEntityTypeId` | BigInt | false | Unique ID of the base entity type. |
| `name` | string | true | Name of the entity type. Must follow this Regex pattern: `^[a-zA-Z][a-zA-Z0-9\_-]{0,127}\$`. |
| `entityIdParts` | BigInt[] | false | The properties (by ID) that together uniquely identify an entity. |
| `displayNamePropertyId` | BigInt | false | The ID of the property that's used as the display name for the entity. |
| `namespaceType` | string | true | Allowed value: *Custom.* |
| `visibility` | string | false | Allowed value: *Visible.* |
| `properties` | EntityTypeProperty[] | false | List of entity type properties. |
| `timeseriesProperties` | EntityTypeProperty[] | false | List of entity type properties. |

### EntityTypeProperty

| Property | Type | Required | Description |
|----|----|----|----|
| `id` | BigInt | true | Unique ID of the entity type property. |
| `name` | string | true | Name of the entity type property. Must follow this Regex pattern: `^[a-zA-Z][a-zA-Z0-9\_-]{0,127}\$`. |
| `redefines` | string | false | Pointer to property inherited from base type that this property redefines. |
| `baseTypeNamespaceType` | string | false | The namespace of the base entity type. |
| `valueType` | string | true | Describes the value type of the entity type property. Allowed values: *String*, *Boolean*, *DateTime*, *Object*, *BigInt*, *Double*. |

### EntityType file example

```json
{
  "id": "8813598896083",
  "namespace": "usertypes",
  "baseEntityTypeId": null,
  "name": "Equipment1",
  "entityIdParts": [
    "3117068036374594013"
  ],
  "displayNamePropertyId": "3117068036374594013",
  "namespaceType": "Custom",
  "visibility": "Visible",
  "properties": [
    {
      "id": "3117068036374594013",
      "name": "DisplayName",
      "redefines": null,
      "baseTypeNamespaceType": null,
      "valueType": "String"
    },
    {
      "id": "3117068031950000331",
      "name": "Manufacturer",
      "redefines": null,
      "baseTypeNamespaceType": null,
      "valueType": "String"
    }
  ],
  "timeseriesProperties": [
    {
      "id": "3114584981368796953",
      "name": "PreciseTimestamp",
      "redefines": null,
      "baseTypeNamespaceType": null,
      "valueType": "DateTime"
    },
    {
      "id": "3114584979743320934",
      "name": "Name",
      "redefines": null,
      "baseTypeNamespaceType": null,
      "valueType": "String"
    },
    {
      "id": "3114584977562679672",
      "name": "Temperature",
      "redefines": null,
      "baseTypeNamespaceType": null,
      "valueType": "Double"
    }
  ]
}
```

## EntityTypes/{ID}/DataBindings directory: DataBinding file

The DataBinding file name is the DataBinding ID.

| Property | Type | Required | Description |
|----|----|----|----|
| `id` | Guid | true | Unique ID of the data binding. |
| `dataBindingConfiguration` | DataBindingConfiguration | true | Configuration specific to the kind of data binding. |

### DataBindingConfiguration

| Property | Type | Required | Description |
|----|----|----|----|
| `dataBindingType` | string | true | Allowed values: *TimeSeries*, *NonTimeSeries* |
| `timestampColumnName` | string | false | Only required if `dataBindingType` is *TimeSeries*. This is the name of the timestamp column from the data table. |
| `propertyBindings` | EntityTypePropertyBinding[] | false | The bindings from source columns to entity type properties. |
| `sourceTableProperties` | LakehouseTableDataBindingProperties or EventhouseTableDataBindingProperties.<br>**Note:** EventhouseTableDataBindingProperties can only be used if the `dataBindingType` is *TimeSeries*. | true | Data source table properties. |

### EntityTypePropertyBinding

| Property | Type | Required | Description |
|----|----|----|----|
| `sourceColumnName` | string | true | The name of the source column in the data table. |
| `targetPropertyId` | string | true | The target property ID in the entity type. |

### LakehouseTableDataBindingProperties

| Property | Type | Required | Description |
|----|----|----|----|
| `sourceType` | string | true | The sourceType of the Data Binding. Allowed value: *LakehouseTable*. |
| `workspaceId` | Guid | true | The ID of the workspace where the customer's lakehouse table is located. |
| `itemId` | Guid | true | `ArtifactId` of the customer's lakehouse. |
| `sourceTableName` | string | true | The name of the data table from the lakehouse. |
| `sourceSchema` | string | false | The schema of the data table. |

### EventhouseTableDataBindingProperties

| Property | Type | Required | Description |
|----|----|----|----|
| `sourceType` | string | true | The source type of the Data Binding. Allowed value: *KustoTable*. |
| `workspaceId` | Guid | true | The ID of the workspace where the customer's eventhouse is located. |
| `itemId` | Guid | true | `ArtifactId` of the customer's eventhouse. |
| `clusterUri` | string | true | The URL to the Kusto cluster. |
| `databaseName` | string | true | The name of the database in the Kusto cluster. |
| `sourceTableName` | string | true | The name of the source table in the Kusto cluster. |

### DataBinding file example

```json
{
  "id": "39a3889b-77e4-4851-8960-e3b779a5d9ba",
  "dataBindingConfiguration": {
    "dataBindingType": "TimeSeries",
    "timestampColumnName": "PreciseTimestamp",
    "propertyBindings": [
      {
          "sourceColumnName": "PreciseTimestamp",
          "targetPropertyId": "3114584981368796953"
      },
      {
          "sourceColumnName": "Name",
          "targetPropertyId": "3114584979743320934"
      },
      {
          "sourceColumnName": "Temperature",
          "targetPropertyId": "3114584977562679672"
      },
      {
          "sourceColumnName": "Name",
          "targetPropertyId": "3117068036374594013"
      }
    ],
    "sourceTableProperties": {
      "sourceType": "LakehouseTable",
      "workspaceId": "580f410e-733d-43bd-8a87-be12b536f7ff",
      "itemId": "d0d863bc-48e1-45b2-8f4b-54795c97ba71",
      "sourceTableName": "equipment1timeseries",
      "sourceSchema": "dbo"
    }
  }
}
```

## EntityTypes/{ID}/Documents directory: Document file

The Document file name is the *document{id}.json*, where *id* is the document number for the entity type.

### Document

| Property    | Type   | Required | Description                        |
|-------------|--------|----------|------------------------------------|
| `displayText` | string | false    | The display text for the document. |
| `url`         | string | true     | The URL pointing to the document.  |

### Document file example

```json
{
  "displayText": "doc1",
  "url": "exampleurl1"
}
```

## EntityTypes/{ID}/Overviews directory: Overviews file

The Overviews file name is *definition.json*.

### Overviews

| Property | Type                | Required | Description                    |
|----------|---------------------|----------|--------------------------------|
| `widgets`  | Widget[] | false    | The widgets on the preview experience.  |
| `settings` | Settings   | false    | The settings of the preview experience. |

### Widget

| Property | Type | Required | Description |
|----|----|----|----|
| `id` | Guid | true | Unique ID of the widget. |
| `type` | string | true | Type of widget. Allowed values: *lineChart*, *barChart*, *file*, *graph*, *liveMap*. |
| `title` | string | false | The title of the widget. |
| `yAxisPropertyId` | string | false | The property to display on the y-axis.<br>**Note:** Include this field only if `type` is *lineChart* or *barChart*. |

### Settings

| Property | Type | Required | Description |
|----|----|----|----|
| `type` | string | true | Type of Settings. Allowed values: *fixedTime*, *customTime*. |
| `interval` | string | true | Sample window values in seconds for the preview experience data. Allowed values: *OneMinute*, *FiveMinutes*, *FifteenMinutes*, *ThirtyMinutes*, *OneHour*, *SixHours*, *TwelveHours*, *OneDay*. |
| `aggregation` | string | true | Aggregation function for the preview experience data. Allowed values: *Average*, *Count*, *Maximum*, *Minimum*, *Sum*, *LastKnownValue*. |
| `fixedTimeRange` | string | false | The fixed time range for the preview experience data. Allowed values: *Last30Minutes*, *Last1Hour*, *Last4Hours*, *Last12Hours*, *Last24Hours*, *Last48Hours*, *Last3Days*, *Last7Days*, *Last30Days*.<br>**Note:** Include this field only if `type` is *fixedTime*. |
| `timeRange` | TimeRange | false | Time range for the preview experience data.<br>**Note:** Include this field only if `type` is *customTime*. |

### TimeRange

| Property  | Type        | Required | Description                           |
|-----------|-------------|----------|---------------------------------------|
| `startTime` | UTCDateTime | true     | Start time for the custom time range. |
| `endTime`   | UTCDateTime | true     | End time for the custom time range.   |

### Overviews file example

```json
{
  "widgets": [
    {
      "type": "lineChart",
      "yAxisPropertyId": "3114584977562679672",
      "id": "6d733018-c177-47b5-87ba-6024cc143776",
      "title": "temperature data"
    }
  ],
  "settings": {
    "type": "fixedTime",
    "fixedTimeRange": "Last1Hour",
    "interval": "OneHour",
    "aggregation": "Average"
  }
}
```

## RelationshipTypes/{ID} directory: RelationshipType file

The RelationshipType file name is *definition.json*.

| Property | Type | Required | Description |
|----|----|----|----|
| `id` | BigInt | true | Unique ID of the relationship type. |
| `namespace` | string | true | Allowed value: *usertypes*. |
| `name` | string | true | Name of the relationship type. Must follow this Regex pattern: `^[a-zA-Z][a-zA-Z0-9\_-]{0,127}\$`. |
| `namespaceType` | BigInt | true | Allowed value: *Custom*. |
| `source` | RelationshipEnd | true | The relationship end that denotes the source. |
| `target` | RelationshipEnd | true | The relationship end that denotes the target. |

### RelationshipEnd

| Property | Type | Required | Description |
|----|----|----|----|
| `entityTypeId` | string | true | The entity type ID of the relationship end that exists in the workspace. The entity type ID is a positive 64-bit integer that's unique across the ontology instance. |

### RelationshipType file example

```json
{
  "namespace": "usertypes",
  "id": "3110733855942077719",
  "name": "contains",
  "namespaceType": "Custom",
  "source": {
    "entityTypeId": "8813598896083"
  },
  "target": {
    "entityTypeId": "159990879905613"
  }
}
```

## RelationshipTypes/{ID}/Contextualizations directory: Contextualization file

The Contextualization file name is the contextualization ID.

| Property | Type | Required | Description |
|----|----|----|----|
| `id` | Guid | true | Unique ID of the contextualization. |
| `dataBindingTable` | LakehouseTableDataBindingProperties | true | The source lakehouse data table. |
| `sourceKeyRefBindings` | EntityTypePropertyBinding[] | true | The columns in the dataTable making up the unique ID of the source-side entity type. |
| `targetKeyRefBindings` | EntityTypePropertyBinding[] | true | The columns in the dataTable making up the unique ID of the target-side entity type. |

### Contextualization file example:

```json
{
  "id": "62bbbf52-39a4-47ed-b7bf-651debaca6ab",
  "dataBindingTable": {
    "workspaceId": "580f410e-733d-43bd-8a87-be12b536f7ff",
    "itemId": "d0d863bc-48e1-45b2-8f4b-54795c97ba71",
    "sourceTableName": "relationshiptable",
    "sourceSchema": "dbo",
    "sourceType": "LakehouseTable"
  },
  "sourceKeyRefBindings": [
    {
      "sourceColumnName": "Equipment1Name",
      "targetPropertyId": "3117068036374594013"
    }
  ],
  "targetKeyRefBindings": [
    {
      "sourceColumnName": "Equipment2Name",
      "targetPropertyId": "3113493256674129151"
    }
  ]
}
```
