Data model overview
The VLIZ DAMS is a semantic data platform: every record is an entity of a known type, and entities are linked by named relations. The schema is defined in JSON-schema validators in clients/vliz-dams/client-collection-module/api/apps/vliz/validation/, which is the source of truth for this documentation.
Entity categories
Entities fall into two broad categories.
1. Content entities (full records)
These have rich metadata and many relations. They are what users curate day-to-day.
| Entity | Description |
|---|---|
| Album | Groups of related media (e.g. a fieldwork campaign, an archive sub-collection). |
| Media | A single logical asset; wraps one or more mediafiles. |
| Mediafile | The actual binary plus per-file metadata (filename, license, copyright, owner). |
| Map | Cartographic asset with projection, scale, bounding box, dates. |
| Publication | Document-style content typed by content and formal document types. |
| Document | A separate document entity (similar shape to publication). |
| ArchivalCollection | A long-running collection requiring an archive_creator. |
| CollectionPart | A subdivision of an archival collection (hierarchical). |
2. Vocabulary entities (controlled lists)
Light-weight entities with a title (or name) and a small set of fields. They exist to be linked to from content entities.
| Entity | Source |
|---|---|
| Keyword, Language, Context, AssetCategory, Confidentiality, Projection | Local VLIZ DAMS |
| License, Event, Project, Partner, MarineRegion, Person | Two flavours: a local *Validator and a federated *ElodyValidator (from the VLIZ vocab server) |
| FormalDocumentType, ContentDocumentType, FormalMapType, ContentMapType | Local taxonomies for typed documents and maps |
Federated vocabularies
For some entity types (license, event, project, partner, marine region) there are two validators: one for entities created locally and one for entities synced from the VLIZ vocab server. The vocab-server flavour adds fields like external IDs and source URLs.
Diagrams
The data model has too many entities to fit comfortably into one diagram, so it's split below into four focused views. All four together cover everything in the validators.
Legend
Solid arrow = stored relation. Dashed arrow = virtual / reverse relation (computed at read time). (R) marks a required relation.
1. Content hierarchy: Album → Media → Mediafile
How everyday content nests. An Album groups multiple Media records; each Media wraps one or more Mediafile binaries; mediafiles can also nest (derivatives / versions).
2. Archival side: ArchivalCollection → CollectionPart → content
The archival hierarchy. ArchivalCollection sits at the top; it contains CollectionParts (which can themselves nest); both expose virtual reverse relations to the content they aggregate.
Album is not a node here
Albums don't link directly to ArchivalCollection or CollectionPart. The connection runs through the Media records the album contains.
3. Mediafile metadata
What attaches to a single Mediafile beyond its parent media.
4. Required relations at a glance
| Entity | Required |
|---|---|
| Album | title, has_context |
| Media | title, has_context |
| Mediafile | (none enforced; belongs_to is set automatically) |
| Map | title, has_context, has_content_map_type, has_formal_map_type, date_description |
| Publication | title, has_context, has_content_document_type, has_formal_document_type |
| Document | title, inventory_number, has_context, has_content_document_type, has_formal_document_type |
| ArchivalCollection | title, has_context, has_archive_creator |
| CollectionPart | title, has_context |
5. Vocabulary usage matrix
Which content entity links to which controlled list. Cells with a ✓ mean the relation exists; ★ marks federated (vocab-server) targets.
| Vocab / relation target | Album | Media | Mediafile | Map | Publication | Document | ArchivalCollection | CollectionPart |
|---|---|---|---|---|---|---|---|---|
| Context (R) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | |
| Keyword | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Language | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| AssetCategory | ✓ | ✓ | ||||||
| Confidentiality | ✓ | |||||||
| License ★ | ✓ | |||||||
| MarineRegion ★ | ✓ | ✓ | ||||||
| Event ★ | ✓ | ✓ | ||||||
| Project ★ | ✓ | ✓ | ||||||
| Partner ★ | ✓ | ✓ | ||||||
| Person — owner | ✓ | ✓ | ✓ | ✓ | ||||
| Person — creator | ✓ | ✓ | ✓ | |||||
| Person — photographer | ✓ | ✓ | ||||||
| Person — archive_creator | ✓ (R) | |||||||
| Person — person | ✓ | |||||||
| Location | ✓ | ✓ | ||||||
| Projection | ✓ | |||||||
| Coord. Ref. System | ✓ | |||||||
| ContentMapType (R) / FormalMapType (R) | ✓ | |||||||
| ContentDocumentType (R) / FormalDocumentType (R) | ✓ | ✓ |
Where to next
- Entity reference — field-by-field tables for each major entity.
- Relations & vocabularies — which entities can link to which.
- CSV import — the most common way to populate entities at scale.