Entities

Introduction

An entity is an identifiable 'thing' relevant to heritage. For example: 'The Night Watch' (a painting), 'Rembrandt' (a person), 'Amsterdam' (a place) and 'Brabantine Gothic' (a concept) are all entities.

Entities are what every integration layer is about. They are the heritage information that an integration layer exposes through its API. Presentation layers present this information to their users. Everything else the integration layer publishes — collections, facet values, keyword values — serves the entities: it organises, groups or finds them.

Data model

An entity is a specialisation of a Resource: it has an id, a type and a name. An entity is abstract: there is no entity whose type is Entity. Every entity has one of the concrete types that an integration layer defines, published as part of its type vocabulary.

The following class diagram visualises how entity types relate to a Resource and to each other. It shows two examples of the concrete types an integration layer can define, 'Heritage object' and 'Person':

Entity types

An entity can be of any type. An integration layer decides which types are relevant to its API and the presentation layers it serves.

For example, an integration layer that exposes information about...

1. all sorts of heritage objects where the exact type does not matter, defines the generic entity type 'Heritage object';
2. books and cars defines the specific entity types 'Book' and 'Car';
3. historical places defines the specific entity types 'City', 'Town' and 'Hamlet';
4. datasets with heritage information defines the specific entity types 'Dataset' and 'Distribution'.

The following table provides examples of common entity types:

Entity type name	Description
Heritage object	A valued object, e.g. a building, painting, book or document.
Person	A human being.
Organisation	An organised group of people.
Place	A spatial extent on the Earth's surface.
Concept	A unit of thought.
Event	A thing that happened at a certain time and location.
Story	An account of an event.
Dataset	A collection of data, e.g. data about heritage objects.
Digital object	A digital representation of an entity, e.g. an image of a heritage object.

Recommended data models

To do

Describe the recommended data models (e.g. for a heritage object, a person, a place) using Schema.org concepts.

To do

Explain data modelling requirements, e.g.:

• An entity must have a publisher (e.g. publisher)
• An entity must refer to the entity IRI of the data provider (e.g. isBasedOn)
• An entity must have a licence (e.g. license)
• An entity must have an ID that a presentation layer can use, e.g. for bookmarking by users (e.g. identifier)
• An entity must expose the collections it is a member of. A presentation layer can then offer a 'more like this' or 'more from this collection' functionality.

Assigning identifiers to entities

Every entity has a URI. A presentation layer uses that URI to retrieve the entity: requesting it returns the entity via the Retrieve an entity endpoint. The URI is also the identifier of the entity: wherever the entity appears — for example, in the items of a collection or in the properties of another entity — the integration layer refers to it with this same URI.

The URI of an entity always has the form /{version}/entities/{entity}:

• {version} is the version of the API of the integration layer.
• entities is fixed. Every entity URI contains it.
• {entity} is the path identifier, and it is variable. The integration layer determines it.

The id of an entity is its full URI, for example https://example.org/v1/entities/1234: the API uses this URI wherever it refers to the entity. The path identifier {entity} is the part after /entities/, for example 1234. The requirements and examples in this section are about the path identifier.

The integration layer MUST determine the {entity} in line with the following requirements:

1. The {entity} MUST be unique: two different entities never have the same {entity}.
2. The {entity} MUST be deterministic: when the integration layer processes the data of a data provider again, it must yield the same {entity}. The entity may have changed properties in between, but its source identifier — the identifier that the data provider assigned to it — stays the same: that is how the integration layer recognises the entity as the same one. The {entity} MUST therefore be traceable to that source identifier. Otherwise a presentation layer cannot use the URI — for example, in the web address of a detail page, or when a user bookmarks, saves or favourites an entity.
3. The {entity} MUST not change when the version of the API changes: /v1/entities/{entity} may become /v2/entities/{entity}, but the {entity} stays the same.

These requirements do not promise that an {entity} stays the same forever. An integration layer cannot guarantee that: it depends on the data provider, and the source identifier may itself change.

The integration layer MAY choose any approach that satisfies the requirements of this section. The following approaches are examples of what an {entity} may look like:

• The {entity} is the source identifier. For example, the source identifier of 'The Night Watch' is https://id.rijksmuseum.nl/200107928. The URI of the entity is https://example.org/v1/entities/https%3A%2F%2Fid.rijksmuseum.nl%2F200107928 (encoded so that it fits in a URI).
• The {entity} is a hash of the source identifier. For example, the hash of the source identifier of 'The Night Watch' is 874f078c5723abf6f0d86dffbbb827b6c82cd0a26ee6c7657519cbab830cef4d (created with the BLAKE3 hashing algorithm). The URI of the entity is https://example.org/v1/entities/874f078c5723abf6f0d86dffbbb827b6c82cd0a26ee6c7657519cbab830cef4d.
• The {entity} is an identifier generated by the integration layer, traceable to the source identifier. For example, {entity} is a number (1234) or a Nano ID (d8fe02e4), assigned the first time the integration layer processes the entity and reused afterwards. The URI of the entity is https://example.org/v1/entities/1234.

Endpoint: Retrieve an entity

The endpoint retrieves an entity. The integration layer MUST implement this endpoint if it publishes at least one entity.

HTTP request

GET /{version}/entities/{entity}

Path parameters

Name	Data type	Cardinality	Description
version	string	1	The version of the API. Example: v1.
entity	string	1	The path identifier of the entity. Example: 1234.

Query parameters

None.

Request body

None.

Response body

The response body MUST contain at least the properties underneath. Additional properties depend on the data model of the entity, defined by the integration layer.

Name	Data type	Cardinality	Description
@context	string	1	The URI of the JSON-LD context that maps the terms in the response to URIs.
id	string	1	The identifier of the entity.
type	string	1	The type of the entity.
name	string	1	The name of the entity.

Example

An example request from a presentation layer:

GET /v1/entities/1234
Host: example.org

The request indicates that the integration layer should return the entity with path identifier 1234.

The response body depends on the data model of the entity. An example:

{
  "@context": "https://example.org/v1/context.json",
  "id": "https://example.org/v1/entities/1234",
  "type": "HeritageObject",
  "name": "The Night Watch",
  "additionalTypes": [
    {
      "id": "https://example.org/v1/entities/1122",
      "type": "Concept",
      "name": "Painting"
    }
  ],
  "description": "Rembrandt’s largest, most famous canvas was made for the Arquebusiers guild hall...",
  "dateCreated": "1642",
  "creators": [
    {
      "id": "https://example.org/v1/entities/5678",
      "type": "Person",
      "name": "Rembrandt"
    }
  ],
  "locationsCreated": [
    {
      "id": "https://example.org/v1/entities/9012",
      "type": "Place",
      "name": "Amsterdam"
    }
  ]
  // Other properties...
}

The response indicates that this entity is a HeritageObject and has name 'The Night Watch'. It is linked to other entities of types Concept, Person and Place.

note

This specification does not define an endpoint that retrieves a list of all entities. A presentation layer finds the entities of an integration layer through curated collections. An integration layer groups its entities into these collections, and a presentation layer browses a collection or filters its items to find the entities it needs.