Skip to content

EPUB 3.1 F2F Meeting Detailed Agenda

Jump to bottom
Hadrien Gardeur edited this page Apr 5, 2016 · 1 revision

The big picture

Work on BFF started by simply "porting" the OPF to JSON. But after the initial call and discussions, Hadrien proposed to adopt a unified model for the OPF and its equivalent in BFF: everything is a collection.

In EPUB 3.0.1, a collection has a role and it contains:

  • metadata
  • links

Some elements in our current OPF (3.1) are essentially links: item, itemref, link.

Structural elements of the OPF (spine, manifest and even renditions) can therefore be expressed as collections.

With this simple model, BFF only needs to have two well-known keys: metadata and links. Everything else is a collection and can be parsed and handled as such, the key becomes the role of the collection (rendition, manifest or preview for example).

In addition to this model, two proposals were made to further simplify things:

  • Matt proposed to replace the spine with rendition, where the links of the rendition become the new spine
  • Dave proposed to avoid duplicating elements between links in rendition and its manifest

While Dave also attempted to craft an alternative to the JSON manifest using HTML, he encountered multiple problems and limitations which is why the current proposal is based on the JSON work done so far (https://github.com/dauwhe/epub31-bff).

Identify, Locate and Link

The first topic of discussion for the F2F is focused on how we identify, locate and link to this new JSON manifest.

Media Type and File Extension

The BFF manifest is based on JSON-LD and there are essentially two things at stake in selecting a media type for it:

  • can an EPUB client (browser, native app, web app) identify the JSON-LD as an EPUB BFF?
  • can a search crawler or a JSON-LD aware client identify it as JSON-LD and properly extract metadata from it?

On mobile devices, there are very limited ways to associate a given file or URI to an app:

  • file extension (tied potentially to multiple apps on iOS and Android)
  • media type (tied potentially to multiple apps on iOS and Android)
  • URI scheme (limited to one app on iOS, multiple apps on Android)

For that environment, it is strongly preferred to have both a unique media type and file extension to identify our new manifest.

The current proposal uses application/epub+json but this could also be something like application/epub+ld+json.

On the other hand, with its own media type, crawlers won't be aware that we're actually using JSON-LD.

The Web App Manifest specification defines application/manifest+json for its own manifest format.

Question 1: Should we define our own media type for EPUB BFF?

Question 2: Do we also need a file extension for EPUB BFF?

Locate

While an OPF can link to an EPUB BFF in 3.0.1 using <link href="manifest.json" media-type="application/epub+json" rel="alternate" />, we also want to consider the case of a potential future serialization of EPUB where BFF could become the primary manifest.

In this scenario, a well-known location for the new manifest would be a requirement.

Question 3: Do we need a well-known location for the new manifest in our current container?

Link

We've already covered in the previous section how a "classic" OPF can link to an EPUB BFF, but the most important part is how a client can actually discover that a document is included in a publication.

This is done through the use of either the <link>element in HTML or the Link: header in HTTP.

In both case, the BFF can be identified by its media type (if we adopt a unique one) and a rel value:

<link href="manifest.pwp" rel="manifest" type="application/epub+json">

The Web App Manifest specification also relies on rel="manifest".

Transmitting a BFF as a File

For some use cases, we could also transmit a BFF as a file (either included in a "classic" EPUB or on its own).

Since a BFF EPUB is meant to be a "live" publication, where both the BFF and its components can be updated at any time, having a "self" link in every BFF could be very useful:

{
  "links": [
    {"rel": "self", "href": "http://example.org/manifest.epub-bff", "type": "application/epub+json"},
    {"rel": "self", "href": "http://example.org/publication.epub", "type": "application/epub+zip"}
  ]
}

Question 4: Do we need a "self" link in every EPUB BFF?

Embedding vs Standalone

The embedding vs standalone debate has mostly centered around the various pros and cons of both, but recent discussions have made this debate less important:

  • crawlers (at least Google) can parse JSON-LD injected using JS in a HTML document now
  • we could also allow embedding but require a standalone manifest, and use application/ld+json when embedded in a <script> element vs application/epub+json the rest of the time

Question 5: Do we want to adopt a position regarding embedding vs standalone?

Relationship to JSON-LD

More recently, as we started discussing metadata and crawlers more in details, both Dave and Hadrien started working on using JSON-LD for EPUB BFF.

Dave attempts were focused on the on using a @context in JSON-LD to cover everything in BFF while Hadrien mostly focused on the publication's metadata.

Hadrien created a separate Gist to showcase how a JSON-LD context can work for simple or complex metadata: https://gist.github.com/HadrienGardeur/03ab96f5770b0512233a

Question 6: Should the JSON-LD context cover the whole document? ([Issue 21] (https://github.com/dauwhe/epub31-bff/issues/21))

The use of JSON-LD in BFF, means that potentially anyone could redefine elements inline (using a local context) or that multiple external contexts could be defined for the same JSON key which could potentially be confusing.

Hadrien finds that problematic and would like to limit JSON-LD to document-level external contexts listed in an IDPF registry, while Ivan find that approach problematic and believes that it is important to enable the full power of JSON-LD and RDF in BFF.

Question 7: Should we limit our usage of JSON-LD? ([Issue 23] (https://github.com/dauwhe/epub31-bff/issues/23) and [Issue 24] (https://github.com/dauwhe/epub31-bff/issues/23))

Syntax Compactness

Multiple issues opened by Dave are related to the compactness of the proposed syntax.

The current syntax favors having:

  • very few well-known keys (metadata and links) and a limited number of roles
  • consistency (everything is a collection)
  • expressiveness (any collection can have its own metadata)

One "grey area" is the manifest, where there's no clear use case (at least for now) for metadata.

Question 8: Can we simplify manifest to allow link objects instead of links? Can we make this change in a way that's consistent with our current design? ([Issue 14] (https://github.com/dauwhe/epub31-bff/issues/14))

Renditions

A related but separate issue regarding "compactness" is directly related to renditions.

In EPUB 3.0.1, renditions are a bit of a mess:

  • renditions are listed and "selected" through a separate XML file
  • no clear distinction between an OPF and a rendition
  • hard to tell which metadata are specific to a rendition or a publication (multiple dc:title for example)
  • rendition:* elements are mixed with publication metadata

Very early on, Matt proposed to replace the spine collection role with a rendition role instead. There are multiple good points to that approach:

  • single rendition or multiple renditions documents work the same way, you simply repeat the collection
  • single file for everything (selection and definition)
  • clear distinction between rendition specific metadata (title in a rendition can be treated differently) and publication metadata
  • we can isolate rendition:* elements from the publication metadata

With this new model, renditions become a central component of our design:

publication
    metadata
    links
    rendition (one or more)
        metadata
        links
        manifest (zero or one)
        other collections (zero or more)
    other collections (zero or more)

Dave argues that this has the unfortunate side effect of making the syntax less compact and adds more nesting for single rendition documents (the vast majority of EPUB files out there).

Hadrien argued back that having a rendition element is useful for single rendition documents too:

  • to separate publication links ("self" for example) from the new "spine", we need a container anyway (a collection)
  • it's useful to separate rendition:* from the rest of the publication metadata, even for single rendition documents

Question 9: Do we treat rendition as a new core component of the EPUB model? ([Issue 13] (https://github.com/dauwhe/epub31-bff/issues/13))

Publication Identifier

The current proposed context requires a URI as the primary identifier in BFF. That's not currently the case in "classic" OPF but it's possible to convert a number of identifier types to URN (ISBN, UUID, ISSN for example).

Question 10: Can we require a URI in EPUB BFF?

Question 11: Should the identifier of an EPUB BFF remain the same as its "classic" counterpart? ([Issue 12] (https://github.com/dauwhe/epub31-bff/issues/12))

Complications

Clone this wiki locally