Entity map
Work
Conceptual creation, canonical title, original language, subjects, and relationships.
Edition
Publisher, date, format, language, extent, identifiers, contributors, and covers.
Contributor
Person or organization plus credited names, roles, order, and authority mappings.
Scan
A digitized physical source with pages, rights, capture details, and processing versions.
Artifact
OCR text, summary, embedding, classification, or answer linked to exact inputs and versions.
Item + Offer
Physical copy, condition evidence, seller, price, quantity, availability, and terms.
Identifiers
Store identifiers as typed rows with scheme, value, normalized value, scope, source, and validation state. ISBNs normally scope to editions or product forms. Provider IDs remain mappings. Internal IDs survive provider changes, merges, and splits.
Contributions, not one author string
Represent a contribution relationship with contributor ID, credited name, role, order, work or edition scope, and source. This handles editors, translators, illustrators, narrators, organizations, pen names, and edition-specific responsibility.
Claims and selected values
For fields that conflict, store source claims. A selection rule or review chooses the normalized value exposed by default. Clients can request provenance expansions, while internal tools inspect alternatives and rejected claims. This design makes corrections explainable.
Relationship examples
- Edition realizes Work.
- Contribution credits Contributor on Work or Edition.
- Cover depicts Edition or belongs to Item.
- Scan digitizes a physical source of Edition.
- Artifact derives from Scan text or licensed text version.
- Item is a copy of Edition.
- Offer makes Item or stock available under seller terms.
Merge and split history
Catalog identity changes. Preserve redirects from merged internal IDs and record why a merge occurred. Support splits when two authors, editions, or works were incorrectly combined. Relationships and historical references should move through auditable migration events, not destructive overwrites.
Projection for clients
The internal model can be rich while responses remain compact. Search returns display fields and match reasons. Detail returns canonical resources with optional expansions. Review endpoints expose claims. Commerce and AI services reference the same edition ID without copying the entire catalog object.