> ## Documentation Index > Fetch the complete documentation index at: https://bloodhound.specterops.io/llms.txt > Use this file to discover all available pages before exploring further. # Definition Schema > Define structured graph behavior for OpenGraph extensions with an extension definition schema. Applies to BloodHound Enterprise and Community Edition An extension definition schema tells BloodHound how to interpret, interact with, and represent extension-specific [data payloads](/opengraph/developer/graph-data). Use it when you want your extension to produce a structured graph and enable advanced analysis features in BloodHound. If you only need generic graph support, upload a valid OpenGraph data payload and skip this page. An extension definition schema is a JSON file that OpenGraph extension developers provide for BloodHound users to install on the [OpenGraph Management](/opengraph/extensions/manage) page before they upload data payloads that conform to the schema. In BloodHound Enterprise, supported platform extensions (GitHub, Jamf, and Okta) are pre-installed. Other SpecterOps-supported schemas, such as SCIM, must still be uploaded manually. This page describes the components of an extension definition schema. For a full example of how these components work together, see the [example schema](/opengraph/developer/graph-definition#example-schema) section at the end of the page. ```json theme={null} { "schema": { ... }, "node_kinds": [ ... ], "relationship_kinds": [ ... ], "environments": [ ... ] } ``` Extension metadata identifying the extension, including version and namespace. Defines custom node types, visual representations, and Entity Panel content for an extension. Defines custom edge types, traversability behavior, and Entity Panel content for an extension. Defines the environments for a platform and identifies which node kinds an extension treats as principals within each environment. BloodHound Enterprise uses these environment definitions to group analysis, findings, and metrics. ## Namespacing BloodHound uses namespaces to organize graph data. Each extension has a namespace key, which is used as a prefix in relevant `name` fields to indicate that the data belongs to that namespace. Namespacing allows multiple extensions to define similar graph data without conflicts, because the namespace prefix makes each name unique. With the exception of `schema.name`, all `name` fields must follow these namespacing rules to avoid collisions with built-in graph elements and other extensions. This does not apply to `display_name` fields, which are used only for human-readable labels. * Must be unique within the extension * Must be prefixed with the extension's namespace separated by an underscore (for example, `namespace_Name`) * Must include more than just the namespace prefix Although the `schema.name` field does not use a namespace prefix, it must still be unique for each extension. BloodHound treats extensions with matching `schema.name` fields as the same extension and overwrites existing extension definition schemas when uploaded. * If names are not unique or properly namespaced, schema uploads fail validation. * The `tag` namespace prefix is reserved in any letter case, including `tag`, `Tag`, and `TAG`. Do not use this prefix in an extension definition schema. If you do, BloodHound rejects the upload. ## `schema` Defines metadata about the extension itself. ```json theme={null} { "name": "SOOkta", "display_name": "Okta Extension (by SpecterOps)", "version": "v2.8.1", "namespace": "Okta" } ``` Unique name that identifies an extension in BloodHound. Human-readable label shown for this extension in BloodHound. Extension schema version, prefixed with `v` followed by semantic version format, for example `v1.0.0`. Namespace key used as a prefix for all `name` fields in the `node_kinds` and `relationship_kinds` arrays to indicate that the data belongs to that namespace. ## `node_kinds` Defines all node types in your extension. Each node kind represents an entity type (for example: user, device, or environment). ```json theme={null} [ { "name": "Okta_User", "display_name": "Okta User", "description": "An Okta user account", "is_display_kind": true, "icon": "user", "color": "#d33115", "info": { "overview": { "title": "Overview", "position": 1, "markdown": { "content": "Okta user accounts represent identities that can authenticate to Okta." } } } } ] ``` Unique node kind identifier. Must follow [namespacing](/opengraph/developer/graph-definition#namespacing) rules. For each node in a data payload to be included in a [structured graph](/opengraph/overview#structured-graphs), at least one value in its `kinds` array must match a `node_kinds.name` defined in the extension definition schema. The node schema for an environment must be defined here to be used for findings and metrics in BloodHound Enterprise. Human-readable label shown for this node kind in BloodHound. Optional description that explains what the node kind represents. Determines whether to use the `icon` and `color` definitions for nodes of this kind in the graph. Optional Font Awesome [icon name](https://fontawesome.com/search?s=solid) (without the "fa-" prefix) to show for nodes of this kind in the graph. Optional Hex color code (in `#RGB` or `#RRGGBB` format, the `#` is required) to apply to nodes of this kind in the graph. Optional [custom Entity Panel content](/opengraph/developer/entity-panel-content#custom-entity-panel-content) for nodes of this kind. ## `relationship_kinds` Defines what kind of connections exist. Each relationship kind represents a specific type of connection that can exist between nodes. ```json theme={null} [ { "name": "Okta_ResetPassword", "description": "Ability to reset passwords or temporary credentials for scoped Okta users", "is_traversable": true, "info": { "abuse": { "title": "Abuse", "position": 1, "markdown": { "content": "An attacker can use this relationship to reset a user's password and access the account." } } } } ] ``` Unique relationship kind identifier. Must follow [namespacing](/opengraph/developer/graph-definition#namespacing) rules. For each edge in a data payload to be included in a [structured graph](/opengraph/overview#structured-graphs), `kind` must match a `relationship_kinds.name` defined in the extension definition schema. Optional description of what the relationship means. Controls whether edges of this relationship kind are used for pathfinding and Attack Path detection. When `is_traversable` is set to `true` on a relationship kind, all edges of that kind inherit the same traversability behavior. Only traversable edges are included in pathfinding and considered for findings and metrics. Optional [custom Entity Panel content](/opengraph/developer/entity-panel-content#custom-entity-panel-content) for relationships of this kind. ## `environments` Applies to BloodHound Enterprise only Environments are platform-specific groupings of nodes that BloodHound Enterprise uses to scope findings and metrics. Each environment definition specifies which node kinds represent principals within each environment. ```json theme={null} [ { "environment_kind": "Okta_Organization", "source_kind": "Okta", "principal_kinds": [ "Okta_User", "Okta_Application", "Okta_ApiServiceIntegration" ] } ] ``` Represents which node type within the extension is considered an environment for organizational and analytics purposes. Must match a node kind defined in the `node_kinds` array. For findings and metrics in BloodHound Enterprise, the [`graph.nodes.properties.environmentid`](/opengraph/developer/nodes#param-properties-environmentid) field for applicable nodes in the data payload must match this field. Source kind that associates this environment definition with a specific platform for environment organization and selection. See [Data source](/opengraph/developer/graph-data#data-source) for details. Node kinds defined by this extension/schema that BloodHound should treat as principals. Must match a `node_kinds.name` defined in this schema. BloodHound Enterprise incorporates these node kinds in findings and metrics. ## Example schema The following example schema is based on Okta to illustrate how the different components of the schema work together. ```json theme={null} { "schema": { "name": "SOOkta", "display_name": "Okta Extension (by SpecterOps)", "version": "v1.0.0", "namespace": "Okta" }, "node_kinds": [ { "name": "Okta_User", "display_name": "Okta User", "description": "An Okta user account", "is_display_kind": true, "icon": "user", "color": "#d33115", "info": { "overview": { "title": "Overview", "position": 1, "markdown": { "content": "Okta user accounts represent identities that can authenticate to Okta." } } } } ], "relationship_kinds": [ { "name": "Okta_ResetPassword", "description": "Ability to reset passwords or temporary credentials for scoped Okta users", "is_traversable": true, "info": { "abuse": { "title": "Abuse", "position": 1, "markdown": { "content": "An attacker can use this relationship to reset a user's password and access the account." } } } } ], "environments": [ { "environment_kind": "Okta_Organization", "source_kind": "Okta", "principal_kinds": [ "Okta_User", "Okta_Application", "Okta_ApiServiceIntegration" ] } ] } ```