Copyright © DAISY Consortium 2023
This specification defines eBraille, a digital reading format for braille publications.
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.
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. But users are not locked into the default display. With the display flexibility of CSS, and standardized markup practices, they could 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.
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 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.
An individual, organization, or process that produces an [=eBraille publication=].
The set of files that comprise an [=eBraille publication=]. The eBraille file set is contained within the [=publication root=].
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.
A system that processes [=eBraille publications=] for presentation to a user in a manner conformant with this specification.
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.
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]]. An [=eBraille publication=] will be easy to package in an EPUB container when needed, however.
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:
A conforming [=eBraille publication=]:
MUST define at least one rendering of its content as follows:
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.
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.
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, 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, so foreign resources cannot be used in the spine. Similarly, foreign image formats have to include fallbacks 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 EPUB creators, but using the [[html]] [^object^] element's intrinsic fallback capabilities can avoid having to duplicate the image in a core media type format.
[=eBraille publications=] only support [=XHTML content documents=] in the [=spine=] [[epub-33]]. Consequently, the use of manifest fallbacks [[epub-33]] is not supported.
The intrinsic fallback methods provided by [[html]] elements are supported.
[=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]].
Note that 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).
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. It has no effect on documents served over the web,
however.
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.
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.
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:
index.htmlpackage.opfThere 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.
eBraille file paths and file names MUST adhere to the file naming restrictions specified in section 4.2.3 of [[epub-33]].
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.
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, only the default
rendition [[epub-multi-rend-11]] (i.e., one listed first in the container.xml file
[[epub-33]]) is subject to the file naming and location
requirements for the package document and primary entry page.
The default rendition MUST be a braille rendition (i.e., identified by a rendition:accessMode attribute
with the value "tactile" [[epub-multi-rend-11]]).
[[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.
eBraille uses the EPUB 3 package document [[epub-33]] to express information about an [=eBraille publication=].
The package document contains three primary sections:
metadata element contains
bibliographic and rendering information about an eBraille publication.manifest element contains a list of
all the publication resources.spine element contains the default ordering
of eBraille content documents.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 — manifest fallbacks and legacy element are not allowed, for example.
The eBraille package document metadata MUST meet all the requirements for [[epub-33]] metadata.
In particular, EPUB requires that all eBraille publications include a unique identifier, the title of the publication, the language of the content, and the last modification date.
[=eBraille publications=] additionally MUST include the following metadata:
eBraille publications SHOULD include the following metadata:
How to specify required and recommended metadata will be provided in a future update to this document.
The package document manifest element contains a list all of the resources in the
[=eBraille publication=]. Each item element child defines one resource, minimally
providing the following information:
id attribute;href attribute; andmedia-type attribute.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.
The manifest entries for [=eBraille content documents=] may also indicate if a media overlay document is available in the media-overlays attribute.
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.
The package document spine element 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.
The linear attribute is used to indicate if a resource referenced from the spine
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).
For the complete set of requirements for the spine, refer to the The spine element in [[epub-33]].
The following features of the EPUB 3 package document are not supported in eBraille so MUST NOT be used:
[=eBraille content documents=] define the markup and presentation of the content of an [=eBraille publication=]. An eBraille content document is encoded using XML syntax of [[html]], also commonly known as XHTML, and is styled using CSS [[css2]].
eBraille content documents are not only 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.
An [=eBraille content document=]:
eBraille does not support scripted interactivity or form submissions. Consequently, authors 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.
The requirements for using CSS to style [=eBraille content documents=] are defined in CSS requirements [[epub-33]] but with the following differences:
-epub-
prefixed properties [[epub-33]].More specific guidance on how to use CSS properties in eBraille content documents is provided in the eBraille Styling Best Practices.
eBraille does not support fixed layouts as defined in [[epub-33]]. Consequently, [=eBraille publications=]:
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]].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 the 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 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 seq elements into logical structures such
as figures and tables.
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]].
[=eBraille publications=] fall under the category of optimized publications as defined by the EPUB Accessibility specification [[epub-a11y-11]]. eBraille publications are only meant for braille users, so it is not expected that [=eBraille creators=] can produce them to fully meet the requirements of W3C's Web Content Accessibility Guidelines [[wcag22]]. There is not always a benefit to braille users in meeting all of that standards requirements.
At the same time, it is possible to create eBraille publications that fail to meet the needs of users if care is not taken to optimize the content. Not properly identifying headings, for example, will limit users' ability to navigate a publication quickly. Similarly, failing to mark up tables properly can make them difficult to navigate and understand.
So although fully meeting WCAG conformance may not be possible, eBraille SHOULD meet all success criteria applicable to eBraille reading and include all relevant accessibility metadata [[epub-a11y-11]] in the package document.
A packaged eBraille file set MUST use the extension .ebrl.
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 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.
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.
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 lead users to be more trusting of external links than they otherwise would be.
The following recommendations from EPUB 3 [[epub-33]] apply equally to [=eBraille publications=]:
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.
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 always require a dedicated eBraille reading system to read them. A very basic reading experience will be possible directly from a standard web browser, and browser-based reading systems can provide a richer reading experience for reading on the web.
An [=eBraille reading system=] MUST meet the requirements for EPUB reading systems [[epub-rs-33]], with the following differences:
spine. The reading
system MAY reject eBraille publications with other formats in the spine or ignore their entries
when rendering the publication.In addition, eBraille reading systems MUST support PDF for tactile graphics. 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.
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.
[=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]].