Relations & vocabularies

In the VLIZ DAMS, almost everything is connected to something else. This page covers two practical questions:

1. Which entities can I link to which?
2. What is the difference between a relation, a vocab link, and a virtual relation?

Relation kinds

Direct relations

A direct relation is a stored link from one entity to another. Set on creation/update; persists in the database. Most fields prefixed with has_ are direct relations:

Media.has_album → Album
Mediafile.has_owner → Person
ArchivalCollection.has_archive_creator → Person  (required)

Vocab relations

Some relation targets are sourced from the VLIZ vocab server rather than from the DAMS database. The shape on the entity is the same (a has_* link), but the target entity is fetched / synchronised from an external source.

Vocab-backed targets currently include: MarineRegion, Event, Project, Partner, License. Some of these have two validators — one for the federated/vocab-server flavour (*_elody_validator.py) and one for entities created directly in the DAMS (*_validator.py). Both flavours are valid link targets.

Linking by ID vs title

Most CSV importers accept either the canonical id (UUID, or vocab-server identifier such as an MRGID) or the human-readable title. If the title resolves uniquely it will be used; otherwise the import errors out with a list of candidates.

Virtual relations

A virtual relation is a reverse link that is computed at read time. You don't set it; it appears on an entity because something else points at it.

Examples:

Virtual relation	Computed from
Album.has_media	reverse of Media.has_album
ArchivalCollection.has_collection_part	reverse of CollectionPart.has_archival_collection
ArchivalCollection.has_media	reverse of Media.has_archival_collection
CollectionPart.is_collection_part_for	reverse of CollectionPart.has_collection_part
Context.has_user	reverse of access-control links

Virtual relations show up in the UI and in GraphQL responses; they are not editable from a CSV.

What can link to what

A condensed view — see Entity reference for the full per-entity field list.

From entity	Can link to
Album	Context (req.) · Album (parent) · Keyword · Language · AssetCategory · MarineRegion · Person (owner / photographer) · Event · Project · Partner · Location (not directly to ArchivalCollection / CollectionPart — that runs through Media)
Media	Context (req.) · Album · ArchivalCollection · CollectionPart · Keyword · Language · AssetCategory · MarineRegion · Person (owner / creator / photographer) · Event · Project · Partner · Location
Mediafile	Media (parent, auto) · Mediafile (parent for versioning) · Confidentiality · License · Keyword · Language · Person (creator / owner / person)
Map	Context (req.) · ContentMapType (req.) · FormalMapType (req.) · ArchivalCollection · Keyword · Language · Projection · Person (creator / owner) · CoordinateReferenceSystem
Publication	Context (req.) · ContentDocumentType (req.) · FormalDocumentType (req.) · Keyword · Language
ArchivalCollection	Context (req.) · Person via has_archive_creator (req.) · Keyword · Language · (virtual) CollectionPart, Media, Map, Publication
CollectionPart	Context (req.) · ArchivalCollection · CollectionPart (parent) · Keyword · Language · (virtual) CollectionPart, Media, Document

Federated vs local vocab entities

A few entity types exist in two flavours:

Entity	Local validator	Federated/vocab validator
Event	event_validator.py	event_elody_validator.py
License	license_validator.py	license_elody_validator.py
MarineRegion	marine_region_validator.py	marine_region_elody_validator.py
Partner	partner_validator.py	partner_elody_validator.py
Project	project_validator.py	project_elody_validator.py

The federated flavour stores the source identifier (e.g. an MRGID for a marine region) and is updated from the VLIZ vocab server. Use these when you want canonical, shared values; use the local flavour for VLIZ-internal additions.

Typical pitfalls

• Required relation forgotten. has_context is required on every content entity; has_archive_creator is required on ArchivalCollection; map and publication require their has_content_*_type and has_formal_*_type.
• Linking to the wrong vocabulary flavour. Both flavours are valid — just be aware which one the title resolves to.
• Trying to set a virtual relation. It will be silently ignored; set the inverse on the other entity instead.
• Trying to set belongs_to on a mediafile by hand. The importer wires this automatically when it places a mediafile in the same row group as a media entity.