API schema
Information about generic schema elements in the API
The main API for the Core platform contains all domain entities which are structured with similar schemas. On this page the conventions are documented which apply for most entities. You can find the exact schemas for each entity in the Rest API Reference.
Identification
The identification object of an entity identifies the entity with certain keys. Depending on the entity different keys are possible.
Key | Description |
id | This a internal UUID in the database. This key is generated immediately when creating an entity. |
publicId | This a human-readable identifier which is unique in the database. Almost all entities can have a public id. This key can be immediately generated when creating the entity, but this can also be done with an update, a special syntax is available for generating public id's for entities. |
draftId | Similar to publicId. But not all entities can have a draft id. This is only available for more transactional entities, like a Contract or an Invoice. |
externalId | This is an id which is determined externally which is treated as unique in the database. This can be your own application, or other application/systems for which you want to register an external id. Other examples could be a company chamber of commerce number or access point EAN. |
Common attributes
Most entities have attributes in common which are available in the API's.
Property | Description |
name | Used for a descriptive name of the entity |
type | Used as classification of the entity. Types can be configured per entity type. |
roles | Used to specify different roles for the entity, roles are used in the context of relations with other entities. For example, a party could have a supplier role in one relation and a reseller role in another relation. Roles can be configured per entity type. |
idGeneration | With id generation one or multiple id's can be generated when creating or updating the entity. Once generated it is immutable. |
definition | Used when an entity is created or updated by a definition. More information about definitions can be found here. Definitions can be used in conjunction with other attributes or related entities, but need to be handled with care because it can result in conflicts. |
extensions | Extensions are custom keys of specific data types to store additionally next to the common attributes. |
Related entities
Entities can be related to other entities. These relations are timesliced and can be active or inactive. The structure of a relation is the same for every entity.
Property | Description |
action | |
identification | The unique identification of the relation itself. |
'target entityType' | This represents the entity type which is related to. Eg party or asset. The identification of this target entity is used here. |
sourceRole | This is the role of the source entity (current entity which is queried, created or updated). The source entity must have this role. The role DEFAULT is always allowed. |
targetRole | This is the role of the target entity. The target entity must have this role. The role DEFAULT is always allowed. |
fromDate | This is the date from which the relation is valid. By default this is {{today}}. |
toDate | This is the date till which the relation is valid. By default this is 9999-12-31. The toDate can not be set, but is always set by the next relation. |
active | This specifies whether or not the relation is active. |
extensions | Additional custom keys can be stored on the relation. |
From date / To date logic
Relations are stored as similar to 'events', each relation is valid until a new relation is added. The previous relation is then updated with a toDate which equals the fromDate of the new relation. The previous relation remains active until that date, the new relation is active from the new from date. The latest relation always has a toDate of 31-12-9999.
Because there can be more relations to different entities, a key is composed to determine previous and next relations. The key is composed of the target entity and the sourceRole and the targetRole. This key is also used in combination with the fromDate to identify a relation.
toDate attribute is always automatically set to ensure that timeslices are contiguous and data integrity is maintained. Example for a party with relatedSites:
Nr | sourceRole | site | targetRole | fromDate | active | toDate |
1 | CUSTOMER | A | ADDRESS | 2022-01-01 | true | 9999-12-31 |
After adding a new relation to a new address per 17/01/2022:
Nr | sourceRole | site | targetRole | fromDate | active | toDate |
1 | CUSTOMER | A | ADDRESS | 2022-01-01 | true | 2022-01-17 |
1 | CUSTOMER | B | ADDRESS | 2022-01-17 | true | 9999-12-31 |
Handling gaps
In case of 'gaps', a relation may require to be inactive for a certain period of time. To do this, a new relation need to be added with active = false. Then the relation becomes inactive from that date. If a new active relation is after that date, from that date the new relation becomes active.
After adding a new 'inactive' relation per 20/01/2022:
Nr | sourceRole | site | targetRole | fromDate | active | toDate |
1 | CUSTOMER | A | ADDRESS | 2022-01-01 | true | 2022-01-17 |
1 | CUSTOMER | B | ADDRESS | 2022-01-17 | true | 2022-01-20 |
1 | CUSTOMER | B | ADDRESS | 2022-01-20 | false | 9999-12-31 |
After adding a new 'active' relation per 25/01/2022:
Nr | sourceRole | site | targetRole | fromDate | active | toDate |
1 | CUSTOMER | A | ADDRESS | 2022-01-01 | true | 2022-01-17 |
1 | CUSTOMER | B | ADDRESS | 2022-01-17 | true | 2022-01-20 |
1 | CUSTOMER | B | ADDRESS | 2022-01-20 | false | 2022-01-25 |
1 | CUSTOMER | B | ADDRESS | 2022-01-25 | true | 9999-12-31 |
After adding a new 'inactive' relation per 10/01/2022 in between 2 other relations:
Nr | sourceRole | site | targetRole | fromDate | active | toDate |
1 | CUSTOMER | A | ADDRESS | 2022-01-01 | true | 2022-01-10 |
1 | CUSTOMER | A | ADDRESS | 2022-01-10 | false | 2022-01-17 |
1 | CUSTOMER | B | ADDRESS | 2022-01-17 | true | 2022-01-20 |
1 | CUSTOMER | B | ADDRESS | 2022-01-20 | false | 2022-01-25 |
1 | CUSTOMER | B | ADDRESS | 2022-01-25 | true | 9999-12-31 |
Sources and targets
Sources and targets are similar to related entities, but with the difference that these are relations to the same entity type. For example, a party related to another party → “Customer” party related to “Contactperson” parties
Using sources and targets a hierarchy can be created.
- The
source entityis part of atarget entity
- The
target entityhas asource entity
If an entity is created and sources are added, the created entity represents the target entity in the relation.
On the other hand, if targets are added, the created entity represents the source entity in the relation.
Sources and targets only have 1 role. Normally it is a best practice to use it as the role of the source entity in the relation, but can be used differently per use case.
Timeseries
Entities can have timeseries directly or can be related to timeseries in the same way as other related entities (see paragraph above) with timeslicing and roles.
If an entity has timeseries directly linked, this entity is the 'owner' of these timeseries. This is an advantage in several features of the platform:
- Ingestion and enrichment of timeseries events using the 'owner' entity
- Lookup of distribution profiles in context of the 'owner' entity
- Aggregation of timeseries event data using the 'owner' entity
- Resolving calculation paths for timeseries in context of the 'owner' entity