openbook.js

{
  // If a book has a subtitle, just use a colon:
  //
  //   "title": "The Elements of Style: Illustrated"
  //
  // The full normalized form is a hash of strings: {
  //   "main": "The Elements of Style",
  //   "subtitle": "Illustrated"
  // }
  //
  // Where the hash keys must include "main", and may include:
  // "subtitle", "short", "collection", "edition", "expanded". The order
  // of the keys in the hash represents the title's display sequence.
  //
  // (If the title has a colon that doesn't represent the separator
  // between the title and subtitle (weird!), use the hash form --
  // the title won't be split up.)
  //
  // But in most cases, a string suffices:
  "title": "The Elements of Style",

  // Creator can be a string, an array of strings, a
  // hash of { name, bio, dates, role }, or an array of such hashes.
  // Normalized to an array of hashes.
  "creator": "William Strunk Jr.",

  // Note: "contributor" is exactly the same as "creator", but is for
  // people whose contribution was secondary to the creation of the work.
  //
  // "contributor": "Roger Angell",

  // Description can also be a hash: { short, full }. If a string,
  // it will be normalized to a hash, where 'full' has
  // the value of the supplied string and 'short' is the first
  // sentence thereof (unless full is only once sentence).
  "description": "A classic of English grammar.",

  // Inferred: images/cover.jpg if it exists and cover is not set.
  // "cover" can be a simple string like "images/cover.jpg"
  //
  // It can also be a hash like the one below. In its full
  // normalized form, it is a hash of such arrays, with the keys
  // "front", "back", "spine", "front-flap", "back-flap", "stepback".
  //
  "cover": {
    "path": "images/cover.jpg",
    "media-type": "image/jpeg"
  },

  // Optional identity and modification timestamp (version, effectively).
  "unique-identifier": "urn:uuid:016cc360-2cfd-11e3-bae3-0002a5d5c51b",
  // Can be a short date or a full Zulu timestamp:
  "modified": "2013-10-31",
  // A version number has no intrinsic meaning. Source: ibooks:version
  "version": "1.0.0",

  // Optional publication URL for this book
  "url": "https://www.overdrive.com/media/222498/the-elements-of-style",

  // Publication identifiers like ISBNs are simply top-level properties.
  "eisbn": "978....",
  "pisbn": "978....",

  "publisher": "OverDrive, Inc.",
  "imprint": "Public Domain Books",
  // Subject can be a string or an array of strings. Normalized: array.
  "subject": ["english", "grammar"],
  // Language can be a string or an array of strings. Normalized: array.
  "language": "en",

  // Date may be a string (representing publication date), or hash with
  // three possible keys: creation, publication, modification:
  "date": "2014-05-24",

  // What kind of book is this? Ebook? Audiobook? Something else?
  "rendition:format": "ebook",
  
  // Reflowable/pre-paginated display of documents. Global settings: each
  // of these can be overridden by individual documents.
  "rendition-layout": "reflowable",
  "rendition-orientation": "auto",
  "rendition-spread": "auto",
  // If specified, this overrides the "viewport" meta declaration inside
  // the document. (The "initial containing block" in EPUB3 parlance.)
  "rendition-viewport": "600x600",
  // Shows or hides the binding between a two-page spread in ereaders
  // that use this. If not defined, default is ereader-defined.
  // Source: ibooks:binding.
  "rendition-visible-binding": false,

  // Internationalization features
  // Can be ltr/rtl/default. Source: EPUB3 page-progression-direction
  "i18n-page-progression-direction": "default",
  // Can be vertical/horizontal/default. Source: ibooks:scroll-axis
  "i18n-scroll-axis": "default",

  // Optional. May be INFERRED if not specified.
  // The ambient soundtrack can be set at the book level and at
  // the document level. Source: ibooks:soundtrack
  //
  // Inferencing: if *no* documents have a soundtrack property, it will
  // look for a .mp3 at exactly this file path: "audio/soundtrack.mp3".
  "audio-soundtrack": "audio/soundtrack.mp3",

  // Total duration of audio overlays for this book in seconds. Inferred
  // from the SMIL files if not given. Don't use SMIL clock values: just
  // use seconds.
  "audio-overlay-duration": 630.5,

  // Optional. This is a book-level default -- will be applied to all
  // audio overlay resources during normalization and removed at the
  // book-level.
  "audio-overlay-narrator": "Nicholas James Bridgewater",

  // Optional. You should just leave these two at their defaults, really.
  // A ereader might add this class to the element that is being spoken.
  "audio-overlay-active-class": "-epub-media-overlay-active",
  // Likewise, an ereader might add this class to the <html> of the document
  // that is being spoken.
  "audio-overlay-playback-active-class": "epub-media-overlay-active-playing",

  // The required "spine" list.
  "spine": [
    {
      // Required. This is the location of the file relative to pub-root.
      "path": "000-cover.html",

      // Optional. This is the default value.
      "media-type": "text/html",

      // Optional. Default is true.
      "linear": false,

      // Very optional! Openbook can automatically generate this. This just
      // holds the id when converting from EPUB, because some ereaders use the
      // spine item id to convert annotations between book versions.
      "id": "000-cover",

      // Optional. May be INFERRED if not specified.
      // Inferencing: looks for a .smil at the related file path - in this
      // case, at audio/overlays/cover.smil.
      "audio-overlay": "audio/overlays/cover.smil",

      // If a soundtrack is specified for any documents, it is used for all
      // subsequent documents until another soundtrack is specified.
      // You can stop a soundtrack with:
      //    "audio-soundtrack": ""
      //  or
      //    "audio-soundtrack": null
      // (The empty string form will normalize to null.)
      "audio-soundtrack": "audio/soundtrack.ogg",

      // Optional. These values are examples, they are non-default.
      // Force this single document to be fixed-layout:
      "rendition-layout": "pre-paginated",
      // Ensure that it's on the right side of a spread (if there's a spread):
      "rendition-position": "right",
      // This document's viewport is twice as wide as other documents in
      // this book.
      "rendition-viewport": "1200x600"

      // Optional. May be INFERRED if not specified.
      // You can specify a fallback chain like this. All the same options
      // for the document can be set here. Nothing is inherited from higher
      // in the chain.
      //
      // Inferencing: if a file exists at fallbacks/cover-1.*, we will use it,
      // and we'll keep incrementing by 1 until we do not find a file.
      "fallback": {
        "path": "fallbacks/000-cover-1.xhtml",
        "fallback": "fallbacks/000-cover-2.htm"
      }
    },

    // Simpler alternative: a document can be just a string - this is the url.
    //
    // Everything else is default or inferred from the file-system.
    "001-colophon.html",
    "002-intro.html",
    "003-illus.html",
    "004-part01.html",
    "005-part02.html",
    "006-part03.html",
    "007-part04.html",
    "008-part05.html",
    "009-part06.html",
    "010-part07.html",
    "011-part08.html",
    "012-illus.html",
    // Here's a quick demonstration of how to turn off the soundtrack.
    // All subsequent documents will not have a soundtrack.
    {
      "path": "013-part09.html",
      "audio-soundtrack": null
    },
    "014-part10.html",
    "015-part11.html",
    "016-part12.html",
    "017-part13.html",
    "018-part14.html",
    "019-part15.html",
    "020-part16.html",
    "021-partl7.html",
    "022-partl8.html",
    "023-illus.html",
    "024-part19.html",
    "025-illus.html",
    "026-part20.html",
    "027-illus.html",
    "028-part21.html",
    "029-illus.html"
  ],


  // Optional "nav" object. This allows for alternative tables of
  // contents and richer navigation options, including the possibility
  // of sub-chapters within documents.
  //
  "nav": {
    // May be INFERRED if not specified.
    //
    // Inferencing: if not found, may look at the <title> tag inside
    // the document HTML. Blank titles will be omitted, obviously.
    // (Advanced note: it will strip " - {publication-title}" from the
    // end of the <title> tag if found.)
    "toc": [
      {
        "title": "THE ELEMENTS OF STYLE",
        "path": "000-cover.html"
      },
      {
        "title": "I. Introductory",
        "path": "002-intro.html"
      },
      {
        "title": "II. Elementary Rules of Usage",
        "path": "004-part01.html",
        "contents": [
          {
            "title": "1. Form the possessive singular of nouns with 's.",
            "path": "004-part01.html"
          },
          {
            "title": "2. In a series of three or more terms with a single conjunction, use a comma after each term except the last.",
            "path": "005-part02.html"
          },
          {
            "title": "3. Enclose parenthetic expressions between commas.",
            "path": "006-part03.html"
          },
          {
            "title": "4. Place a comma before and or but introducing an independent clause.",
            "path": "007-part04.html"
          },
          {
            "title": "5. Do not join independent clauses by a comma.",
            "path": "008-part05.html"
          },
          {
            "title": "6. Do not break sentences in two.",
            "path": "009-part06.html"
          },
          {
            "title": "7. A participial phrase at the beginning of a sentence must refer to the grammatical subject.",
            "path": "010-part07.html"
          },
          {
            "title": "8. Divide words at line-ends, in accordance with their formation and pronunciation.",
            "path": "011-part08.html"
          }
        ]
      },
      {
        "title": "III. Elementary Principles of Composition",
        "path": "013-part09.html",
        "contents": [
          {
            "title": "9. Make the paragraph the unit of composition: one paragraph to each topic.",
            "path": "013-part09.html"
          },
          {
            "title": "10. As a rule, begin each paragraph with a topic sentence; end it in conformity with the beginning.",
            "path": "014-part10.html"
          },
          {
            "title": "11. Use the active voice.",
            "path": "015-part11.html"
          },
          {
            "title": "12. Put statements in positive form.",
            "path": "016-part12.html"
          },
          {
            "title": "13. Omit needless words.",
            "path": "017-part13.html"
          },
          {
            "title": "14. Avoid a succession of loose sentences.",
            "path": "018-part14.html"
          },
          {
            "title": "15. Express co-ordinate ideas in similar form.",
            "path": "019-part15.html"
          },
          {
            "title": "16. Keep related words together.",
            "path": "020-part16.html"
          },
          {
            "title": "17. In summaries, keep to one tense.",
            "path": "021-part17.html"
          },
          {
            "title": "18. Place the emphatic words of a sentence at the end.",
            "path": "022-part18.html"
          }
        ]
      },
      {
        "title": "IV. A Few Matters of Form",
        "path": "023-part19.html"
      },
      {
        "title": "V. Words and Expressions Commonly Misused",
        "path": "024-part20.html"
      },
      {
        "title": "VI. Words Commonly Misspelled",
        "path": "025-part21.html"
      }
    ],

    // Optional, and not used if not supplied.
    "loi": [
      {
        "title": "The Cover, featuring Mr Pickwick from The Pickwick Papers",
        "path": "000-cover.html",
      },
      {
        "title": "Mr Micawber, from David Copperfield",
        "path": "003-illus.html"
      },
      {
        "title": "Mr Bumble, from Oliver Twist",
        "path": "012-illus.html"
      },
      {
        "title": "Sarah Gamp, from Martin Chuzzlewit",
        "path": "023-illus.html"
      },
      {
        "title": "Mr Jingle, from The Pickwick Papers",
        "path": "025-illus.html"
      },
      {
        "title": "Dick Swiveller, from The Old Curiosity Shop",
        "path": "027-illus.html"
      },
      {
        "title": "Toots, from Dombey & Son",
        "path": "029-illus.html"
      }
    ],

    // Optional, and not used if not supplied.
    "landmarks": [
      {
        "title": "The Cover",
        "path": "000-cover.html",
        "type": "cover"
      },
      {
        "title": "Title Page",
        "path": "001-colophon.html",
        "type": "titlepage"
      },
      {
        "title": "I. Introductory",
        "path": "003-intro.html",
        "type": "introduction bodymatter"
      }
    ],

    // Again, optional.
    "page-list": []
  },


  // Optional "resources" object. This lists one or more files that are not
  // in the contents object, in order to provide more detailed information
  // about them (like the media type or the fallback).
  //
  // NOTE: to keep the inferred manifest's size down, this section is never
  // inferred, even if not specified. It doesn't really add much to just list
  // all the resources in all sub-directories.
  "resources": [
    {
      "path": "audio/soundtrack.ogg",
      "media-type": "audio/ogg",
      "fallback": "audio/soundtrack.mp3",

      // Very optional. See notes at 'spine'.
      "id": "audio-soundtrack-ogg"
    },
    {
      "path": "audio/overlays/cover.smil",
      "media-type": "application/smil+xml",
      // Optional fields for audio overlay SMIL files.
      "audio-overlay-duration": 16.75,
      "audio-overlay-narrator": "Steve Potash"
    },
    {
      "path": "bindings/xlviewer.html",
      // This could be a string or an array. (Per the EPUB spec, which says
      // "If you find an <object> tag with an unknown media-type, look for
      // a resource with this media-type as a binding, then open this resource
      // in an iframe to render it.")
      "bindings": "application/vnd.ms-excel"
    }
  ],

  // The 'generator' is typically the piece of software that did
  // the inferencing or normalizing of the original manifest.
  // You don't need to update this for small additions; only for inferencing.
  "generator": "Bookbinder 0.5.1",

  // A generic metadata construct. You can store specialized metadata here
  // if you want to, but in normal cases you probably wouldn't.
  //
  // You can nest properties arbitrarily deep in this structure.
  //
  // "metadata": {
  //   "some-property": [{
  //     "@": "value-of-some-property",
  //     "some-property-property": {
  //       "@": "value-of-some-property-property",
  //       "some-property-property-property": {
  //         "@": "value-of-etc"
  //       }
  //     }
  //   }],
  //   "other-property": [
  //     { "@": "other-property-first-value" },
  //     { "@": "other-property-second-value" }
  //   ]
  // }

}

TOP-LEVEL PROPERTIES

"title":

SHORT ANSWER:
- Just a title: "A Tale of Two Cities"
- Title with subtitles: "Math: An Introduction"

RAW: a string or a hash of strings

COOKED: a hash of strings with mandatory key: "main"  and 
optional keys: subtitle, collection, short, edition, expanded      
  NORMALIZATION:
  Given a string, will normalize "Tale of Two Cities, A" to 
  { "main": "A Tale of Two Cities" }, and "Math: An Introduction" to 
  { "main": "Math", "subtitle": "An Introduction" }

  Will not normalize a hash.

"creator":

SHORT ANSWER:
- Single author: "William Strunk, Jr."
- Multiple authors: ["William Strunk, Jr.", "E.B. White"]

RAW: a string, an array of strings, a hash, an array of hashes. If an
array, must be in order from "most important creator" to "least".

COOKED: an array of hashes — [{
  "name": ...  [ALWAYS]
  "role": ...  [ALWAYS]
  "bio": ...  [SOMETIMES]
  "dates": ...  [SOMETIMES]
}]

  NORMALIZATION: "role" will be converted to lowercase. If given a 
  string or an array of strings, or if "role" is not provided in the
  hash, "role" will be set to "author".

"description":

SHORT ANSWER: "<p>This is the blurb.</p>"

RAW: *optional, but strongly recommended* 

COOKED: a hash — {
  "full": "..." [ALWAYS],
  "short": "..." [SOMETIMES]
}

  NORMALIZATION: when the raw form is a string, that will the "full"
  value. The "short" value will be the first sentence of the full value,
  unless the full value is only one sentence.

"cover":

SHORT ANSWER: "images/cover.jpg"

RAW: can be a string like "images/cover.jpg" or a hash like 
{ "path": "images/cover.jpg", "media-type": "image/jpeg" } or a 
hash of strings like 
{ "front": "images/cover-front.jpg", "back": "images/cover-back.jpg" },
or a hash of hashes like the cooked form


COOKED: a hash of hashes — {
  "front": {   [ALWAYS]
    "path": "images/cover-front.jpg",   [ALWAYS]
    "media-type": "image/jpeg"   [ALWAYS]
  },
  "back": {    [SOMETIMES]
    "path": "images/cover-back.png",
    "media-type": "image/png"
  }
}

Valid cover labels are "front" (mandatory if any labels) and "back",
"spine", "front-flap", "back-flap", "stepback" (all optional).

  NORMALIZATION: "media-type" will automatically be generated based
  on file extension if supplied a string, or a hash without a 
  'media-type' property

  INFERENCING: If there is no 'cover' property and there is a file
  at "images/cover.jpg", the property will be set to {
    "path": "images/cover.jpg",
    "media-type": "image/jpeg"
  }. If there's no such file, but there is an images/cover.png file,
  the equivalent hash will be used.

"unique-identifier":

SHORT ANSWER: "urn:uuid:016cc360-2cfd-11e3-bae3-0002a5d5c51b"

RAW: *optional* this is a string that uniquely identifies your ebook. Often
a urn:uuid — if you need one, you can generate one 
here: http://www.famkruithof.net/uuid/uuidgen

COOKED: optional. It remains as just a string. When converting to or from
other formats, it MAY be supplied as the MD5 digest of the source file.

REASON FOR INCLUSION: EPUB3 package identifiers — http://www.idpf.org/epub/30/spec/epub30-publications.html#sec-opf-metadata-identifiers-pid

"modified":

SHORT ANSWER: "2013-10-31"

RAW: *optional* the date this package was last modified. You can use a simple date
like this "2013-10-31" or the full Zulu-time catastrophe: "2013-10-31T12:00:00Z"

COOKED: if supplied, always converted to exactly this format: "2013-10-31T12:00:00Z"

REASON FOR INCLUSION: EPUB3 package identifiers, same as "unique-identifier".

"version":

SHORT ANSWER: skip it

RAW: *very optional*. If supplied, should be something like this: "1.0.1". Openbook
recommends using semantic versioning if your book has a version number. Pour yourself
a cup of tea and visit http://semver.org/ for (much) more detail.

COOKED: unchanged if supplied.

REASON FOR INCLUSION: Apple's iBooks has an ibooks:version property. Useful for UI
display, eg: "The latest version of your book is 1.0.1 — update now?"

"url":

SHORT ANSWER: "http://www.hup.harvard.edu/catalog.php?isbn=9780674430006"

RAW: *optional*. May be a string, in which case it is the "canonical" URL, which 
is the for the publisher's webpage for this book. Or it may be a hash of URLs: {
  "publication": "...",
  "purchase": "...",
  "onix": "...",
  "marc": "...
}

COOKED: Will be a hash. 'http://' will be prepended to each URL if no protocol.
Each URL will be validated, discarded if not a URL. 

"eisbn":

SHORT ANSWER: "9780674430006"

RAW: *optional* An ISBN, preferably in ISBN-13 format.

COOKED: normalized to ISBN-13 with no spaces or dashes.

"pisbn":

SHORT ANSWER: "978067443000X"

RAW: *optional* If this ebook has a print book counterpart, you can supply the
isbn for that print book. Prefer ISBN-13.

COOKED: normalized to ISBN-13 with no spaces or dashes.

"publisher":

SHORT ANSWER: "Penguin Books"

RAW: *optional*. The name of the publisher.

COOKED: unchanged if supplied.

"imprint":

SHORT ANSWER: "Puffin Books"

RAW: *optional* The name of the imprint.

COOKED: unchanged if supplied

"series":

[TODO]

"subject":

SHORT ANSWER: ["fiction", "romance", "regency"]

RAW: *optional* A string — "fiction" — or an array — ["fiction", "romance"]

COOKED: normalized to an array of strings, so "fiction" would become ["fiction"]

"language"

[TODO]

"rendition-layout":

EXPLANATION: a "reflowable" document has multiple pages, and the ebook reader will show
as many words as will fit on each page. A "pre-paginated" document is a single page
with a fixed width and height, and the ebook reader will scale it down to fit the screen
if necessary.

SHORT ANSWER:
- reflowable books: "reflowable" (or omit, because this is the default)
- fixed layout books: "pre-paginated"

RAW: either "reflowable" or "pre-paginated", following the EPUB3 convention.

COOKED: Removed! After this value is applied to each document in the spine that
does not have its own explicit 'rendition-layout' value, this property is removed
from the top-level. (This makes this property a DOCUMENT-DEFAULT-VALUE.)

"rendition-orientation":

EXPLANATION: if a document has an intended orientation of "landscape" or "portrait",
the ereader may choose to make the user reorient their device to read it. Obviously
that only works for mobile devices where screen reorientation is feasible.

SHORT ANSWER: "auto"

RAW: can be "landscape" or "portrait" or "auto", but we generally recommend that you
leave this at auto and let the reading system optimize the experience for the user.

COOKED: This is a DOCUMENT-DEFAULT-VALUE. After applying to each document that 
doesn't have its own value, it's removed from the top level.

"rendition-spread":

EXPLANATION: a document can say that it may appear in a two-page spread only for
a certain screen orientation. If the value is "landscape", it means "only show two
pages when this document is on screen if in a landscape orientation". If the ereader
doesn't support two-page spreads it's ignored of course.

SHORT ANSWER: "auto"

RAW: can be "auto" (leaving it up to the ereader), "landscape" (the most common
choice after "auto"), "portrait" (which usually looks pretty weird, with narrow
columns of text), or "both" (meaning always spread in landscape AND portrait).

COOKED: This is a DOCUMENT-DEFAULT-VALUE. Applied to all documents that don't
have their own rendition-spread value, then removed from the top level.

"rendition-viewport":

EXPLANATION: a pre-paginated document has a fixed width and height. All the content
of the page fits within this space. The ereader will scale down this space to fit
the available screen size. (This is the equivalent of the "initial containing block"
stuff in the EPUB3 Fixed Layout spec — but here you only have to write it once.)

SHORT ANSWER: "800x600"

RAW: express it as a string in the form "WIDTHxHEIGHT", where WIDTH and HEIGHT are 
integers (representing pixels).

COOKED: This is a DOCUMENT-DEFAULT-VALUE. Applied to all documents that don't have
their own rendition-viewport value, then removed from the top level.

"audio-soundtrack":

EXPLANATION: You can add a short looping audio track to documents in your book. In
supporting ereaders, if the user has chosen to play the soundtrack, this file will
start playing when the user turns to this document. (If this file was the soundtrack
for the last document they were on, it will keep playing.)

SHORT ANSWER: leave this blank and put an mp3 at "audio/soundtrack.mp3"

RAW: *optional*. Can be a string, in which case it is a path to a sound file in 
the package, or it can be a hash in the form: { 
  "path": "audio/soundtrack.ogg", 
  "media": "audio/ogg" 
}

COOKED: This is a DOCUMENT-DEFAULT-VALUE. Applied to the first set of documents that
don't have their own audio-soundtrack value, then removed from the top level. 

Note that documents without 'audio-soundtrack' properties inherit the value from the
preceding document, so this value will only apply in the spine up to the first document
that has a value for 'audio-soundtrack' -- even if that value is "" or null. Basically,
it's best to only use the top-level property if every document in the book will have
this soundtrack. Otherwise, use the document-level property.

"audio-tts-permitted":

[TODO]

"i18n-page-progression-direction":

[TODO]

"i18n-scroll-axis":

[TODO]

"spine":

[TODO]

"nav":

[TODO]

"resources":

[TODO]

"generator":

SHORT ANSWER: you must leave this blank

RAW: unless the Openbook is cooked, generator should be blank.

COOKED: this should be the "name and version" string for the software that
performed the "cooking". Eg: "Bookbinder 0.5.1"

"creator":

SHORT ANSWER:
- Single author: "William Strunk, Jr."
- Multiple authors: ["William Strunk, Jr.", "E.B. White"]

RAW: a string, an array of strings, a hash, an array of hashes. If an
array, must be in order from "most important creator" to "least".

COOKED: an array of hashes — [{
  "name": ...  [ALWAYS]
  "role": ...  [ALWAYS]
  "bio": ...  [SOMETIMES]
  "dates": ...  [SOMETIMES]
}]

    NORMALIZATION:
    "role" will be converted to lowercase. If given a string or an
    array of strings, or if "role" is not provided in the hash,
    "role" will be set to "author"

"description":

SHORT ANSWER: "<p>This is the blurb.</p>"

RAW: *optional, but strongly recommended* 

COOKED: a hash — {
  "full": "..." [ALWAYS],
  "short": "..." [SOMETIMES]
}

    NORMALIZATION: when the raw form is a string, that will the "full"
    value. The "short" value will be the first sentence of the full value,
    unless the full value is only one sentence.

"cover":

SHORT ANSWER: "images/cover.jpg"

RAW: can be a string like "images/cover.jpg" or a hash like 
{ "path": "images/cover.jpg", "media-type": "image/jpeg" } or a 
hash of strings like 
{ "front": "images/cover-front.jpg", "back": "images/cover-back.jpg" },
or a hash of hashes like the cooked form


COOKED: a hash of hashes — {
  "front": {   [ALWAYS]
    "path": "images/cover-front.jpg",   [ALWAYS]
    "media-type": "image/jpeg"   [ALWAYS]
  },
  "back": {    [SOMETIMES]
    "path": "images/cover-back.png",
    "media-type": "image/png"
  }
}

Valid cover labels are "front" (required if any labels) and "back", "spine", "front-flap", "back-flap" (all optional).

    NORMALIZATION: "media-type" will automatically be generated based
    on file extension if supplied a string, or a hash without a 
    'media-type' property

    INFERENCING: If there is no 'cover' property and there is a file
    at "images/cover.jpg", the property will be set to {
      "path": "images/cover.jpg",
      "media-type": "image/jpeg"
    }. If there's no such file, but there is an images/cover.png file,
    the equivalent hash will be used.

"unique-identifier":

SHORT ANSWER: "urn:uuid:016cc360-2cfd-11e3-bae3-0002a5d5c51b"

RAW: *optional* this is a string that uniquely identifies your ebook. Often
a urn:uuid — if you need one, you can generate one 
here: http://www.famkruithof.net/uuid/uuidgen

COOKED: optional. It remains as just a string. When converting to or from
other formats, it MAY be supplied as the MD5 digest of the source file.

REASON FOR INCLUSION: EPUB3 package identifiers — http://www.idpf.org/epub/30/spec/epub30-publications.html#sec-opf-metadata-identifiers-pid

"modified":

SHORT ANSWER: "2013-10-31"

RAW: *optional* the date this package was last modified. You can use a simple date
like this "2013-10-31" or the full Zulu-time catastrophe: "2013-10-31T12:00:00Z"

COOKED: if supplied, always converted to exactly this format: "2013-10-31T12:00:00Z"

REASON FOR INCLUSION: EPUB3 package identifiers, same as "unique-identifier".

"version":

SHORT ANSWER: skip it

RAW: *very optional*. If supplied, should be something like this: "1.0.1". Openbook
recommends using semantic versioning if your book has a version number. Pour yourself
a cup of tea and visit http://semver.org/ for (much) more detail.

COOKED: unchanged if supplied.

REASON FOR INCLUSION: Apple's iBooks has an ibooks:version property. Useful for UI
display, eg: "The latest version of your book is 1.0.1 — update now?"

"url":

SHORT ANSWER: "http://www.hup.harvard.edu/catalog.php?isbn=9780674430006"

RAW: *optional*. The URL for the publisher's webpage for this book.

COOKED: 'http://' will be prepended if no protocol. URL will be validated, discarded
if not a URL.

"eisbn":

SHORT ANSWER: "9780674430006"

RAW: *optional* An ISBN, preferably in ISBN-13 format.

COOKED: normalized to ISBN-13 with no spaces or dashes.

"pisbn":

SHORT ANSWER: "978067443000X"

RAW: *optional* If this ebook has a print book counterpart, you can supply the
isbn for that print book. Prefer ISBN-13.

COOKED: normalized to ISBN-13 with no spaces or dashes.

"publisher":

SHORT ANSWER: "Penguin Books"

RAW: *optional*. The name of the publisher.

COOKED: unchanged if supplied.

"imprint":

SHORT ANSWER: "Puffin Books"

RAW: *optional* The name of the imprint.

COOKED: unchanged if supplied

"series":

[TODO]

"subject":

SHORT ANSWER: ["fiction", "romance", "regency"]

RAW: *optional* A string — "fiction" — or an array — ["fiction", "romance"]

COOKED: normalized to an array of strings, so "fiction" would become ["fiction"]

"language"

[TODO]

"rendition-layout":

EXPLANATION: a "reflowable" document has multiple pages, and the ebook reader will show
as many words as will fit on each page. A "pre-paginated" document is a single page
with a fixed width and height, and the ebook reader will scale it down to fit the screen
if necessary.

SHORT ANSWER:
- reflowable books: "reflowable" (or omit, because this is the default)
- fixed layout books: "pre-paginated"

RAW: either "reflowable" or "pre-paginated", following the EPUB3 convention.

COOKED: Removed! After this value is applied to each document in the spine that
does not have its own explicit 'rendition-layout' value, this property is removed
from the top-level. (This makes this property a DOCUMENT-DEFAULT-VALUE.)

"rendition-orientation":

EXPLANATION: if a document has an intended orientation of "landscape" or "portrait",
the ereader may choose to make the user reorient their device to read it. Obviously
that only works for mobile devices where screen reorientation is feasible.

SHORT ANSWER: "auto"

RAW: can be "landscape" or "portrait" or "auto", but we generally recommend that you
leave this at auto and let the reading system optimize the experience for the user.

COOKED: This is a DOCUMENT-DEFAULT-VALUE. After applying to each document that 
doesn't have its own value, it's removed from the top level.

"rendition-spread":

EXPLANATION: a document can say that it may appear in a two-page spread only for
a certain screen orientation. If the value is "landscape", it means "only show two
pages when this document is on screen if in a landscape orientation". If the ereader
doesn't support two-page spreads it's ignored of course.

SHORT ANSWER: "auto"

RAW: can be "auto" (leaving it up to the ereader), "landscape" (the most common
choice after "auto"), "portrait" (which usually looks pretty weird, with narrow
columns of text), or "both" (meaning always spread in landscape AND portrait).

COOKED: This is a DOCUMENT-DEFAULT-VALUE. Applied to all documents that don't
have their own rendition-spread value, then removed from the top level.

"rendition-viewport":

EXPLANATION: a pre-paginated document has a fixed width and height. All the content
of the page fits within this space. The ereader will scale down this space to fit
the available screen size. (This is the equivalent of the "initial containing block"
stuff in the EPUB3 Fixed Layout spec — but here you only have to write it once.)

SHORT ANSWER: "800x600"

RAW: express it as a string in the form "WIDTHxHEIGHT", where WIDTH and HEIGHT are 
integers (representing pixels).

COOKED: This is a DOCUMENT-DEFAULT-VALUE. Applied to all documents that don't have
their own rendition-viewport value, then removed from the top level.

"audio-soundtrack":

EXPLANATION: You can add a short looping audio track to documents in your book. In
supporting ereaders, if the user has chosen to play the soundtrack, this file will
start playing when the user turns to this document. (If this file was the soundtrack
for the last document they were on, it will keep playing.)

SHORT ANSWER: leave this blank and put an mp3 at "audio/soundtrack.mp3"

RAW: *optional*. Can be a string, in which case it is a path to a sound file in 
the package, or it can be a hash in the form: { 
  "path": "audio/soundtrack.ogg", 
  "media": "audio/ogg" 
}

COOKED: This is a DOCUMENT-DEFAULT-VALUE. Applied to the first set of documents that
don't have their own audio-soundtrack value, then removed from the top level. 

Note that documents without 'audio-soundtrack' properties inherit the value from the
preceding document, so this value will only apply in the spine up to the first document
that has a value for 'audio-soundtrack' -- even if that value is "" or null. Basically,
it's best to only use the top-level property if every document in the book will have
this soundtrack. Otherwise, use the document-level property.

"i18n-page-progression-direction":

[TODO]

"i18n-scroll-axis":

[TODO]

"spine":

[TODO]

"nav":

[TODO]

"resources":

[TODO]

"generator":

SHORT ANSWER: leave this blank

RAW: unless the Openbook is cooked, generator should be blank.

COOKED: this should be the "name and version" string for the software that
performed the "cooking". Eg: "Bookbinder 0.5.1"