Relationship Types

A RelationshipType defines a typed, directional connection between entities. Because relationships are themselves entities (of type entity_type/relationship_type), they can carry their own properties (edge properties) and participate in further relationships.

Defining a RelationshipType

Properties

Field	Type	Required	Description
name	string	yes	System identifier; used as the key
label	localized map	yes	Display name per locale
description	localized map	no	Description per locale
icon	string	no	Icon identifier for UI display
target_type	entity reference	yes	Constrains the entity type of the target
key_script	Lua string	no	Computes keys for relationship instances. See Lua Scripting.
label_script	Lua string	no	Computes labels for relationship instances. See Lua Scripting.

Relationships on a RelationshipType

Relationship	Target Type	Description
has_prop	property_type	Edge properties carried by each relationship instance
has_rel	relationship_type	Further relationships that relationship instances can participate in

Example

{
    "key": "has_ingredient",
    "properties": {
        "name": "has_ingredient",
        "label": { "en_us": "Has Ingredient", "de_de": "Hat Zutat" },
        "target_type": "entity_type/vegetable"
    },
    "relationships": {
        "has_prop": [
            {
                "properties": { "name": "quantity", "label": { "en_us": "Quantity" }, "required": true },
                "target": "int_property_type/generic"
            },
            {
                "properties": { "name": "unit", "label": { "en_us": "Unit" } },
                "target": "string_property_type/generic"
            }
        ]
    }
}

This defines a has_ingredient relationship type that targets vegetable entities and carries quantity and unit as edge properties.

Relationship Instances

A relationship instance represents a concrete connection between two entities. It is itself a full entity with its own UUID, properties, and metadata.

Fields

Field	Description
source	UUID of the entity that owns this relationship
target	UUID of the entity being pointed to
properties	Edge property values defined by the relationship type's has_prop

Creating Relationship Instances

Relationships can be created inline when creating or updating an entity:

{
    "key": "lasagna",
    "properties": { "name": { "en_us": "Lasagna" } },
    "relationships": {
        "has_ingredient": [
            {
                "target": "vegetable/tomato",
                "properties": { "quantity": 3, "unit": "pieces" }
            },
            {
                "target": "vegetable/onion",
                "properties": { "quantity": 1, "unit": "pieces" }
            }
        ]
    }
}

They can also be created through the dedicated relationship routes:

POST /api/v1/by-key/recipe/lasagna/relationships/has_ingredient

See REST API Reference for the full relationship route documentation.

Relationship Keys and Sub Key Spaces

Relationship instances have their own key, computed by the key_script on the RelationshipType (following the same resolution precedence as entity keys).

Key uniqueness is scoped to a sub key space for the combination of (relationship_type, source_entity). Two relationship instances of the same type may share a key as long as they have different source entities.

Canonical Reference Format

The canonical reference for a relationship instance follows the form:

source_entity_type/source_entity_key/relationship_type/relationship_key

For example: recipe/lasagna/has_ingredient/tomato

Relationship instances also carry their own root_id and id, with the same versioning semantics as regular entities.

Declaring Relationships on Entity Types

Entity types declare which relationship types they participate in via has_rel:

"has_rel": [
    {
        "properties": { "name": "has_ingredient", "label": { "en_us": "Ingredients" } },
        "target": "relationship_type/has_ingredient"
    }
]

The target points to the RelationshipType entity. Only relationship types declared via has_rel can be used on instances of that entity type.

Built-in System Relationship Types

These are defined by the system and used to describe the meta model itself:

Name	Target	Description
has_prop	property_type	Declares a property on an entity type or relationship type
has_virtual_prop	property_type	Declares a computed property
has_rel	relationship_type	Declares a relationship on an entity type or relationship type
has_list	entity_type	Declares a list on an entity type
has_parent	entity_type	Inheritance link
has_lc_map	lc_map	Links an entity type to a lifecycle map
has_lc_status	lc_status	Links a lifecycle map to its statuses
has_lc_transition	lc_status	Defines a valid transition from one lc_status to another
has_action	action	Declares an action on an entity type
has_hook	action	Declares a hook on an entity type

info

System relationship types are part of the meta model and cannot be modified by customers. They form the foundation on which all data modeling is built.

Traversing Relationships via the API

The API provides several ways to navigate relationships:

Route	Description
GET /@outgoing	All outgoing relationships, keyed by relationship type UUID
GET /@incoming	All relationship entities whose target points to this entity
GET /@referenced-by	All entities that hold a relationship pointing at this entity
GET /relationships	All relationships grouped by relationship type name
GET /relationships/<rel_name>	All instances of a specific relationship type
GET /relationships/<rel_name>/<rel_root_id>/@target	Navigate through a relationship to the target entity

See REST API Reference for the complete traversal documentation.