Property Types

A PropertyType defines the data type and validation constraints of a property. All concrete property types inherit from the base property_type entity type. Property types are reusable -- define one once and attach it to many entity types.

Declaring a Property

Properties are declared on entity types and relationship types via has_prop. Each has_prop relationship instance carries edge properties that define the context of that particular usage:

Field	Type	Required	Description
name	string	yes	Property identifier on the entity
label	localized map	yes	Display name
description	localized map	no	Description
required	bool	no	Whether the property must have a value
unique	bool	no	Whether the value must be unique within the key space (see below)

The target of the has_prop relationship points to the specific property type variant (e.g. string_property_type/generic).

Uniqueness Scope

The unique constraint is scoped to the same key space as the entity's key (see Key Spaces):

• For entity properties: uniqueness across all instances of the same type.
• For trait properties: uniqueness globally across all entities that carry the trait.
• For relationship and list-item edge properties: uniqueness within the sub key space scoped to the source/owner entity.

Example

"has_prop": [
    {
        "properties": {
            "name": "material_number",
            "label": { "en_us": "Material Number", "de_de": "Materialnummer" },
            "required": true,
            "unique": true
        },
        "target": "string_property_type/system_name"
    }
]

Built-in Property Types

Scalar Types

Reference	Description	JSON type
bool_property_type/generic	Boolean	true / false
int_property_type/generic	Integer	number
float_property_type/generic	Floating point	number
datetime_property_type/generic	Date/time (ISO 8601)	"string"
blob_property_type/generic	Binary large object	See BLOB Properties

String Types

String property types support an optional regex field on the variant for server-side validation:

Reference	Regex	Description
string_property_type/generic	--	Plain string
string_property_type/system_name	[a-zA-Z0-9_]+	System-safe identifier
string_property_type/filename	^[^<>:;,?"*|/]+$	Valid filename
string_property_type/email	RFC 5321	E-mail address
string_property_type/uri	RFC 3986	Uniform Resource Identifier
string_property_type/url	RFC 3986	Uniform Resource Locator (http/https/ftp)
string_property_type/lua_script	--	Lua scripting code

Multi-Language Types

Values are locale maps with locale codes as keys:

Reference	Description
multi_lang_property_type/generic	Localized string
multi_lang_property_type/standard_label	Localized display name
multi_lang_property_type/standard_description	Localized description

{ "name": { "en_us": "Potato", "de_de": "Kartoffel" } }

Rich Text

Reference	Description
rich_text_property_type/generic	Formatted/rich text content

Rich text values are stored as raw JSON with an html key:

{ "content": { "html": "<p>Detailed description...</p>" } }

Entity Reference Types

Properties that hold a reference to another entity:

Reference	Target	Description
entity_property_type/file_ref	entity_type/file	Reference to a file entity
entity_property_type/entity_type_ref	entity_type/entity_type	Reference to an entity type

BLOB Properties

A blob_property_type/generic property stores a reference to a binary object (image, document, file, etc.) held in an external S3-compatible object store. Only the reference is stored in the database; the binary data lives in the blob store.

Declaring a BLOB Property

"has_prop": [
    {
        "properties": { "name": "photo", "label": { "en_us": "Photo" }, "required": false },
        "target": "blob_property_type/generic"
    }
]

Wire Format (Read)

When reading an entity, a BLOB property is serialized as:

{
    "blob_id":  "<uuid>",
    "store_id": "default"
}

Immediately after entity creation where a BLOB property was supplied, an @upload_url is additionally included:

{
    "blob_id":     "<uuid>",
    "store_id":    "default",
    "@upload_url": "<presigned S3 PUT URL>"
}

This allows skipping the explicit @upload call on initial creation.

Wire Format (Write)

On create or update, supply the blob_id UUID as a plain string. Passing null clears the reference.

{ "properties": { "photo": "<blob-uuid>" } }

Full Upload Workflow

Uploading a binary file to a BLOB property is a three-step process:

1. Request a presigned URL -- PUT /properties/<prop>/@upload on the entity. Returns a blob_id and a presigned S3 upload URL (valid for 5 minutes).
2. Upload binary data -- PUT the file bytes directly to the presigned URL. This request goes to S3 and bypasses EP.Core entirely.
3. Store the reference -- Update the entity, setting the BLOB property value to the blob_id received in step 1.

sequenceDiagram
    participant Client
    participant EP as EP.Core
    participant S3 as Blob Store
    Client->>EP: PUT /properties/photo/@upload
    EP-->>Client: { blob_id, upload_url }
    Client->>S3: PUT upload_url (file bytes)
    S3-->>Client: 200 OK
    Client->>EP: PUT / { properties: { photo: blob_id } }
    EP-->>Client: Updated entity

See REST API Reference for the complete @download and @upload route documentation.

Enum Properties

An enum property constrains a property value to one of a predefined set of named entries. See Enums for the full enum system documentation.

Declaring an Enum Property

"has_prop": [
    {
        "properties": { "name": "color", "label": { "en_us": "Color" }, "required": false },
        "target": "enum_property_type/fruit_color"
    }
]

Wire Format

Both input and output use the plain string value:

{ "properties": { "color": "red" } }

Internally, the engine resolves the string to the stable root_id UUID of the matching enum_entry and stores that UUID. This means enum entry labels, int mappings, and even the string value itself can change without breaking stored references.

Built-in Enum Instances

Reference	Description
enum_property_type/generic	Generic enum property (no specific enums entity)

Property Value Types Summary

JSON type	Stored as	Example
number	int or float	5, 3.14
"string"	plain string	"hello"
true / false	bool	true
{ "en_us": "...", ... }	multi-language string	{ "en_us": "Potato", "de_de": "Kartoffel" }
{ "html": "..." }	rich text (raw JSON)	{ "html": "<p>...</p>" }
"<uuid>"	BLOB reference	"a1b2c3d4-..."