Traits

Traits are dynamic mixins that can be attached to any entity instance regardless of its type. Unlike properties and relationships declared on the entity type, traits are not part of the type schema -- they are added at the instance level.

This makes traits ideal for cross-cutting concerns that apply to some, but not all, instances of a type.

Trait Type Definition

A trait type is defined as an entity of type entity_type/trait. It declares its own properties via has_prop, just like any other entity type.

{
    "key": "is_semantically_tagged",
    "properties": {
        "name": "is_semantically_tagged",
        "label": { "en_us": "Semantically tagged" },
        "description": { "en_us": "Trait to semantically describe an Entity" }
    },
    "relationships": {
        "has_prop": [
            {
                "properties": { "name": "semantic_tag", "label": { "en_us": "Semantic Tag" }, "required": true },
                "target": "string_property_type/uri"
            }
        ]
    }
}

Applying a Trait to an Instance

Traits are applied when creating or updating an entity, using the traits field in the request body:

{
    "key": "tomato",
    "properties": {
        "name": { "en_us": "Tomato" },
        "weight": 3
    },
    "traits": {
        "is_semantically_tagged": {
            "properties": {
                "semantic_tag": "http://schema.org/tomato"
            }
        }
    }
}

Multiple traits can be applied to the same entity instance simultaneously.

Wire Format

Response Shape

In API responses, traits appear under the traits field of the entity object:

{
    "traits": {
        "is_semantically_tagged": {
            "type_id":       "<uuid>",
            "properties":    { "semantic_tag": "http://schema.org/Potato" },
            "relationships": {}
        }
    }
}

Each trait object contains:

Field	Description
type_id	UUID of the trait type entity
properties	Trait property values
relationships	Trait relationship values (if the trait declares any)

Input Shape

When creating or updating, only supply the properties (and optionally relationships):

{
    "traits": {
        "is_semantically_tagged": {
            "properties": { "semantic_tag": "http://schema.org/potato" }
        }
    }
}

Trait Key Spaces

Trait property uniqueness is globally scoped. If a trait property is marked as unique, the value must be unique across all entities that carry that trait, regardless of their entity type.

This is in contrast to regular entity property uniqueness, which is scoped to the entity type. See Key Spaces for the full key space model.

Querying Entities by Trait

The API provides a dedicated route to find all entities that have a specific trait:

GET /api/v1/by-trait/<trait_name>

Returns all entities that have the named trait attached, regardless of their entity type.

See REST API Reference for details.

Built-in Traits

trait/is_preview_enabled

Attaches a preview file to any entity instance. Carries one property:

Property	Type	Description
preview_file_ref	entity_property_type/file_ref	Reference to an entity_type/file entity representing the preview

This trait uses an entity reference rather than a raw BLOB property -- the file entity is a first-class entity in the system and can carry its own metadata and lifecycle.

trait/is_semantically_tagged

Attaches a semantic tag URI to an entity, enabling semantic classification and integration with ontologies.

Property	Type	Description
semantic_tag	string_property_type/uri	A URI identifying the semantic concept (e.g. http://schema.org/Recipe)