BB eBooks Banner

Documentation for the BB Meta Pad


The BB Meta Pad was written by the team at BB eBooks to assist in navigating the complicated and confusing metadata requirements for EPUB laid out by the International Digital Publishing Forum (IDPF) and Dublin Core, which is a Singaporean-based metadata initiative. All metadata generated by the BB Meta Pad should included in the <metadata> section of your OPF file. For more information on how the EPUB package is structured, please consult the BB eBooks EPUB 2.0.1 Tutorial. Sample boilerplate OPF files are available at the developers page provided by BB eBooks. You are welcome to use this app for commercial purposes.

The BB eBooks Meta Pad is not a one-click EPUB generator, but rather a handy tool to help you in your workflow as build your EPUB package. This web app is written in JavaScript with the jQuery library, and this application is used in-house at BB eBooks to aid in adding metadata for clients’ eBooks. If you have suggestions for new functionality you would like to see, please drop us a line, and we’ll see what we can do.

Basic Instructions

To use the BB Meta Pad, simply fill out the forms in the Required Metadata portion of the Control Panel and click on the button “Insert Required Metadata”. After that, you can fill out the optional metadata in the Control Panel and click “Add Optional Metadata”. This will insert the optional metadata right below the required metadata in your generated XML. If you need to add additional contributors in your metadata (such as photographers, editors, and other team players), simple fill out the fields in Extra Metadata and click “Add Extra Metadata”. All XML is generated in the textarea below the control panel for copying and editing convenience.

BB Meta Pad has been tested on Chrome, Firefox, and IE 9—older browsers may have issues. If you make a mistake, just press Ctrl-Z to undo. It goes without say that you should be saving backups of your content often during your workflow. BB Meta Pad has no server-side features, so everything lives in your browser.

Please note that all XML generated by the BB Meta Pad has been tested with EpubCheck for EPUB compliance.

Required Metadata Help

The IDPF requires that the following metadata be available in the OPF file for version 2.0.1 or it will fail EPUB validation. The IDPF spec on metadata in EPUB is here for your reference:

eBook’s Title: This is the content within the dc:title element. If you want to file your eBook as “Adventures of Huck Finn, The” rather than “The Adventures of Huck Finn”, you should annotate this in the title field. Do not use the file-as attribute in the dc:title element.

eBook’s Author: This is the name of the primary author and that should appear within the dc:creator element after you generate the required metadata from the Control Panel. The opf:role="aut" attribute is not required by the IDPF but suggested, which is why this attribute is automatically added in the Meta Pad. If you want to file the author’s name with their last name first, simply write that in the (file as) field in the Control Panel. This will add the file-as attribute within the dc:creator XML. If you want to file the metadata by the author’s first name, simply leave the (file-as) field in the Control Panel blank.

The Publisher: Even if you are self-publishing, this metadata is required. If you do not have a publishing company, simply add the author’s name. The BB Meta Pad will automatically add an XML entry within the dc:publishing element.

Publishing Date: This is the date the eBook is published. It should be in the YYYY-MM-DD format (e.g. 2012-07-04 for July 4th, 2012). The BB Meta Pad will automatically add an XML entry within the dc:date element.

ISBN or UUID: ISBN’s are expensive and most eBook stores do not require them. If you leave this blank, the BB eBooks Meta Pad will automatically generate a unique identifier for you (i.e. a UUID). If you insist upon using an ISBN, please keep in mind that it must be different for both the EPUB and MOBI versions. Also, ensure that you use this exact same metadata in your toc.ncx Table of Contents. Consult the boilerplate for examples.

Language: Enclosing the code for the eBook’s language within the dc:language element is required within the OPF file. The codes are from the RFC 3066 spec. Using en-us for US English is inserted by default in the BB Meta Pad.

Optional Metadata Help

Keywords: These are labels that apply to your eBook, similar to the way bloggers tag their posts. A good example for a work of fiction such as a hard-boiled novel would be “Hard Boiled, Crime, Noir, Detective, Mystery, Thriller, Femme Fatale”. You can separate these with commas in the Control Panel, and the BB Meta Pad will break each keyword up into dc:subject markup for the XML. You can list as many as you like, but seven is recommended. Note: When you upload your eBook for sale, you have to re-enter all the keywords.

Description: This is typically the backjacket description or blurb of the eBook. You can enter in multiple paragraphs in the Control Panel, but the Meta Pad will condense the entry into one paragraph, because the description can only have one XML entry in the dc:description element. Do not enter HTML here; this will cause your EPUB to fail validation. However, UTF-8 characters are okay, just make sure you indicate that your OPF file has UTF-8 in your text editor or you will get strange errors during EpubCheck. Note: When you upload your eBook for sale, you have to re-enter the eBook’s description.

Rights/Copyright Information: This is a standard statement on the rights of the eBook such as “All Rights Reserved” or “Public Domain”. It is not widely recognized by eReading devices, but it does no harm to add this metadata. It is placed in the dc:rights XML element.

Type: This is from the Dublin Core metadata specification for dc:type. For eBooks, this will always be “Text”. Please note that eReading devices rarely use this metadata.

Source: This is more Dublin Core metadata that defines the dc:source XML element as “A Reference to a resource from which the present resource is derived.” If your eBook is part of a series or a portion of another larger periodical, you may consider adding this metadata by including an ISBN or UUID for the relevant publication. If your eBook is a compilation of a blog post, you can consider placing the URL to your blog. Please note that eReading devices rarely make use of this metadata.

Relation: This is some more Dublin Core metadata. The dc:relation XML element is defined as “A reference to a related resource.” If your eBook is a spin-off from another publication, you may consider placing a URL, ISBN, or UUID. However, eReading devices rarely make use of this metadata.

Coverage: This defines the coverage of your copyright, which is typically “Worldwide” or “Territorial”. If you eBook is public domain, you can simply say “Public Domain.” dc:coverage is the applicable XML markup and you don’t typically see this in metadata. It is part of the Dublin Core specification and included here for completeness.

Extra Metadata Help

The extra metadata section allows you to add people who contributed to the publication, such as an illustrator, editor, and even the rubricator (whatever the hell that is). XML markup with the tag dc:contributor is added, along with the attribute opf:role plus a three-letter code indicating the title of the contributor. The three-letter codes come from the Marc Code List for Relators as dictated by the IDPF standard, and there are details of each contributor’s description at the United States Library of Congress.

To fill out a contributor on the BB Meta Pad, simply select the type of contributor, enter the name, and the file-as. If the name and file-as are the same, you can leave the file-as blank. Like the dc:creator element, you can add an attribute with the file-as attribute if you want to file the last name first. None of this metadata is required, and you can add as many contributors as you feel necessary.

Note: The extra metadata should not include the primary author, which must be listed under the dc:creator element.