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:

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 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 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.

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.
• 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.
• 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.

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.

get_publication returns none of the three. The grouping guide explains which field fits when. The field reference lists every field with its format and an example.