Skip to main content

What is an Entity?

Before we dive into the details of working with our system, let's clarify what an entity is.
An entity is a fundamental building block in our system, representing a distinct object or concept.
Entities can be anything from a person, place, or event to more abstract concepts like ideas or products.
Each entity has a unique identifier and can have various properties associated with it, such as name, description, and relationships to other entities. These properties are defined by our data model (What is the Datamodel?), which defines the structure and types that entities can have.

We have two different representations of an entity: the Entity and the Indexed Entity.
The Entity is the full representation of an entity, including all its properties, metadata, and relationships.
The Indexed Entity is a simplified version of the entity that includes only the properties that are indexed and searchable.
This Information is important because each endpoint consumes or produces a different representation of an entity.

As a rule of thumb, you can remember that everything that enters the system has the form of an entity, and everything that leaves the system has the form of an indexed entity.

Entity​

An entity has besides his fields that are defined in the datamodel, also some additional metadata.

{
    "_id": "18ee1089c718bf6ac88ea346",
    "types": [
        "schema:Event",
        "venus:HikingTrip"
    ],
    "project": "18ee1049b719bf6ac88ea346",
    "channels": [
        "18ee1049b719bf6ac88ea347"
    ],
    "pools": [
        "18ee1049b719bf6ac88ea348"
    ],
    "content": {
        // Part of schema:Thing
        "schema:name": [
            {
                "lang": "de-DE",
                "value": "Wanderevent 2025"
            },
            {
                "lang": "en",
                "value": "Hiking event 2025"
            }
        ],
        // Part of schema:Event
        "venus:eventSchedule": [
            {
                "startDate": "2025-10-11T08:00:00.000+02:00",
                "endDate": "2025-10-11T14:00:00.000+02:00",
                "doorTime": "09:30"
            }
        ],
        "schema:location": [
            {
              "_id": "18ee1049b719bf6ac88ea349"
            }
        ],
        // Part of venus:HikingTrip
        "schema:audience": [
            "venus:family",
            "venus:couples",
            "venus:kids"
        ]
    },
    "createdAt": "2025-10-10T10:05:10.023+0000",
    "updatedAt": "2025-10-10T11:10:32.363+0000",
    "deletedAt": "2025-10-14T08:57:44.105+0000"
}

The fields in the entity are:

_id​

The unique identifier of the entity. This is a string that is generated by the system and is used to reference the entity in other parts of the system.

types​

The types define the structure of the entity. Each type comes with its own set of properties.
To learn more about the types, have a look at the Datamodel.

project​

The project the entity belongs to.

channels​

The channels the entity belongs to. Channels are used to group entities together and can be used to filter entities by channel. \

pools​

The pools the entity belongs to. Pools are used to group entities together and can be used to filter entities by pool. \

content​

The content of the entity contains actual data of the entity.
As before mentioned the content is defined by the types of the entity.
In this example, the entity contains the types schema:Event and venus:HikingTrip.
This means that the content can contain properties from both types.

schema:name​

The name of the entity is part of the schema:Thing type.
It is a required property and can have multiple values in different languages.
In this example, the entity has two names, one in German (de-DE) and one in English (en).

venus:eventSchedule​

The event schedule is part of the schema:Event type.
It contains the start and end date of the event, as well as the door time.
In this example, the event starts on October 11, 2025, at 08:00 and ends at 14:00.
The door time is set to 09:30.

schema:location​

The location is part of the schema:Event type.
Location is a reference to another entity that represents the location of the event.
In this example, the location is a reference to another entity with the ID 18ee1049b719bf6ac88ea349.
This entity must be from type schema:Place.

schema:audience​

The audience is part of the venus:HikingTrip type.
It contains the target audience of the event.
In this example, the audience is set to venus:family, venus:couples, and venus:kids. \

createdAt​

The date and time when the entity was created. \

updatedAt​

The date and time when the entity was last updated. \

deletedAt​

The date and time when the entity was deleted.
This field is only present if the entity has been deleted.
If the entity has not been deleted, this field is not present.

Indexed-Entity​

An indexed entity is a search-/import-/frontend-optimized entity that only contains a subset of the properties of the entity.
It is used to speed up search queries and to reduce the amount of data that needs to be transferred over the network.
The significant difference between an entity and an indexed entity is that the indexed entity does not hold its content in the content field, but in the top-level fields.
The indexed entity is created from the entity and is updated whenever the entity is updated.

{
    "_id": "68348027293493b36f19d032",
    "types_all": [
        "schema:Event",
        "schema:Trip",
        "schema:Intangible",
        "schema:Thing"
    ],
    "types": [
        "schema:Event",
        "venus:HikingTrip"
    ],
    "project": "18ee1049b719bf6ac88ea346",
    "channels": [
        "18ee1049b719bf6ac88ea347"
    ],
    "pools": [
        "18ee1049b719bf6ac88ea348"
    ],
    "remoteIdentifiers": [],
    // Start entity content
    // Part of schema:Thing
    "schema:name": [
        {
            "lang": "de-DE",
            "value": "NAH AM FUNDAMENT"
        }
    ],
    // Part of schema:Event
    "venus:eventSchedule": [
        {
            "id": "fcf4c420-3131-4cba-9ead-63b870f1637a",
            "startDate": "2025-10-11T06:00:00.000Z",
            "endDate": "2025-10-11T12:00:00.000Z",
            "doorTime": "09:30",
            "startTimezone": "Europe/Berlin",
            "endTimezone": "Europe/Berlin"
        }
    ],
    "pseudo:timeline": [
        {
            "id": "83da288f-7ed5-4449-a80c-bcd96e97712e",
            "parent": "fcf4c420-3131-4cba-9ead-63b870f1637a",
            "startDate": "2025-10-11T06:00:00.000Z",
            "startTimestamp": 1760162400000,
            "startTimezone": "Europe/Berlin",
            "endDate": "2025-10-11T12:00:00.000Z",
            "endTimestamp": 1760184000000,
            "endTimezone": "Europe/Berlin",
            "allDay": false
        }
    ],
    "pseudo:timelineMeta": {
        "minDate": "2025-10-11T06:00:00.000Z",
        "maxDate": "2025-10-11T12:00:00.000Z"
    },
    "schema:location": [
        {
          "_id": "18ee1049b719bf6ac88ea349"
        }
    ],
    "schema:location_content": [
        {
            "_id": "18ee1049b719bf6ac88ea349",
            "schema:name": [
                {
                    "lang": "de-DE",
                    "value": "Deutsche Staatsphilharmonie Rheinland-Pfalz"
                }
            ],
            "schema:description": [
                {
                    "lang": "de-DE",
                    "value": "Staatsphilharmonien Rheinland-Pfalz"
                }
            ],
            "types_all": [
                "schema:PerformingGroup",
                "schema:Place",
                "schema:Thing",
                "schema:Organization"
            ],
            "raw": "{...}"
        }
    ],
    // Part of venus:HikingTrip
    "schema:audience": [
        "venus:family",
        "venus:couples",
        "venus:kids"
    ],
    "schema:audience_fulltext": [
        {
            "value": "venus:family",
            "title": "Familie(n)"
        },
        {
            "value": "venus:couples",
            "title": "Paare"
        },
        {
            "value": "venus:kids",
            "title": "Kinder"
        }
    ],
    // End entity content
    "version": 142,
    "linkedEntities": [
        {
            "_id": "67ab04ff8eebdddb7732bfbf",
            "field": "schema:performer"
        }
    ],
    "createdAt": "2025-10-10T10:05:10.023+0000",
    "updatedAt": "2025-10-10T11:10:32.363+0000",
    "indexedAt": "2025-10-10T11:10:38.130+0000"
}

The fields in the indexed entity are:

_id​

see _id in the entity.

types_all​

The types_all field contains all types of the entity, including the base types.
This is useful to understand the full structure of the entity and to filter entities by type. \

types​

See types in the entity.

project​

See project in the entity.

channels​

See channels in the entity.

pools​

See pools in the entity.

remoteIdentifiers​

For more information about remote identifiers, have a look at the Remote Identifiers documentation.

schema:name​

See schema:name in the entity.

schema:eventSchedule​

See venus:eventSchedule in the entity.

psuedo:timeline​

The pseudo:timeline field contains the timeline of the event.
Its aggregated from the venus:eventSchedule field and contains the start and end date of the event, as well as the door time. \

For more information about the timeline, have a look at the Pseudo Fields documentation.

pseudo:timelineMeta​

The pseudo:timelineMeta field contains the minimum and maximum dates of the timeline.
This is useful to understand the time range of the event and to filter events by date. \

For more information about the timeline, have a look at the Pseudo Fields documentation.

schema:location​

See schema:location in the entity.

schema:location_content​

_content is a special field that contains the content of the linked entity.
It's generate for every property that that has the Data Type Entity With this data field it is possible to filter and search for entities by their content. \

schema:audience​

See schema:audience in the entity. \

schema:audience_fulltext​

_fulltext is a special field that contains the fulltext representation of the schema:audience field.
It's generated for every property that has the Data Type Enumeration
This is useful to filter and search for entities by their audience. \

version​

The version of the entity. This is a number that is incremented every time the entity is updated.
This is useful to understand if the entity has been updated since the last time it was fetched.

createdAt​

See createdAt in the entity.

updatedAt​

See updatedAt in the entity.

deletedAt​

See deletedAt in the entity.