---
type: Documentation
title: Data model
description: Which records Librario keeps, how they relate, and what identifiers and
  the publication date are called in the web app, the AI assistant (MCP) and REST
  API v3.
resource: https://www.librario.de/en/docs/grundlagen/datenmodell
language: en
revision: e114aa541d24c57e452957a2313c85d2014b716b
tags:
- docs
- grundlagen
---

# Data model

This page explains which records Librario keeps, how they relate to each other, and what they are called in the web app, in the AI assistant (MCP) and in REST API v3. It helps library teams, integrators and AI assistants keep similar-sounding terms apart: a publication is not a PDF, and an internal ID is not an ISBN.

## Publication, file, hard copy and borrowing transaction


The publication sits at the centre. Everything else hangs off it:

```text
Publication
├── publication type (exactly one, e.g. book, article, standard)
├── contributors: authors and editors (any number, ordered)
├── organisation (at most one)
├── identifiers (any number)
├── categories (any number)
├── parent publication (at most one)
├── files (any number)
└── hard copies (any number)
    └── borrowing transactions (any number, at most one open)
```

- **Publication** – the bibliographic record of a work: title, contributors, publication date, identifiers, keywords and categories. A publication exists without any file and without any hard copy. The [publication type](/en/docs/bibliothekswesen/publikationstypen) decides which extra fields exist, such as status and successors for standards.
- **File** – an uploaded file, usually a PDF. Every file belongs to exactly one publication. Full-text search reads the text of all of a publication's files.
- **Hard copy** – a physical copy on the shelf, described by its location and shelfmark. Every hard copy belongs to exactly one publication, and a publication has zero, one or many hard copies. A reference-only copy cannot be borrowed.
- **Borrowing transaction** (loan) – links a hard copy to the borrower, the borrowing date and, later, the return date. A hard copy has at most one open borrowing transaction. Closed ones stay on record as its history.
- **Loan request** – a task in which someone asks for a publication or places a hold on it. It is for the publication, not for a particular hard copy, and is not a borrowing transaction yet. Only when a copy is actually lent to the requester is the hard copy bound to the loan request (`hard_copy_id` is set). Then the borrowing transaction exists, and the loan request for that publication is marked done.

So "there is a PDF", "there is a hard copy" and "the hard copy is available" are three different statements. [Borrowing hard copies](/en/docs/grundlagen/leihexemplare-ausleihen) explains how loans work.

## Contributors and organisations

People and organisations are records of their own, shared by all publications in an account. Each name occurs once per account. The same person can be an author of one publication and an editor of another. Authors and editors keep the order in which they were entered.

- **Authors and editors** – people, together called contributors. A person record can carry GND, VIAF and ORCID identifiers and alternative names.
- **Organisation** – at most one per publication, for example the issuing institute, authority or standards body.

## Identifiers


Librario tells three kinds of identifier apart. Don't mix them up: only the third means anything outside Librario.

1. **Internal publication ID** – a number Librario assigns to every publication, for example `42`. It appears in the address of the publication page (`/publications/42`) and is the key for every MCP and REST API request. It is not bibliographic data: don't cite it, and don't look it up in external catalogues.
2. **File ID** – a UUID that every file gets. It addresses exactly one file, never the publication. An AI assistant needs it to download a file.
3. **Bibliographic identifiers** – values that name the work outside Librario too:
   - ISBN, ISSN, DOI, PubMed ID (PMID) and arXiv ID as typed fields. A publication can have several values of one type, such as the ISBNs of the print and the digital edition.
   - The "Identifier" field for everything else: standard designations such as `DIN EN 1992-1-1:2011-01`, patent numbers or in-house numbers. It also takes several values.

For standards, "Predecessors" and "Successors" refer to standard designations, not internal IDs. Librario links them to other standards in the library whose identifier matches exactly. The status "Active" or "Withdrawn" records what your library team entered. It is not a check of whether the standard applies today.

## The same data in the web app, MCP and REST API v3


The three ways in show the same records, but not under the same names and not always in full. MCP is built for reading and citing, the REST API for syncing and maintaining records.

| Item                            | Web app                                                      | MCP                                                                                                                       | REST API v3                                                                                        |
| ------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| Internal publication ID         | Address of the publication page: `/publications/42`          | `publication_id`; also `web_url`, and `resource_uri` (`librario://publications/42`) in `search_library`             | `id`                                                                                               |
| File ID                         | No field of its own                                          | `files[].file_id` from `get_publication`, the input for `download_file`                                                   | `assets[].id` in `GET /api/v3/publications/{id}`; one file at `/api/v3/assets/{id}`         |
| ISBN, ISSN, DOI, PMID, arXiv ID | Fields "ISBN", "ISSN", "DOI", "PubMed ID (PMID)", "arXiv ID" | `identifiers.isbn`, `.issn`, `.doi`, `.pmid`, `.arxiv_id`: the first value only                                          | `identifiers[]` with `type` (`isbn`, `issn`, `doi`, `pmid`, `arxiv_id`) and `value`: every value |
| Other identifiers               | Field "Identifier"                                           | `identifiers.generic[]`: every value                                                                                      | `identifiers[]` with `type: generic`                                                               |
| Hard copy                       | Location, shelfmark, reference-only copy, availability            | `hard_copies[]` with `location`, `shelfmark`, `reference_book`, `borrowing_status` (`available`, `borrowed`); no ID. `available` only means not on loan. `reference_book: true` marks a reference-only copy, which can be read on site but not borrowed | `/api/v3/hard_copies`: `id`, `uuid`, `location`, `shelfmark`, `reference_book`                     |
| Publication date                | Field "Publication date": `YYYY`, `YYYY-MM` or `YYYY-MM-DD`              | `published_on` as text, as recorded (`2021`, `2021-06` or `2021-06-15`); the `year` filter takes a year, a range (`1985-2010`) or a decade (`1970s`) | `published_on` as text, exactly as entered (`2021`, `2021-06` or `2021-06-15`)                     |

On the publication date: Librario stores it as EDTF level 0 (`YYYY`, `YYYY-MM` or `YYYY-MM-DD`) at the precision it was entered with, so a year alone, a year and month, or a full date. MCP and the REST API both return that text unchanged in `published_on`, so a missing month or day means it was not recorded. In MCP, `year` is a search filter only, not a result field.

## Categories, collections, favourites and tasks

These four all organise publications, but they differ in who owns them and who sees them.

- **Category** – a subject label for the whole account, for example "Fire safety". A publication can have several categories. Categories mainly serve as search filters. MCP returns them as a list of names (`categories`), the REST API as objects with `id`, `uuid` and `name`.
- **Collection** – a named, curated list with a description, such as a department's reading shelf. A publication can sit in several collections. Every signed-in user of the account sees and reads every collection. That is the viewer role the visibility form shows. The collection's owners and editors maintain it, as do administrators and librarians. MCP reads collections: `list_collections` finds them, `get_collection` shows one, and `search_library` with a `collection_id` lists its publications. It cannot change them. The REST API offers `/api/v3/collections` and the `collection_id` filter. See [managing collections](/en/docs/grundlagen/sammlungen-verwalten).
- **Favourite** – a personal star. Each person has their own list, which others can see on their user profile. MCP and the REST API filter with `starred_by` (`me` or a user ID). See [managing favourites](/en/docs/grundlagen/favoriten-verwalten).
- **Task** – a work item for the library team with a type, status, priority and, optionally, an assignee. Loan requests, quality reviews and duplicate reviews are examples. A task can refer to a publication, a person or organisation, a file or an import. MCP has no tasks. The REST API offers `/api/v3/tasks` with `type` and `reference`. See [task management](/en/docs/bibliothekswesen/aufgabenverwaltung).

## Grouping: series, parent publication and original title


Three fields bring related publications together. Only one of them is a real link between two records.

- **Series** (`series`) – free text. Publications with the same series title belong to the same series; there is no separate series record.
- **Parent publication** (`parent_publication`) – a link to another publication, such as from one volume to the multi-volume work. A publication has at most one parent but can itself have any number of children.
- **Original title** (`uniform_title`, the uniform title in library terms) – free text that brings together editions and translations of the same work.

| Field              | MCP                                                                   | REST API v3                                                                        |
| ------------------ | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| Series             | `series` in `search_library` results; `series` filter                 | `series`; `series` filter                                                          |
| Parent publication | `parent_publication_id` filter                                        | `parent_publication` as an embedded publication; `parent_publication_id` filter    |
| Original title     | `uniform_title` filter (exact match)                                  | `uniform_title` in the response and on create and update; `uniform_title` filter   |

`get_publication` returns none of the three. The [grouping guide](/en/docs/bibliothekswesen/best-practices/publikationen-gruppieren) explains which field fits when. The [field reference](/en/docs/bibliothekswesen/felder-referenz) lists every field with its format and an example.