Readwyn 0.1.0

What metadata is inside an EPUB?

An EPUB 3 file needs only four pieces of metadata: dc:identifier, dc:title, dc:language, and exactly one dcterms:modified timestamp. EPUB 3.3 makes everything else optional, the author included. Its own minimal example is Norwegian Wood with an identifier, a title, the language en and a timestamp, and no Murakami anywhere. The record sits in the metadata section of the package document, the .opf file described in what is inside an EPUB file.

Where the dc: names come from

The dc: prefix stands for Dublin Core, and the Dublin is the one in Ohio. OCLC and the National Center for Supercomputing Applications held a workshop there in March 1995, where more than 50 people worked on a common set of terms for describing things on the web, and named the result after the town. Its fifteen elements became a standard in 1998 as IETF RFC 2413, and were later published as ANSI/NISO Z39.85 and ISO 15836. EPUB takes all fifteen. Besides the three required ones, a package can hold creator, contributor, publisher, date, description, subject, rights, type, format, source, relation and coverage.

Order and format

Position in the file carries meaning. The first dc:title is the main title that apps show, and the first dc:language is the primary language. Among authors, the first dc:creator is the primary one, and the order of the others sets their display priority. A second dc:title is allowed but discouraged, because apps handle it inconsistently: some drop the extra part, others join the parts in unexpected ways.

dc:language takes a BCP 47 tag such as en-US. The chapters don't inherit it, so each one has to declare its own language.

dc:identifier can be a UUID, a DOI or an ISBN. One of them must have an id that the package element names in its unique-identifier attribute, and publishers are asked to keep it when they only fix errata or correct the metadata. An ebook doesn't always need an ISBN of its own; ISBNs for ebooks explains when it does.

EPUB 3 allows at most one dc:date, and it means the date of publication. The last change goes in dcterms:modified, in UTC and in exactly the form 2016-01-01T00:00:01Z. A value without the seconds or the final Z is invalid.

EPUB 2 and EPUB 3 compared

EPUB 2's package format, OPF 2.0.1, became a recommended specification on 4 September 2010. It wrote extra detail as opf: attributes on the Dublin Core elements. EPUB 3 moved it into separate meta elements that point at an element's id through a refines attribute.

What is recordedEPUB 2 (OPF 2.0.1)EPUB 3 (EPUB 3.3)
Requiredtitle, identifier, languagetitle, identifier, language, dcterms:modified
Creator's roleopf:role="aut"meta with property="role"
Name for sortingopf:file-asmeta with property="file-as"
Kind of identifieropf:scheme="ISBN"identifier-type, where ONIX code 15 is a 13-digit ISBN
Datesseveral dc:date, told apart by opf:eventone dc:date, plus dcterms:modified
Cover imagean OPF 2 meta elementcover-image on the manifest item
Seriesnot definedbelongs-to-collection

An EPUB 3 file may still carry the old meta element for EPUB 2 reading systems, but EPUB 3 reading systems don't use it.

Roles and sort names

Roles are usually codes from the Library of Congress's MARC relator list. OPF 2 made that list the normative one. In EPUB 3 a role can come from any code list that a scheme attribute names, and the spec's examples use MARC. The list now has about 300 coded terms, from aut (author) and trl (translator) to nrt (narrator) and cov (cover designer). Someone with two jobs gets two role entries: the spec's example is Maurice Sendak as both aut and ill. OPF 2 required the codes in lower case and allowed a home-made role only under the prefix oth.. The list has moved since: OPF 2 printed aui for the author of an introduction, and the Library of Congress now sends that term to win, wfw or wpr, for an introduction, a foreword or a preface.

OPF 2 treats a contributor like a creator, except that their part in the book was secondary. An app with no better method was told to show every creator in the order given, and was free to leave contributors out (OPF 2.0.1, sections 2.2.2 and 2.2.6).

The file-as value is what lets an app shelve Lewis Carroll under C. OPF 2's own example files "Rev. Dr. Martin Luther King Jr." as "King, Martin Luther Jr.". A sibling property, alternate-script, holds the name in another writing system, so Haruki Murakami can also appear as 村上 春樹 with xml:lang="ja".