Entity Types

An EntityType defines the schema for a class of entities. It is itself an entity of type entity_type/entity_type, which means it is created, versioned, and queried through the same API as any other entity.

Every entity type you define -- whether recipe, document, or part -- automatically becomes available as a REST API endpoint. See REST API Reference for details.

Properties of an EntityType

Field	Type	Required	Description
name	string	yes	System identifier; used as the key. Must match [a-zA-Z0-9_]+. A customer prefix (e.g. xy_document) is recommended for namespacing.
label	localized map	yes	Display name per locale
label_plural	localized map	no	Plural display name per locale
description	localized map	no	Description per locale
icon	string	no	Icon identifier for UI display (Lucide icon library)
key_script	Lua string	no	Computes the human-readable key for instances. See Lua Scripting.
label_script	Lua string	no	Computes the display label for instances. See Lua Scripting.

Localized Maps

Properties like label, label_plural, and description use locale codes as keys:

{
    "label": { "de_de": "Rezept", "en_us": "Recipe" },
    "label_plural": { "de_de": "Rezepte", "en_us": "Recipes" }
}

Relationships on an EntityType

An entity type declares its structure through relationships to other meta-model entities:

Relationship	Target Type	Description
has_prop	property_type	Declares properties on this entity type. See Property Types.
has_virtual_prop	property_type	Declares computed (read-only) properties. See Virtual Properties.
has_rel	relationship_type	Declares which relationship types this entity type participates in. See Relationship Types.
has_list	entity_type	Declares ordered sub-entity lists. See Lists.
has_parent	entity_type	Inheritance -- this type extends another entity type. See Inheritance below.
has_lc_map	lc_map	Assigns a lifecycle map. See Lifecycle.
has_action	action	Declares callable actions. See Actions & Hooks.
has_hook	action	Declares lifecycle hooks. See Actions & Hooks.

Example: Defining an EntityType

{
    "key": "recipe",
    "properties": {
        "name": "recipe",
        "label": { "en_us": "Recipe", "de_de": "Rezept" },
        "label_plural": { "en_us": "Recipes", "de_de": "Rezepte" },
        "description": { "en_us": "A cooking recipe" },
        "icon": "book-open",
        "key_script": "return self.properties[\"recipe_id\"]"
    },
    "relationships": {
        "has_prop": [
            {
                "properties": { "name": "recipe_id", "label": { "en_us": "Recipe ID" }, "required": true, "unique": true },
                "target": "string_property_type/system_name"
            },
            {
                "properties": { "name": "title", "label": { "en_us": "Title" }, "required": true },
                "target": "multi_lang_property_type/generic"
            },
            {
                "properties": { "name": "servings", "label": { "en_us": "Servings" } },
                "target": "int_property_type/generic"
            }
        ],
        "has_rel": [
            {
                "properties": { "name": "has_ingredient", "label": { "en_us": "Ingredients" } },
                "target": "relationship_type/has_ingredient"
            }
        ],
        "has_lc_map": [
            { "target": "lc_map/EP_Default" }
        ]
    }
}

This defines a recipe entity type with three properties, one relationship type, and the default lifecycle.

Inheritance

Entity types support single inheritance via has_parent. A child type inherits all properties, relationships, and lists from its parent.

{
    "key": "vegan_recipe",
    "properties": {
        "name": "vegan_recipe",
        "label": { "en_us": "Vegan Recipe" }
    },
    "relationships": {
        "has_parent": [
            { "target": "entity_type/recipe" }
        ],
        "has_prop": [
            {
                "properties": { "name": "certification", "label": { "en_us": "Certification" } },
                "target": "string_property_type/generic"
            }
        ]
    }
}

The vegan_recipe type inherits all properties and relationships from recipe and adds its own certification property.

info

The property type hierarchy itself uses this mechanism -- all concrete property types (string_property_type, int_property_type, etc.) inherit from the base property_type.

Automatic API Endpoints

Every entity type is instantly available in the REST API and creates endpoints for its instances:

GET    /api/v1/by-type/<type_name>            -- List all instances
POST   /api/v1/by-type/<type_name>            -- Create a new instance
GET    /api/v1/by-key/<type_name>/<key>       -- Get a specific instance
PUT    /api/v1/by-id/<uuid>                   -- Update an instance
DELETE /api/v1/by-id/<uuid>?purge=true        -- Delete an instance

See REST API Reference for the complete endpoint documentation.

info

Entity types can change over time. Multiple versions of an entity type may exist concurrently, following the same immutability model described in The Meta Model.