eBraille 1.0

This specification defines eBraille, a digital reading format for braille publications.

eBraille uses an EPUB 3-compatible file set based on the Open Web Platform — using technologies such as XHTML and CSS — to encode braille in semantically enhanced markup and allow it to adapt to the different capabilities of braille reading devices. The file set is designed for both packaged distribution to end users and deployment to the web for online and downloadable reading.

The eBraille Working Group is seeking input on all aspects of this document. It is particularly interested in implementation experience both creating eBraille publication and creating reading systems in which to read them.

Introduction

Overview

Unlike braille formats that focus on interchanging embosser-ready braille, eBraille focuses on adapting braille for reading in refreshable braille displays with different line lengths.

In order to maintain close alignment with mainstream publishing formats, and simplify transcription of these works, the eBraille format is built on an EPUB 3-compatible file set — it incorporates XHTML documents, CSS, images, audio, and video. This means that an [=eBraille publication=] shares its technology with the web, making it compatible for reading in standard web browsers.

An [=eBraille publication=] differs from reading a typical web site in that the braille is not transformed on the fly but comes formatted according to the rules of the regional braille code where the publication was produced. Users are not locked into this default display, however. With the display flexibility of CSS, and standardized markup practices, they can apply styles for another region or even modify the display to their own preferences (e.g., by changing the maximum line length).

eBraille publications are also designed to be flexible for deployment. An eBraille publication can be placed on the web, unzipped on a user's local file system, or distributed in EPUB 3-compatible packaging. And as web-compatible file sets, they are adaptable to future changes to publishing formats.

Relationship to EPUB 3

The [=eBraille file set=] is designed to be compatible with EPUB 3 [[epub-33]] and adapt to changes to that standard. Distribution and consumption on mainstream [=EPUB reading systems=], however, is not a primary goal of this format. This specification introduces some additional requirements and features beyond those defined in EPUB 3, and it is not expected that mainstream reading systems will adapt to these modifications. Consequently, an eBraille publication may not render exactly as intended outside of eBraille reading systems.

The primary difference between the eBraille format and EPUB 3 is [=eBraille publications=] do not have to be packaged and distributed in an [=EPUB container=] [[epub-33]] — they can be deployed on the web as an unpackaged set of files. An eBraille publication is packagable in an EPUB container when that is the preferred distribution method, but eBraille uses the file extension .ebrl not .epub.

Compatibility with EPUB 3 also means that eBraille relies on the same underlying technologies [[epub-33]]. Many of these technologies, like [[html]], are referred to as "evergreen" or "living" standards as they are updated often and do not have version numbers. Others, like [[svg]], are referred to without a specific version number so that the latest recommendation is always the recommended one to use.

The practical effect of this approach is predominantly beneficial for [=eBraille creators=]. New features become available for use as soon as they are standardized; it is not required to wait for a new revision of the eBraille standard to allow them. The approach does come with some drawbacks, however. eBraille creators also have to keep themselves apprised of changes to the underlying technologies, and use their best judgement in some cases as to whether a new feature is supported well enough in [=eBraille reading systems=] to begin deploying. In some rare cases, it may also mean that content that was previously valid may no longer be, but breaking changes like this usually only happen when features are unsupported or are found to have serious security or privacy flaws.

Future directions

The first version of the eBraille format is focused on creating a reading experience that is minimally feature complete for the majority of braille publications. It is not expected that this version will handle every unique formatting requirement of every publication type, but future drafts and versions of this specification will focus on making the format more feature complete.

In particular, the working group expects to review the current support decisions for the following features:

scripting — the use of JavaScript in [=eBraille content documents=] is currently prohibited. The working group is seeking further input on the need for dynamic braille before allowing scripting as the ability to script documents increases the security and privacy risks of the format.
CSS extensions — the first version of eBraille uses standard CSS properties to format braille content. There may be a need to extend CSS in the future to handle more complex formatting cases, which will also require defining reading system implementations.
embossing — this version of eBraille is focused on consuming [=eBraille publications=] on electronic reading systems, more specifically refreshable braille displays. It is expected that a revision is needed to better account for the use case of embossing publications on paper.

Terminology

This specification defines the following terms specific to eBraille.

Only the first instance of a term in a section links to its definition.

eBraille content document

eBraille content documents contain all or part of the content of a braille publication. They use a restrictive set of [[html]] tags and define processing requirements through the use of [^global/class^] and [^/role^] attributes.

For more information, refer to .

eBraille creator

An individual, organization, or process that produces an [=eBraille publication=].

eBraille file set

The set of files that comprise an [=eBraille publication=]. The eBraille file set is contained within the [=publication root=].

For more information, refer to .

eBraille publication

A logical document entity consisting of a set of interrelated resources.

An eBraille publication typically represents a single intellectual or artistic work, but this specification does not restrict the nature of the content.

eBraille reading system (or reading system)

A system that processes [=eBraille publications=] for presentation to a user in a manner conformant with this specification.

primary entry page

The default [=eBraille content document=] that users reading an [=eBraille publication=] in a browser are expected to encounter. It is located in the [=publication root=] and specially named to open by default when users browse to a folder containing an eBraille publication.

The primary entry page is an implementation of the [=EPUB navigation document=] [[epub-33]]. It contains the table of contents for the publication.

For more information, refer to

publication root

The root directory is the base of the [=eBraille file set=]. All the resources of an eBraille publication are located at or below this directory.

Authoring shorthands

In package document metadata, reserved prefixes [[epub-33]] are used without declaration.

The following namespace prefixes [[xml-names]] are also sometimes used without an explicit declaration, but the listed declaration is required for their use to be valid:

Prefix	Required declaration	Used with
`dc:`	`xmlns:dc="http://purl.org/dc/elements/1.1/"`	Dublin Core elements [[dcterms]]
`epub:`	`xmlns:epub="http://www.idpf.org/2007/ops"`	EPUB 3-defined attributes [[epub-33]]

eBraille publication conformance

A conforming [=eBraille publication=]:

MUST define at least one rendering of its content as follows:
- It MUST contain a package document that conforms to and meet all publication resource requirements for the package document.
- It MUST contain a primary entry page that conforms to .
SHOULD conform to the accessibility requirements defined in .

In addition, all publication resources MUST adhere to the requirements in .

If an eBraille publication is packaged for distribution, it MUST adhere to the packaging requirements in .

The rest of this specification covers specific conformance details.

Publication resources

Introduction

An [=eBraille publication=] is typically composed of many resources — XHTML documents, CSS files, tactile graphics, audio, video, etc.

As an eBraille publication is intended to be easily packaged as a conforming [=EPUB publication=], the requirements for publication resources are inherited from EPUB, specifically as defined in [[epub-33]].

This section represents a subsetting of the EPUB requirements, as certain features, such as manifest fallbacks, are disallowed in eBraille publications.

Core media types

To ensure that [=eBraille reading systems=] are capable of rendering the content of [=eBraille publications=], only certain widely supported resource types are allowed to be included without fallbacks. These are called core media types and are designated by their MIME media type [[rfc2046]] (e.g., XHTML documents have the MIME media type application/xhtml+xml).

Being designated a core media type does not mean that all reading systems are required to support the type of resource, however. A reading system without audio capabilities will not be able to render audio core media types, for example.

The list of core media types allowed in eBraille publications is the same as those designated for EPUB 3. Some of the key core media types for eBraille include:

application/xhtml+xml — HTML documents that use the XML syntax [[html]].
text/css — CSS Style Sheets [[css2]].
image/jpeg — JPEG Images [[jpeg]]
image/png — PNG Images [[png]]
image/svg+xml — SVG images [[svg]]

The complete list is available in the core media types section of [[epub-33]].

All other media types are considered foreign resources.

Foreign resources

Foreign resources, unlike core media types, have no guarantee of support in reading systems.

To avoid users not being able to access the content of the [=eBraille publication=], foreign resources can only be used if a fallback to a core media type is provided. Fallbacks are provided using intrinsic fallback methods [[epub-33]].

Manifest fallbacks are not supported in eBraille. This means they cannot be used to include foreign resources in the spine or as a means of providing fallbacks for foreign image formats (in the latter case, fallbacks can be provided instead using the [[html]] [^img^] and [^picture^] elements' intrinsic fallback capabilities).

It is generally best to avoid foreign resources unless absolutely necessary. PDF tactile graphics are an example of a foreign resource that may not be avoidable for some [=eBraille creators=], but using the [[html]] [^object^] element's intrinsic fallback capabilities can avoid having to duplicate the image in a core media type format.

<object
     data="ebraille/images/clouds.pdf"
     type="application/pdf"
     height="250"
     width="100"
     aria-label="alternative text">
   <p><!-- description --></p>
</object>

Resource fallbacks

eBraille does not support the use of manifest fallbacks [[epub-33]].

The intrinsic fallback methods provided by [[html]] elements are supported.

Resource location

[=eBraille publications=] do not support [=remote resources=] [[epub-33]]. All publication resources MUST be located in or below the [=root directory=], as defined in .

eBraille does not support the file: URL scheme [[rfc8089]] for referencing resources in an eBraille publication. Accessing files on the user's local file system presents too great a security risk.

The data: URL scheme MAY be used to embed resources within [=eBraille content documents=] per the restrictions outlined in Data URLs [[epub-33]].

Exempt resources

It is possible to include additional resources in an [=eBraille publication=] that are not part of the rendering of the content. EPUB 3 defines resources that are not used in the [=spine=] or embedded in [=xhtml content documents=] as exempt from the normal [=core media type resource=] restrictions [[epub-33]].

This means, for example, that [=eBraille creators=] can embed pre-formatted braille in their publication in a format such as PDF or BRF. The resource would still be listed in the [=manifest=], but it would not be flagged as needing a fallback.

It would not be possible to link to these resources from the eBraille publication, but the publication could note the presence of the resources and include instructions on how to access them (e.g., to open the publication with a ZIP tool and navigate to a specific directory).

File extensions

Reading systems typically do not rely on file extensions for rendering, so, with a couple of notable exceptions for the package document and primary entry page, eBraille does not require specific extensions for the resources in an [=eBraille publication=]. The media type declared in the manifest is used as a hint to the nature of each resource, but even that declaration is not reliable. Instead, reading systems typically leave inspection of resources and their rendering to their underlying browser core.

The use of standard file extensions for resources should still be considered a best practice, however, as it avoids authoring confusion over the nature of resources.

Some formats have more than one common extension. For example, XHTML documents can use either the extension .html or .xhtml and JPEG images can use either .jpg or .jpeg. In these cases, either extension is acceptable.

This specification uses the .html extension in examples for [=eBraille content documents=] as it is more widely used and recognized than .xhtml, particularly for opening the primary entry page.

The .xhtml extension may be useful if eBraille content documents are opened in a browser on a local file system (e.g., for testing), as this triggers some browsers to render the content using the correct XML parser. The extension has no effect on documents served over the web, however.

XML conformance

The requirements for XML-based media types [[rfc2046]] defined in XML conformance [[epub-33]] also apply to [=eBraille publications=].

The only difference is that eBraille publications only support UTF-8 [[unicode]]. UTF-16 MUST NOT be used to encode XML resources.

eBraille file set

Introduction

The [=eBraille file set=] is like a physical manifestation of the OCF abstract container [[epub-33]]. EPUB 3 only defines its file set in the abstract because those files are expected to be zipped in the [=EPUB container=] [[epub-33]]; the standard is not concerned with the physical files before they are zipped or after they are unzipped. As a ZIP file does not have a true file system within it, the rules for file naming and placement can only be defined virtually.

eBraille moves the rules for the OCF abstract container to the physical file set that exists before and after packaging in the EPUB container. This allows an [=eBraille publication=] to be independent of packaging, making it a format that can flexibly move between web deployment and end-user distribution.

eBraille defines additional rules on the file structure in order to make it easier to read an eBraille publication on the web or from a local file system. In particular, it requires the [=EPUB navigation document=] [[epub-33]] be in the root of the file set and named index.html. These requirements do not conflict with being able to package an eBraille publication as a valid [=EPUB publication=] [[epub-33]], however.

File and directory structure

The [=eBraille file set=] MUST have a single common root directory — the [=publication root=] — for all the contents of the [=eBraille publication=].

Unlike EPUB 3, the eBraille file set MUST NOT reference resources outside the publication root (i.e., [=remote resources=] [[epub-33]] are not supported).

The eBraille file set MUST contain the following files in the publication root:

The EPUB navigation document [[epub-33]]. This file MUST be named index.html
The EPUB package document [[epub-33]]. This file MUST be named package.opf

There are no restrictions on where the rest of the eBraille publication content goes beyond the requirement in EPUB 3 that publication resources are not allowed in a META-INF directory [[epub-33]].

For simplicity of unzipping and accessing a publication on a user's local file system, [=eBraille creators=] are encouraged to place the rest of the publication in a subfolder (e.g., named "ebraille"). This will make the navigation document the first HTML file users encounter.

File paths and file names

To avoid potential naming issues when opening [=eBraille publications=] on common operating systems, eBraille file paths and file names MUST adhere to the EPUB 3 file naming restrictions specified in File paths and file names [[epub-33]].

URLs in the file set

Although the [=publication root=] establishes a common directory for all files in an [=eBraille publication=], depending on how the eBraille publication is deployed it could allow references to resolve outside of the publication root. For example, if an eBraille publication is deployed on the web, unless it assigned its own domain, a [=path-absolute-URL string=] [[url]] (i.e., a path that begins with a slash) could allow the publication to reach other resources on the server.

For this reason, the eBraille file set MUST NOT include file references that use path-absolute-URL strings.

Multiple renditions

An [=eBraille publication=] MAY contain multiple renditions of the content. The specifics of how this is done are defined in EPUB 3 Multiple-Rendition Publications 1.1 [[epub-multi-rend-11]].

When including multiple renditions, the default rendition [[epub-multi-rend-11]] — the one listed first in the container.xml file [[epub-33]] — MUST be a braille rendition. The default rendition has a default rendition:accessMode selection attribute [[epub-multi-rend-11]] equivalent to the value tactile. No other value is allowed if the attribute is set explicitly.

Subsequent renditions are exempt from the following requirements:

The file naming and location requirements for the package document and primary entry page, as this would cause conflicts.
The recommendation to use only 6- and 8-dot Unicode characters if the rendition is not in braille.
The publication language requirement to use the Brai script designator if the rendition is not in braille.

[[epub-multi-rend-11]] is only a W3C Working Group Note. The technology is not currently considered stable and should be used with appropriate caution.

The eBraille working group may consider a replacement technology for multiple renditions in a future version if there is significant need for them and implementation of the EPUB technology proves too difficult.

Package Document

Introduction

eBraille uses the EPUB 3 package document [[epub-33]] to express information about an [=eBraille publication=].

The package document is an XML document that contains three primary sections that encapsulate information about the content and how to render it:

Metadata — the metadata element contains bibliographic and rendering information about an eBraille publication.
Manifest — the manifest element contains a list of all the publication resources.
Spine — the spine element contains the default ordering of [=eBraille content documents=].

These sections are all contained within the root package element.

The primary difference of the eBraille package document is only in the metadata that is required and recommended. The eBraille implementation of the package document is also more limited in the features it allows — EPUB 3's manifest fallbacks and legacy elements [[epub-33]] are not allowed, for example.

The `package` element

At the root of the eBraille package document is the package element. This element MUST conform to the requirements for the package element in [[epub-33]].

For example, EPUB 3 requires the package element's version attribute [[epub-33]] have the value "3.0". This identifies that the package document conforms to the EPUB 3 definition. (The identifier that the content conforms to this specification is contained in the required dc:format element.)

It is also required that the unique-identifier attribute [[epub-33]] be specified. This attribute references the ID of the dc:identifier element that contains the unique identifier for the publication.

Although setting the default language of the package document text on the package element is not required, it is best practice to set it here in an xml:lang attribute [[epub-33]] so that language information is available for every element that requires it.

In this example, a dc:identifier element with the id attribute value uid (not shown) is specified in the metadata.

<package xmlns="http://www.idpf.org/2007/opf"
         version="3.0"
         unique-identifier="uid"
         xml:lang="en">
   …
</package>

Metadata

About package document metadata

Metadata elements

Metadata about an [=eBraille publication=] is expressed in the package document's metadata element [[epub-33]]. This element is the first child of the root package element.

The following elements are allowed as children of the metadata element:

Dublin Core elements

Dublin Core defines 15 elements in the /elements/1.1/ namespace [[dcterms]]. Any of these element can be used in the metadata element — elements not listed in the required or recommended metadata sections are considered optional elements.

The meta element

The meta element [[epub-33]] is used to express properties from metadata vocabularies, where its property attribute defines the property name.

Metadata properties defined in this element typically require a prefix (many prefixes are reserved and do not have to be declared).

The link element

The link element [[epub-33]] is used to associate resources with an [=eBraille publication=], such as metadata records.

Linked resources are typically not publication resources so are not listed in the manifest.

Metadata properties defined in this element also typically require a prefix.

For more information about the attributes allowed on these elements, refer to their definitions in [[epub-33]].

Metadata values

EPUB 3 requires that all Dublin Core [[dcterms]] and meta elements have child text content [[epub-33]] (i.e., they have to have at least one non-whitespace character after leading and trailing ASCII whitespace [[?infra]] is stripped). In the descriptions for these elements, this specification refers to this content as the element's value.

Whitespace within these element values is not significant. Sequences of one or more whitespace characters are collapsed to a single space [[infra]] during processing.

Using prefixes

The meta element and link element are meant for use with properties defined in existing metadata vocabularies, such as those in the Dublin Core /terms/ namespace [[dcterms]].

EPUB 3 defines a set of reserved prefixes [[epub-33]] for common metadata vocabularies. Properties from these vocabularies can be used without having to declare their prefix.

If properties from other vocabularies are needed, a prefix needs to be declared before they can be used. Prefixes are defined in the prefix attribute on the root package element. Both the prefix and a URL to associate with the prefix have to be specified. These values are separated by whitespace.

<package … prefix="ex: https://example.com/metadata/">
   <metadata>
      …
      <meta property="ex:revisionDate">2024-01-01</meta>
      …
   </metadata>
   …
</package>

For more information about using prefixes in the package document, refer to Vocabulary association mechanisms [[epub-33]].

General requirements

The eBraille package document metadata:

MUST meet all the requirements for EPUB 3 metadata [[epub-33]].
MUST include all metadata defined in .
SHOULD include all metadata defined in .

Required metadata

dc:creator

The REQUIRED dc:creator element [[dcterms]] identifies the name(s) of the primary author, editor, etc. Follow regional conventions for name layout.

<dc:creator>
   Mark Twain
</dc:creator>

<dc:creator>
   Akiko AKAZOME
</dc:creator>

The element MAY include the following attributes: dir, id, xml:lang [[epub-33]].

Repeat the element for each creator name.

To identify the role the creator played in the creation of the content, associate a role property [[epub-33]] with the element.

<dc:creator id="aut01">
   Charlotte Brontë
</dc:creator>
<meta property="role" refines="#aut01">aut</meta>

<dc:creator id="aut02">
   Herman Melville
</dc:creator>
<meta property="role" refines="#aut02">aut</meta>

To provide the creator's name for sorting purposes, associate a file-as property [[epub-33]] with the element.

<dc:creator id="aut01">
   Charlotte Brontë
</dc:creator>
<meta property="file-as" refines="#aut01">Brontë, Charlotte</meta>

For more information, refer to the definition of the dc:creator element in [[epub-33]].

dc:format

The REQUIRED dc:format element [[dcterms]] identifies version of the eBraille standard an publication conforms to. The [=value=] MUST contain both the name "eBraille" and the version number.

For example, for this version of the specification, the value would be "eBraille 1.0".

<dc:format>
   eBraille 1.0
</dc:format>

The element MAY include an id attribute [[epub-33]].

dc:identifier

The REQUIRED dc:identifier element [[epub-33]] contains an identifier for an [=eBraille publication=], such as a UUID, DOI, or ISBN.

These identifiers SHOULD be formatted using a Uniform Resource Name.

<dc:identifier>
   urn:uuid:550e8400-e29b-41d4-a716-446655440000
</dc:identifier>

<dc:identifier>
   urn:doi:10.1080/10509585.2015.1092083
</dc:identifier>

<dc:identifier>
   https://en.wikipedia.org/wiki/Braille
</dc:identifier>

The element MAY include an id attribute [[epub-33]].

One identifier MUST be identified as the unique identifier for the publication using the package element's unique-identifier attribute [[epub-33]]. This identifier MUST be unique to the publication.

<package … unique-identifier="uid">
   <metadata>
      <dc:identifier id="uid">
         urn:isbn:978-3-16-148410-0
      </dc:identifier>
      …
   </metadata>
   …
</package>

For more information, refer to the definition of the dc:identifier element in [[epub-33]].

dc:language

The REQUIRED dc:language element [[epub-33]] identifies the language(s) of the [=eBraille publication=].

The [=value=] MUST be a well-formed language tag [[bcp47]]. The language code MUST include the script subtag Brai to indicate the text is encoded in braille.

<dc:language>
   it-Brai
</dc:language>

When specified, a country code subtag MUST refer to the language of the work being transcribed.

<dc:language>
   en-Brai-US
</dc:language>

The element MAY include an id attribute [[epub-33]].

If multiple languages are used, repeat the tag for each language. The first language listed in document order MUST be the primary language of the publication.

<dc:language>
   fr-Brai-FR
</dc:language>
<dc:language>
   de-Brai-DE
</dc:language>

For more information, refer to the definition of the dc:language element in [[epub-33]].

dc:title

The REQUIRED dc:title element [[dcterms]] identifies the title of the source material.

<dc:title>
   Aus meinem Leben: Dichtung und Wahrheit
</dc:title>

The element MAY include the following attributes: dir, id, xml:lang [[epub-33]].

The first dc:title element in document order identifies the primary title of the [=eBraille publication=]. Subsequent dc:title elements may be ignored by reading systems, so consider merging titles into a single tag if it is important that users have access to the complete set of titles.

For more information, refer to the definition of the dc:title element in [[epub-33]].

dcterms:dateCopyrighted

The REQUIRED dcterms:dateCopyrighted property [[dcterms]] identifies the copyright date of the work being transcribed.

The property is defined in a meta tag with its property attribute set to dcterms:dateCopyrighted.

The [=value=] of the property MUST be an [[iso8601-1]] conformant date of the form YYYY-MM-DD, YYYY-MM, or YYYY

<meta property="dcterms:dateCopyrighted">
   2010-01-02
</meta>

<meta property="dcterms:dateCopyrighted">
   2014
</meta>

dcterms:modified

The REQUIRED dcterms:modified property identifies the date, in Coordinated Universal Time (UTC), on which an [=eBraille publication=] was last modified.

The property is defined in a meta tag with its property attribute set to dcterms:modified.

<meta property="dcterms:modified">
   2014-10-14T18:45:00Z
</meta>

The [=value=] MUST be an [[xmlschema-2]] dateTime conformant date of the form: YYYY-MM-DDThh:mm:ssZ, where YYYY represents the year, MM the month, DD the day, T is a separator indicating the start of the time section, hh the hour, mm the minutes, ss the seconds, and Z represents the UTC time zone designator.

For more information, refer to the definition of the last modified date [[epub-33]].

Recommended metadata

dc:publisher

The RECOMMENDED dc:publisher element identifies the name(s) of the organization(s) or individual(s) that published the [=eBraille publication=].

<dc:publisher>
   Royal National Institute of Blind People
</dc:publisher>

The element MAY include the following attributes: dir, id, xml:lang [[epub-33]].

Repeat the property for each organization or individual.

dc:description

The RECOMMENDED dc:description element provides an abstract, a table of contents, or a free-text account of the resource.

<dc:description>
   Frankenstein tells the story of Victor Frankenstein,
   a young scientist who creates a sapient creature in
   an unorthodox scientific experiment.
</dc:description>

The element MAY include the following attributes: dir, id, xml:lang [[epub-33]].

Only one instance of this element is allowed.

dc:rights

The RECOMMENDED dc:rights element provides rights information about an [=eBraille publication=]. The rights statement includes various property rights associated with the resource, including intellectual property rights.

<dc:rights>
   Further reproduction or distribution in other 
   than an accessible format is prohibited.
</dc:rights>

The element MAY include the following attributes: dir, id, xml:lang [[epub-33]].

Repeat the element to include more than one rights statement.

dc:source

The RECOMMENDED dc:source element provides a reference to the work being transcribed.

<dc:source>
   urn:isbn:0-618-16841-9
</dc:source>

The [=value=] of the element SHOULD uniquely identify the source. An ISBN, DOI, ISSN or similar identifier from a controlled system is preferred.

The element MAY include an id attribute [[epub-33]].

dc:subject

The RECOMMENDED dc:subject element [[dcterms]] identifies the subject of an [=eBraille publication=].

The [=value=] SHOULD be a human-readable heading or label, but a code value MAY be used if the subject taxonomy does not provide a separate descriptive label.

<dc:subject>
   Geography
</dc:subject>

The element MAY include the following attributes: dir, id, xml:lang [[epub-33]].

The system or scheme the element's value was drawn from MAY be identified using the authority property [[epub-33]]. A subject code MUST also be specified when specifying the authority property.

<metadata …>
   <dc:subject id="subject01">
      POETRY / Epic
   </dc:subject>
   <meta
       refines="#subject01"
       property="authority">
      BISAC
   </meta>
   <meta
       refines="#subject01"
       property="term">
      POE014000
   </meta>
</metadata>

Repeat the element for each subject.

For more information, refer to the definition of the dc:subject element in [[epub-33]]

dcterms:educationLevel

The RECOMMENDED dcterms:educationLevel property identifies the level of education an [=eBraille publication=] is targeted to (e.g., the grade level).

The property is defined in a meta tag with its property attribute set to dcterms:educationLevel.

<meta property="dcterms:educationLevel">
   3rd grade
</meta>

Repeat the element if the publication is intended for more than one education level.

Additional metadata

The package document metadata section MAY include any other Dublin Core elements [[epub-33]] not listed as required or recommended.

Metadata from vocabularies with a reserved prefix MAY also be added. Properties from other vocabularies are also allowed provided a prefix [[epub-33]] is defined.

The accessibility metadata properties defined in this specification can be used without defining the a11y: prefix, as detailed in .

Examples

<package … 
          xmlns:dc="http://purl.org/dc/elements/1.1/"
          unique-identifier="uid">
   <metadata>
      <!-- required metadata -->
      <dc:title>World Cultures and Geography</dc:title>
      <dc:creator>Sarah Witham Bednarz</dc:creator>
      <dc:creator>Ines M. Miyares</dc:creator>
      <dc:creator>Mark C. Schug</dc:creator>
      <dc:creator>Charles S. White</dc:creator>
      <dc:format>eBraille 1.0</dc:format>
      <dc:identifier id="uid">
         41f1328c-0571-4e71-8be8-e65bc148281a
      </dc:identifier>
      <dc:language>en-Brai-US</dc:language>
      <meta property="dcterms:dateCopyrighted">
         2024
      </meta>
      <meta property="dcterms:modified">
         2015-02-24T13:37:19Z
      </meta>
      <meta property="a11y:cellType">6</meta>
      <meta property="a11y:code">UEB</meta>
      <meta property="a11y:completeTranscription">
         false
      </meta>
      <meta property="a11y:created">2003</meta>
      <meta property="a11y:producer">
         DAISY Consortium
      </meta>
      <meta property="a11y:sourcePublisher">
         McDougal Littell, a division of
         Houghton Mifflin Company
      </meta>
      <meta property="a11y:tactileGraphics">false</meta>

      <!-- recommended metadata -->
      <dc:publisher>DAISY Consortium</dc:publisher>
      <dc:date>2014-12-11T09:12:52+00:00</dc:date>
      <dc:description>
         This is a sample eBraille publication.
      </dc:description>
      <dc:rights>All rights reserved.</dc:rights>
      <dc:source>urn:isbn:9780618596645</dc:source>
      <dc:subject>Social Studies</dc:subject>
      <meta property="dcterms:educationLevel">
         06 and up
      </meta>
      
      <!-- other metadata -->
      <meta property="a11y:pageBreakSource">
         urn:isbn:9780618596645
      </meta>
      <meta property="a11y:contributor">
         DAISY XML Techniques Team
      </meta>
      <meta property="schema:accessMode">
         tactile
      </meta>
      <meta property="schema:accessibilityFeature">
         alternativeText
      </meta>
      <meta property="schema:accessibilityFeature">
         longDescription
      </meta>
      <meta property="schema:accessibilityFeature">
         printPageNumbers
      </meta>
      <meta property="schema:accessibilityFeature">
         readingOrder
      </meta>
      <meta property="schema:accessibilityFeature">
         structuralNavigation
      </meta>
      <meta property="schema:accessibilityFeature">
         tableOfContents
      </meta>
      <meta property="schema:accessibilityFeature">
         unlocked
      </meta>
      <meta property="schema:educationalRole">
         student
      </meta>
      <meta property="schema:typicalAgeRange">18+</meta>
   </metadata>
   …
</package>

Manifest

The package document manifest element [[epub-33]] contains a list all of the resources in the [=eBraille publication=]. It is the second required child of the root package element.

Each item element [[epub-33]] child of the manifest defines one resource, minimally providing the following information:

an identifier for the resource in its id attribute [[epub-33]];
the location of the resource in its href attribute [[epub-33]]; and
the media type of the resource in its media-type attribute [[epub-33]].

<package …>
   …
   <manifest>
      <item id="c01"
            href="eBraille/chapter01.xhtml"
            media-type="application/xhtml+xml"
      …
   </manifest>
   …
</package>

Manifest entries may also identify specific properties of the resource in the properties attribute. For eBraille, this attribute will typically only be used for the navigation document and when SVG tactile graphics are embedded in the resource.

In this example, the chapter02.html file contains one or more SVG images. These images could be embedded directly in the HTML document using the svg element or they could be separate resources referenced from img or object elements (in which case the images would also be listed in the manifest).

<package …>
   …
   <manifest>
      …
      <item id="c02"
            href="eBraille/chapter02.html"
            media-type="application/xhtml+xml"
            properties="svg"
      …
   </manifest>
   …
</package>

The manifest entries for [=eBraille content documents=] may also indicate if a media overlay document is available in the media-overlay attribute [[epub-33]].

For the complete set of requirements for the manifest, refer to the The manifest element in [[epub-33]].

As eBraille does not support manifest fallbacks, the fallback attribute is not supported.

Spine

The package document spine element [[epub-33]] is the third required child of the root package element. It defines the default reading order for an [=eBraille publication=].

Each itemref child of the spine references the manifest entry for an [=eBraille content document=] in its required idref attribute [[epub-33]].

<package …>
   …
   <manifest>
      <item id="c01"
            href="eBraille/chapter01.xhtml"
            media-type="application/xhtml+xml"
      …
   </manifest>
   <spine>
      <itemref idref="c01"/>
      …
   </spine>
</package>

The linear attribute [[epub-33]] is used to indicate if the resource referenced contains content that must be read sequentially or not. Linear content typically consists of eBraille content documents that contain content in the primary reading order while non-linear content contains supplementary material such as notes and descriptions that can be accessed out of sequence (e.g., an [=eBraille reading system=] might opt to not render them until after all the linear content has been read). If the linear attribute is not specified, the spine item defaults to being linear content (i.e., the attribute is only required to specify non-linear content).

In the following example, the answer key for chapter 5 of a publication is marked as non-linear.

<package …>
   …
   <spine>
      …
      <itemref idref="c05"/>
      <itemref idref="c05-answers" linear="no"/>
      <itemref idref="c06"/>
      …
   </spine>
</package>

For the complete set of requirements for the spine, refer to the The spine element in [[epub-33]].

Unsupported features

The following features of the EPUB 3 package document are not supported in eBraille so MUST NOT be used:

all features marked as deprecated [[epub-33]]
manifest fallbacks
collections [[epub-33]]
legacy features [[epub-33]]

eBraille content documents

Introduction

[=eBraille content documents=] define the markup and presentation of the content of an [=eBraille publication=]. An eBraille content document is encoded using the XML syntax of [[html]], also commonly known as XHTML, and is styled using CSS [[css2]].

eBraille content documents are not limited to formatted text. For example, they may include tactile graphics, audio, and video. The primary difference between the features of an eBraille content document and a typical web page is that scripting and forms are not supported.

Note that unlike EPUB 3, eBraille only supports XHTML in the [=spine=] of an eBraille publication. SVG images are not supported in the [=spine=] but can be embedded in XHTML documents.

XHTML

An [=eBraille content document=] MUST be an XHTML content document as defined [[epub-33]] with additional constraints as defined in the following subsections.

Character encoding

[=eBraille content documents=] are required to provide their text content in 6- or 8-dot braille characters. eBraille is not meant as a delivery format for ASCII braille or similar mappings to braille cells.

For this reason, the text content of [=eBraille content documents=] SHOULD consist only of the following [[unicode]] characters:

Braille Patterns (U+2800 … U+28FF) ;
Whitespace [[xml]]:
- TAB (U+0009)
- LF (U+000A)
- CR (U+000D)
- SPACE (U+0020)
NO-BREAK SPACE (U+00A0)
SOFT HYPHEN (U+00AD)

The zero width space character is not included in this list as eBraille creators are advised to use the [^wbr^] element [[html]] to indicate break opportunities within words.

This restriction only applies to the renderable text of an XHTML document as well as the attributes that could be rendered depending on the display capabilities of a device or user configuration settings, for example:

the [^img/alt^] attribute [[html]] for images and image maps that cannot be displayed;
the [^th/abbr^] attribute [[html]] for alternative table headings;
the [^abbr/title^] attribute [[html]] for expansions of abbreviations.

This restriction does not apply to attributes that carry meta information (e.g., the [^global/class^] and [^a/href^] attributes [[html]], as well as the [^html-global/title^] attribute in the page list).

For some technologies that can be embedded in eBraille content documents, such as [[mathml]], it will not be possible to restrict the text to braille characters.

Unsupported features

eBraille does not support scripted interactivity or form submissions. Consequently, [=eBraille creators=] MUST NOT include [[html]] [^script^] elements or the [^form^] element's [^form/action^] attribute in eBraille content documents.

The lack of support for scripting means that html elements that depend on scripting (e.g., the [^canvas^] element and custom elements) will not work in [=eBraille publications=]. It is strongly recommended not to include these elements, as well.

An exemption is made to the scripting requirement for the primary entry page so long as it is not listed in the spine. The exemption is to allow publishers to add a user interface for web deployment.

Cascading Style Sheets (CSS)

Introduction

[=eBraille creators=] may use CSS [[css2]] to style and lay out [=content documents=]. With the few exceptions defined in this section, eBraille defers to [[epub-33]], and more specifically to the CSS standardization work done in W3C, to define CSS.

Keep in mind that some [=reading systems=] will not support all desired features of CSS. The following are identified as potentially problematic, depending on the technology choices of reading system implementations, and should therefore be used with caution:

The "CSS Paged Media Module Level 3" working draft [[css-page]], which builds on the "Paged media" section of [[css2]], is not well supported in web browsers.

Note that the presentation of content is not determined by author style sheets only. Reading systems are expected to apply default styles that make sense for the current locale, in case author styles are missing or incomplete. This may be done through CSS or through other means. Reading systems may also perform specific styling according to user preferences.

CSS requirements

The requirements for using CSS to style [=eBraille content documents=] are defined in CSS requirements [[epub-33]] but with the following differences:

[=eBraille creators=] MUST NOT use -epub- prefixed properties [[epub-33]].
CSS style sheets MUST be UTF-8 encoded [[unicode]].

In addition, eBraille creators:

SHOULD NOT use properties that affect the text's font (e.g., which font gets applied, its size, whether it is bold, italic, etc.). Creators should assume that reading systems determine the shape and size of the braille symbols (e.g., for technical reasons, or to ensure a good reading experience).

The font-related properties include, but are not limited to:
- font-family,
- font-size,
- font-style,
- font-weight and
- font-variant [[css-fonts]],
- color [[css-color]],
- text-decoration,
- text-shadow and
- text-underline-position [[css-text-decor]]
SHOULD use font-relative lengths [[css-values]] only. Because it should be assumed that creators have no control over the font used by the reading device, using absolute lengths is regarded as unreliable. Using font-relative lengths in style sheets is also needed in order to reliably use relative widths and heights in media queries.

More specific guidance on how to use CSS properties in eBraille content documents is provided in the eBraille Styling Best Practices.

Media queries

eBraille allows the use of media queries [[mediaqueries]] to support styling and content that is conditional on the type and characteristics of the device.

The restrictions and recommendations in this section apply to CSS (e.g. @media [[css-conditional]] and @import [[css-cascade]] rules), as well as where media queries are used as a microsyntax in [[html]] (such as in the link and style elements), and in xml-stylesheet processing instructions [[xml-stylesheet]].

[=eBraille creators=] SHOULD NOT use media queries that discriminate between a braille display and a screen when the target medium is a braille display.

The logical consequence of this is that it will be impossible to discriminate between visual and tactile access modes. In other words, it forces rendering on a screen and on a braille display, that are otherwise comparable, to be the same, and the CSS to have the same requirements.

The use of braille, and (grid) is not recommended because there are currently no known CSS implementations that match these types, so requiring [=eBraille reading systems=] to match them could be problematic.

Using screen is also not recommended to be forward-compatible with a possible future version of the standard that supports differences in styling for screens vs. braille displays.

To adapt the styling based on the dimensions of the viewport, eBraille creators SHOULD use font-relative lengths.

More specific guidance on how to use media queries in eBraille content documents is provided in the eBraille Styling Best Practices.

Authoring best practices

As this is a technical specification for the eBraille format, its focus is on the technologies for creating [=eBraille content documents=]. It does not specify a specific manner in which the content must be created, as regional differences in braille codes will influence how any given publication is formatted.

A goal of the eBraille format, however, is, as much as possible, to promote common markup practices across regions so that organizations and individuals can interchange files without needing to completely reformat them. Using common markup practices will allow [=eBraille reading systems=] to apply regional CSS rules, improving the readability for users expecting different braille formatting conventions.

To this end, eBraille content documents rely primarily on the [[html]] [^global/class^] and [^/role^] attributes to identify formatting requirements. Augmenting core HTML elements with a common set of classes and roles will make eBraille publications more predictable for reformatting.

The eBraille working group is working on a set of best practices to help facilitate this model. These include:

eBraille Tagging Best Practices — This document defines the core HTML elements and attributes to structure braille content.
eBraille Styling Best Practices — This document defines CSS styling conventions to use to render braille content.

Layout rendering control

eBraille does not support fixed layouts as defined in [[epub-33]]. Consequently, [=eBraille publications=]:

MUST NOT specify the rendition:layout property with the value pre-paginated in the package document metadata or specify its override property rendition:layout-pre-paginated on spine items [[epub-33]].
MUST NOT specify any other properties or spine overrides defined in Fixed-layout package settings [[epub-33]].

Primary entry page

Introduction

To make it easier to deploy [=eBraille publications=] on the web, the [=EPUB navigation document=] is used as the primary entry point for publications. The required file naming (index.html) and location of this file mean it will be the first document loaded when users browse to a folder containing an eBraille publication.

By requiring the [=primary entry page=] be located in the [=publication root=], it is also easier for users to unzip an eBraille publication and read it locally, if they so choose. If all the other resources in the publication are placed in a subfolder, for example, the primary entry page will be the first HTML document users encounter in the unzipped folder.

The primary entry page does not have to be the first document in the spine, however. As the page is meant as an entryway for web reading, it may not be helpful to include it in the spine at all. Reading systems will still be able to extract the table of contents and other information from the document even if it is not in the spine.

General requirements

The primary entry page MUST be a conforming EPUB navigation document [[epub-33]]. In addition, it MUST be named index.html and be located in the [=publication root=], as defined in .

The primary entry page MUST include an [[html]] [^link^] element with its [^link/rel^] attribute set to the value publication. The [^link/href^] attribute MUST specify the package document and the [^link/type^] attribute MUST contain the media type of the package document (application/oebps-package+xml).

<html …>
   <head>
      …
      <link rel="publication" href="package.opf" type="application/oebps-package+xml"/>
      …
   </head>
   <body>
      …
   </body>
</html>

Although it is possible to discover the package document by its required name and location, this requirement ensures that [=eBraille reading systems=] can programmatically determine that the primary entry page belongs to an [=eBraille publication=] (i.e., to avoid having to check for a package document for any web page a user might try to open).

The primary entry page MAY include [[html]] [^script^] elements only if the document is not included in the spine. This exception is to allow publishers to include a user interface to better enable reading of their publication in browsers. It is not meant for general scripting of the content.

A scripted primary entry page is not allowed in the spine as an extra measure to ensure that the scripting does not interfere with rendering in [=eBraille reading systems=]. Reading systems are expected to disable the scripting in the primary entry page regardless of the document's placement in the spine.

As the primary entry page is meant to help browser users navigate the publication, it SHOULD NOT be included in the spine. If the publication needs a table of contents in the spine, it is better to create a separate document with publication-specific formatting.

As per the requirements of EPUB 3, the manifest entry for the primary entry page has to have a properties attribute with the value nav [[epub-33]].

<package …>
   …
   <manifest>
      <item id="nav" href="index.html" type="application/xhtml+xml" properties="nav"/>
      …
   </manifest>
   …
</package>

Navigation

The table of contents provides users access to the major sections of the publications.

The EPUB 3 specification requires that the table of contents be defined in an [[html]] [^nav^] element whose epub:type attribute specifies the value "toc" [[epub-33]].

For compatibility with web-based rendering, the table of contents MUST also be identified by the [^/role^] attribute [[html]] value "doc-toc" [[dpub-aria]].

<html xmlns="http://www.w3.org/1999/xhtml"
      xmlns:epub="http://www.idpf.org/2007/ops"
      …>
   …
   <body>
      <nav epub:type="toc"
           role="doc-toc"
           aria-label="Table of Contents">
         <h2>⠠⠞⠁⠃⠇⠑⠀⠕⠋⠀⠠⠉⠕⠝⠞⠑⠝⠞⠎</h2>
         …
      </nav>
   </body>
</html>

The table of contents is defined by a single [[html]] ordered list ([^ol^]) in the root of the nav element. Each [[html]] list item ([^li^]) represents one of the top-level sections of the publication. If the section can be linked to, wrap its heading inside an [[html]] anchor tag ([^a^]), otherwise wrap the heading in a [^span^] element (unlinked headings are not common outside of publications that omit content).

<nav epub:type="toc"
     role="doc-toc"
     aria-label="Table of Contents">
   <h2>⠠⠞⠁⠃⠇⠑⠀⠕⠋⠀⠠⠉⠕⠝⠞⠑⠝⠞⠎</h2>

   <ol>
      <li>
         <a href="chap01.html#c01">
            ⠠⠉⠓⠁⠏⠞⠑⠗⠀⠼⠁
         </a>
      </li>
      <li>
         <a href="chap02.html#c02">
            ⠠⠉⠓⠁⠏⠞⠑⠗⠀⠼⠃
         </a>
      </li>
      <li>
         <a href="chap03.html#c03">
            ⠠⠉⠓⠁⠏⠞⠑⠗⠀⠼⠉
         </a>
      </li>
      …
   </ol>
</nav>

If a section contains additional subsections, list those headings in an ol element after the link to the heading.

<li>
   <a href="part01.html#p01">
      ⠠⠏⠁⠗⠞ ⠼⠁
   </a>
   <ol>
      <li>
         <a href="sec01.html#s01">
            ⠠⠎⠑⠉⠞⠊⠕⠝ ⠼⠁
         </a>
      </li>
      …
   </ol>
</li>

The minimalist rules on the structure of the table of contents are to ensure that [=eBraille reading systems=] can reliably process the information and present it to users in a specialized interface. The table of contents is not normally included in the spine for reading; it is typically only presented directly to users if they load the primary entry page in a browser.

For more information, refer to The toc nav element in [[epub-33]].

Page list

The page list provides users to access to static page break locations in an [=eBraille publication=]. These static page breaks typically correspond to the page breaks in the source publication.

The EPUB 3 specification requires that the page list be defined in an [[html]] [^nav^] element whose epub:type attribute specifies the value "page-list" [[epub-33]].

For compatibility with web-based rendering, the page list MUST also be identified by the [^/role^] attribute [[html]] value "doc-pagelist" [[dpub-aria]]

<html xmlns="http://www.w3.org/1999/xhtml"
      xmlns:epub="http://www.idpf.org/2007/ops"
      …>
   …
   <body>
      …
      <nav epub:type="page-list"
           role="doc-pagelist"
           aria-label="Page List">
         <h2>⠠⠏⠁⠛⠑ ⠠⠇⠊⠎⠞</h2>
         …
      </nav>
   </body>
</html>

The page list is defined by a single [[html]] ordered list ([^ol^]) in the root of the nav element. Each [[html]] list item ([^li^]) represents one static page break in the publication, with the page number wrapped inside an [[html]] anchor tag ([^a^]) that links to its location.

Each entry in the page list MUST include the print page number equivalent in a [^title^] attribute [[html]]. Providing both encodings allows reading systems to match the page number regardless of whether the device accepts braille input or not and avoids mistranslation of the page numbers if only one encoding is provided.

<nav epub:type="page-list"
     role="doc-pagelist"
     aria-label="Page List">
   <h2>⠠⠏⠁⠛⠑ ⠠⠇⠊⠎⠞</h2>
   <ol>
      <li>
         <a href="intro.html#pi"
            title="i">
            ⠊
         </a>
      </li>
      <li>
         <a href="intro.html#pii"
            title="ii">
            ⠊⠊
         </a>
      </li>
      …
      <li>
         <a href="chap01.html#p001"
            title="1">
            ⠼⠁
         </a>
      </li>
      <li>
         <a href="chap01.html#p002"
            title="2">
            ⠼⠃
         </a>
      </li>
      …
   </ol>
</nav>

Only include the page number in the a tag. Adding words such as "page" may break the ability of users to jump to the page break (i.e., [=reading systems=] will typically try to find an exact match for the page number a user enters).

Unlike the table of contents, the page list cannot include nested lists. It is not possible to group pages together by the section they belong to, for example.

For more information, refer to The page-list nav element in [[epub-33]].

Landmarks

Landmarks identify key structures of an [=eBraille publication=] that users may want a quick way to access. Landmarks are not a repetition of the table of contents, but a more select list of locations that users may want to refer to while reading.

The most common landmark in EPUB 3, for example, is the location where the body matter begins. Providing this location allows reading systems to skip the front matter and load the first page when users open a publication. Other key landmarks include glossaries and indexes, as users often need to access these reference sections for more information while reading.

A future update may recommend specific landmarks to include.

The EPUB 3 specification requires that the landmarks be defined in an [[html]] [^nav^] element whose epub:type attribute specifies the value "landmarks" [[epub-33]].

<html xmlns="http://www.w3.org/1999/xhtml"
      xmlns:epub="http://www.idpf.org/2007/ops"
      …>
   …
   <body>
      …
      <nav
           epub:type="landmarks"
           aria-label="Landmarks">
         <h2>⠠⠇⠁⠝⠙⠍⠁⠗⠅⠎</h2>
         …
      </nav>
   </body>
</html>

Due to the conflicting naming with ARIA landmarks [[wai-aria-1.2]], the DPUB-ARIA vocabulary [[dpub-aria]] does not include a role for a landmarks navigation element.

Landmarks are defined by a single [[html]] ordered list ([^ol^]) in the root of the nav element. Each [[html]] list item ([^li^]) represents one landmark in the publication.

The name of the landmark is wrapped inside an [[html]] anchor tag ([^a^]) that provides a machine-readable semantic that identifies the type of landmark in its epub:type attribute. These semantics are drawn from the EPUB Structural Semantics Vocabulary [[epub-ssv-11]].

<nav
     epub:type="landmarks"
     aria-label="Landmarks">
   <h2 id="lm-hd">⠠⠇⠁⠝⠙⠍⠁⠗⠅⠎</h2>
   <ol>
      <li>
         <a href="chap01.html" epub:type="bodymatter">
            ⠠⠎⠞⠁⠗⠞ ⠕⠋ ⠃⠕⠙⠽ ⠍⠁⠞⠞⠑⠗
         </a>
      </li>
      <li>
         <a href="glossary.html" epub:type="glossary">
            ⠠⠛⠇⠕⠎⠎⠁⠗⠽
         </a>
      </li>
   </ol>
</nav>

For more information, refer to The landmarks nav element in [[epub-33]].

Media overlays

eBraille publications support media overlays as defined in [[epub-33]]. Media overlays allow prerecorded audio to be synchronized with the content of [=eBraille content documents=], allowing users to switch between reading braille, listening to auditory playback, or reading along with narration.

A media overlay document MAY be associated with an [=eBraille content document=] by adding a media-overlays attribute to its package document manifest entry.

The following package document manifest markup shows the media overlay for the eBraille content document is identified by its ID.

<package …>
   …
   <manifest>
      …
      <item id="c01"
            href="braille/content/ch01.xhtml"
            media-type="application/xhtml+xml"
            media-overlays="c01-overlay"/>
            
      <item id="c01-overlay"
            href="braille/overlays/ch01.smil"
            media-type="application/smil+xml"/>
      …
   </manifest>
   …
</package>

The body of a media overlay document consists of [^par^] and [^seq^] elements [[epub-33]]. The par element defines the audio content to associate with the specified content, while seq elements are used to group par and other seq elements into logical structures such as figures and tables.

The following media overlay document shows the markup for a table. seq elements are used to define the table and rows, while par elements define the text and audio synchronization for cell content.

<smil …>
   …
   <body>
      …
      <seq epub:type="table">
         <seq epub:type="table-row">
            <par epub:type="table-cell">
               <text src="braille/content/ch01.xhtml#t1r1c1"/>
               <audio src="braille/audio/ch01.mp3" clipBegin="24:22.67" clipEnd="24:44.98"/>
            </par>
            
            <par epub:type="table-cell">
               <text src="braille/content/ch01.xhtml#t1r1c2"/>
               <audio src="braille/audio/ch01.mp3" clipBegin="24:44.98" clipEnd="25:03.36"/>
            </par>
            …
         </seq>
         …
      </seq>
      …
   </body>
</smil>

Although it is possible to associate styling information [[epub-33]] with the audio playback, eBraille reading systems are not expected to use this information. It would only be used if the [=eBraille publication=] were visually rendered, such as if the publication were opened in a mainstream EPUB 3 reading system.

For more information about creating media overlay documents, refer to the Media overlays section of [[epub-33]].

Packaging

When [=eBraille publications=] are distributed to end users as a single file set, they MUST be packaged in a conforming EPUB container as defined in OCF ZIP Container [[epub-33]].

As packaging is separate from the [=eBraille file set=], the mimetype and container.xml files [[epub-33]] are only required for a packaged eBraille file. The files MAY be omitted if an eBraille publication is not packaged.

Packaged eBraille publications use the same media type identifier as EPUB in the mimetype file: application/epub+zip [[epub-33]]. The requirements for specifying this identifier in the mimetype file are defined in OCF ZIP container media type identification [[epub-33]].

The EPUB media type identifier is required in the mimetype file for conformance with the OCF Zip Container and helps make eBraille files compatible with EPUB reading systems.

The actual media type for eBraille publications is application/ebrl+zip, as defined in . This is the media type used, for example, in the Content-Type header [[rfc9110]] when serving packaged eBraille publications over the web.

A packaged eBraille file set MUST use the extension .ebrl.

If an eBraille file is packaged with the extension .epub, it will not be recognized by eBraille reading system as an eBraille publication. In this case, the file would be recognized as an EPUB publication and could be opened in EPUB reading systems (with some loss of braille-specific functionality).

As the use of CSS font properties is not recommended, eBraille creators SHOULD NOT use EPUB's font obfuscation algorithm [[epub-33]] to embed fonts.

Security and privacy

Threat model

Although eBraille shares a common file set with EPUB 3, many of the privacy and security threats [[epub-33]] that arise with EPUB 3 publications do not apply to [=eBraille publications=]. The reason is that the primary threat vectors in EPUB 3 come from its allowance of scripting and network access. Users do not face the same risks from third party scripts, from attempts by publishers to monitor their activities or profile them through scripting, or from malicious code being brought in by remote resource calls, among other threats outlined in EPUB 3.

It does not mean that there are no security or privacy risks with eBraille publications. [=eBraille creators=] still need to ensure they maintain the security and privacy rights of users when creating their publications. The possible areas of concern for eBraille publications include:

Linking to external resources: Linking out to resources on the web can expose users to potential malicious content. Broken-link hijacking is one example where a malicious actor may buy the expired domain of a site and redirect users to content the eBraille creator never intended. Links to a publishers web site could allow them to profile users if they include tracking information.
Including malicious content: Although eBraille does not allow eBraille creators to embed remote resources in publications, using third-party resources, such as tactile graphics, can expose users to exploits.
Falsified publication information: Malicious actors could include false metadata — such as the title, author, and publisher — in an eBraille publication to trick unsuspecting users into believing they are reading material from a trustworthy source. This could, for example, lead users to be more trusting of external links than they otherwise would be.

Risk mitigation

The following recommendations from EPUB 3 [[epub-33]] apply equally to [=eBraille publications=]:

Avoid links to untrustworthy web sites (e.g., that browsers do not recognize as safe).
Use secure connections to external sites and resources (i.e., using the HTTPS protocol).
Avoid embedding content not provided by reputable organizations or individuals.

Web deployment

When making an [=eBraille publication=] available for reading over the web, [=eBraille creators=] MUST ensure that resources are served with the correct MIME media type [[rfc2046]] in their Content-Type headers [[rfc9110]]. File extensions cannot be relied on, as XHTML documents, for example, are only properly processed as XML when the correct media type is set.

eBraille creators MUST also ensure that each directory containing an eBraille publication is configured to serve the primary entry page (index.html) by default for users that access the publications from a web browser.

eBraille Reading Systems

Introduction

As an [=eBraille publication=] represents a subset of an EPUB 3 publication [[epub-33]], an eBraille reading system similarly consists of a subset of features of a full EPUB 3 reading system [[epub-rs-33]].

Similar to EPUB 3, eBraille does not define a uniform set of requirements that all reading systems must meet. Support is instead based on the capabilities of the device. A reading system might not support media overlays, for example, if it does not support audio playback.

As eBraille publications can be deployed unpackaged on the web, users may not even require a dedicated eBraille reading system to read them. A very basic reading experience will be possible directly from a standard web browser, while browser-based reading systems could provide a richer reading experience for reading on the web.

Reading system requirements

General

An [=eBraille reading system=] MUST meet the requirements for EPUB reading systems [[epub-rs-33]], with the following differences:

It MUST NOT support remote resources [[epub-rs-33]].
It MUST NOT resolve [=path-absolute-URL strings=] [[url]].
As remote resources, forms, and scripting are not supported, it MUST NOT allow [=eBraille publications=] to have network access [[epub-rs-33]]. (Note that barring network access should not prevent users from following external hyperlinks [[epub-rs-33]] in a publication.)
It MUST only support [=eBraille content documents=] in the spine. The reading system MAY reject eBraille publications with other formats in the spine or ignore their entries when rendering the publication.
It MUST NOT support form submission [[epub-rs-33]].
It MUST NOT support scripting [[epub-rs-33]].
It is only required to support OCF processing [[epub-33]] if it supports packaged eBraille publications.

Other unsupported features

The following EPUB reading system features [[epub-rs-33]] are not supported in the authoring of eBraille publications. Unlike the features restricted in , the existence of these features will not affect the rendering of [=eBraille publications=] and does not affect their privacy or security. Reading systems built on EPUB rendering engines MAY support these features although they SHOULD be disabled, if possible, to discourage use by eBraille creators:

manifest fallbacks.
SVG content documents. (Note that this does not affect embedded SVG.)
EPUB 3's prefixed CSS properties.
fixed layouts.
backward compatibility or forward compatibility with other EPUB versions.

eBraille reading systems not built on EPUB rendering engines MUST NOT add support for these features.

Publication types

An eBraille reading system MUST support at least one of packaged eBraille publications or web-hosted eBraille publications, but SHOULD support both deployment methods.

For packaged eBraille publications, reading systems:

SHOULD NOT fail to open a publication solely because the mimetype is missing or not encoded or stored as required.
are not required to assign a unique URL [[epub-rs-33]] to publications because scripting is not supported. It is still RECOMMENDED to domain isolate publications in case scripting is introduced in a future version, however.

If an eBraille reading system supports web access, it SHOULD allow users to download unpackaged eBraille publications hosted on the web by specifying the path to the package document.

Font support

In addition to the general requirements for CSS support in [[epub-rs-33]], Reading devices MUST guarantee that 1ch corresponds with the cell-to-cell distance (i.e., the distance from center to center of corresponding dots in adjacent cells), while 1em should correspond with the line-to-line distance (i.e., the distance from center to center of corresponding dots from one line to the next).

As the use of CSS font properties is not recommended, reading system support for font obfuscation is OPTIONAL.

Media queries

[=eBraille reading systems=] of type braille display MUST match either braille or screen, and SHOULD match both. They SHOULD match both (grid) and not (grid).

[[mediaqueries]] deprecates braille and requires that user agents recognize the media type as valid, but make it match nothing. So maybe we should replace "MUST match either braille or screen, and SHOULD match both" with "SHOULD match screen".

Core media types

eBraille reading systems MUST support PDF for tactile graphics in addition to the core media types requirements in [[epub-rs-33]]. If an eBraille reading system is not capable of rendering PDFs embedded in [=eBraille content documents=], it MUST provide a mechanism that allows the user to open the graphics in an application that supports PDF rendering.

Browser-based reading systems

[=eBraille publications=] made available over the web in unpackaged form are expected to provide minimal functionality in web browsers without the need for a dedicated [=eBraille reading system=].

If a browser-based reading system is created for reading unpackaged eBraille publications (e.g., through a web app), it SHOULD provide the same functionality as a dedicated eBraille reading system.

Browser-based reading systems will be inherently less secure than dedicated eBraille reading systems, as it will not likely be possible to disable features such as scripting, forms, and remote resource access. Consequently, a browser-based reading system SHOULD follow all the recommendations for securing publications defined in [[epub-rs-33]].

About this vocabulary

This vocabulary defines metadata properties for describing [=eBraille publications=].

Properties are only added to this vocabulary if suitable equivalents are not already defined in existing vocabularies such as Dublin Core and Schema.org.

Referencing

The base URL for referencing this vocabulary is http://idpf.org/epub/vocab/package/a11y/#

The reserved prefix a11y: [[epub-33]] MUST be used to reference these properties in EPUB 3-compatible package documents.

Property field definitions

The fields in the vocabulary definition tables have the following implicit requirements:

Allowed Values: Specifies the REQUIRED type of value using [[xmlschema-2]] datatypes.
Description: Describes the purpose of the property and specifies any additional usage requirements.
Example: Provides non-normative usage examples.
Name: Specifies the name of the property as it MUST appear in metadata.

Bibliographic properties

completeTranscription

Definition of the `completeTranscription` property
Name:	`completeTranscription`
Description:	Identifies whether the original work being transcribed is fully represented in the braille rendition, minus any minor omissions such as illustrations without captions or other material that is not ordinarily transcribed.
Allowed value(s):	`true` \| `false`
Example:	<meta property="a11y:completeTranscription">true</meta>

producer

Definition of the `producer` property
Name:	`producer`
Description:	Identifies the name of the organization(s) that produced the braille publication.
Allowed value(s):	`xsd:string`
Example:	<meta property="a11y:producer">APH</meta>

Content properties

cellType

Definition of the `cellType` property
Name:	`cellType`
Description:	Identifies whether 6- or 8-dot braille cell characters are used in the text or, when both are present, which is the more commonly used.
Allowed value(s):	`6` \| `8` \| `6, 8` \| `8, 6`
Example:	<meta property="a11y:cellType">6</meta>

graphicType

Definition of the `graphicType` property
Name:	`graphicType`
Description:	Identifies the format(s) of any tactile graphics included in the work. The value is a comma-separated list containing one or more of the values `JPG`, `PNG`, `SVG`, and `PDF`. When multiple formats are included, order them from most- to least-used. Required when `tactileGraphics` has the value `true`.
Allowed value(s):	`JPG` \| `PDF` \| `PNG` \| `SVG`
Example:	<meta property="a11y:graphicType">SVG</meta>

minimumCells

Definition of the `minimumCells` property
Name:	`minimumCells`
Description:	Identifies the minimum number of cells per line required to accurately display the material within the transcription. For example, if a single graphic in the file requires at least 10 cells of space and so the minimum for this file would be 10 cells. Reading systems should attempt to display the content regardless of the value of this property.
Allowed value(s):	`xsd:unsignedInt`
Example:	<meta property="a11y:minimumCells">10</meta>

minimumLines

Definition of the `minimumLines` property
Name:	`minimumLines`
Description:	Identifies the minimum number of lines per page required to accurately display the material within the transcription. For single- and multi-line braille displays, the concept of a page refers to the total number of lines that the hardware can accommodate without refreshing.
Allowed value(s):	`xsd:unsignedInt`
Example:	<meta property="a11y:minimumLines">5</meta>

sourcePublisher

Definition of the `sourcePublisher` property
Name:	`sourcePublisher`
Description:	Identifies the name of the publisher of the work being transcribed.
Allowed value(s):	`xsd:string`
Example:	<meta property="a11y:sourcePublisher">HarperCollins</meta>

tactileGraphics

Definition of the `tactileGraphics` property
Name:	`tactileGraphics`
Description:	Identifies whether tactile graphics are present in the work.
Allowed value(s):	`true` \| `false`
Example:	<meta property="a11y:tactileGraphics">true</meta>

The `application/ebrl+zip` media type

This appendix registers the media type application/ebrl+zip for the eBraille implementation of the EPUB Open Container Format (OCF).

The OCF ZIP container file is based on the zip archive format (see https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT). It is used to encapsulate an eBraille publication.

MIME media type name:

application

MIME subtype name:

ebrl+zip

Required parameters:

None.

Optional parameters:

None.

Encoding considerations:

OCF ZIP container files are binary files encoded in the application/zip media type.

Security considerations:

All processors that read OCF ZIP container files should rigorously check the size and validity of data retrieved.

In addition, because of the various content types that can be embedded in OCF ZIP container files, application/ebrl+zip may describe content that poses security implications beyond those noted here. However, only in cases where the processor recognizes and processes the additional content, or where further processing of that content is dispatched to other processors, would security issues potentially arise. In such cases, matters of security would fall outside the domain of this registration document.

Security considerations that apply to application/zip also apply to OCF ZIP container files.

Interoperability considerations:

None.

Published specification:

This media type registration is for the eBraille implementation of the EPUB Open Container Format (OCF), as described by the eBraille specification located at https://www.daisy.org/s/eBraille.

Applications that use this media type:

This media type is in use for the distribution of braille documents in the eBraille format.

Additional information:

Magic number(s):: 0: PK 0x03 0x04
File extension(s):: eBraille container files are identified with the extension .ebrl.
Macintosh file type code(s):: ZIP

Person & email address to contact for further information:

eBraille Working Group (ebraille@daisylists.org)

Intended usage:

COMMON

Author/change controller:

DAISY Consortium

Changes since the First Public Working Draft

29-Aug-2024: Added media type registration for eBraille container.
08-Aug-2024: Updated the names in the dc:creator element examples and added explanation and examples of using the file-as property to provide sorting info. Refer to issue 218.
08-Aug-2024: Fixed the definition of whitespace characters allowed in content documents to refer to the XML definition as Form Feed is not valid in XHTML. Refer to issue 238.

Introduction

Overview

Relationship to EPUB 3

Future directions

Terminology

Authoring shorthands

eBraille publication conformance

Publication resources

Introduction

Core media types

Foreign resources

Resource fallbacks

Resource location

Exempt resources

File extensions

XML conformance

eBraille file set

Introduction

File and directory structure

File paths and file names

URLs in the file set

Multiple renditions

Package Document

Introduction

The package element

Metadata

About package document metadata

Metadata elements

Metadata values

Using prefixes

General requirements

Required metadata

dc:creator

dc:format

dc:identifier

dc:language

dc:title

dcterms:dateCopyrighted

dcterms:modified

a11y:cellType

a11y:code

a11y:completeTranscription

a11y:created

a11y:producer

a11y:sourcePublisher

a11y:tactileGraphics

Recommended metadata

dc:publisher

dc:description

dc:rights

dc:source

dc:subject

dcterms:educationLevel

Additional metadata

Examples

Manifest

Spine

Unsupported features

eBraille content documents

Introduction

XHTML

Character encoding

Unsupported features

Cascading Style Sheets (CSS)

Introduction

CSS requirements

Media queries

Authoring best practices

Layout rendering control

Primary entry page

Introduction

General requirements

Navigation

Table of contents

Page list

Landmarks

Media overlays

Accessibility

Packaging

Security and privacy

The `package` element

The `application/ebrl+zip` media type