Copyright © DAISY Consortium 2023
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.
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.
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.
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:
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.
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]] |
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. 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.
eBraille does not support the use of manifest fallbacks [[epub-33]].
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]].
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. The extension 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.
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]].
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, 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:
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.
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 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=].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.
package elementAt 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.
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 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.
meta elementThe 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).
link elementThe 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]].
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.
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.
The prefixes a11y: and dcterms: are reserved prefixes in EPUB
3. They do not have to be declared to use the associated required and recommended
metadata properties in this specification.
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.
For more information about using prefixes in the package document, refer to Vocabulary association mechanisms [[epub-33]].
The eBraille package document metadata:
The REQUIRED dc:creator element [[dcterms]] identifies the name(s) of the
primary author, editor, etc. Follow regional conventions for name layout.
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.
To provide the creator's name for sorting purposes, associate a file-as property [[epub-33]] with the
element.
For more information, refer to the definition of
the dc:creator element in [[epub-33]].
The REQUIRED dc:date element [[dcterms]] defines the publication date of the
[=eBraille publication=].
It is RECOMMENDED that the date string conform to [[iso8601]], particularly the subset expressed in W3C Date and Time Formats [[datetime]].
The element MAY include the following attributes: dir, id, xml:lang [[epub-33]].
Only one dc:date element is allowed in the package document metadata.
The publication date is not the same as the last modification date, which is the last time the publication was changed.
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".
The element MAY include an id attribute
[[epub-33]].
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.
The dc:identifier element is not used to identify the source work being
transcribed. Use the dc:source element for the
source work's identifier(s).
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.
For more information, refer to the definition
of the dc:identifier element in [[epub-33]].
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.
When specified, a country code subtag MUST refer to the language of the work being transcribed.
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.
For more information, refer to the definition
of the dc:language element in [[epub-33]].
The REQUIRED dc:title element [[dcterms]] identifies the title of the source
material.
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]].
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
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.
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]].
The REQUIRED a11y:brailleSystem property identifies the name of the braille
system an [=eBraille publication=] has been formatted in conformance with.
The property is defined in a meta tag with its
property attribute set to a11y:brailleSystem.
The [=value=] SHOULD be a value from the eBraille Braille Codes Registry [[code-registry]].
If only some contractions are used, specify the code twice — both as contracted and uncontracted. Put whichever code is most common first.
For multiple braille codes, codes should be listed in descending order from most to least utilized within that file.
The REQUIRED a11y:cellType property identifies whether the text of the
[=eBraille publication=] is encoded using 6- or 8-dot braille characters.
The property is defined in a meta tag with its
property attribute set to a11y:cellType.
The [=value=] MUST be 6 or 8, with 6 for 6-dot braille
characters and 8 for 8-dot braille characters.
If both 6- and 8-dot braille characters are used in the same file, use a comma to separate the values, with the one used most often listed first.
Only one instance of this property is allowed.
The REQUIRED a11y:completeTranscription indicates whether the complete original
work has been transcribed of not.
The property is defined in a meta tag with its
property attribute set to a11y:completeTranscription.
The [=value=] MUST be true if complete and false if not complete.
Completeness is determined by 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.
Only one instance of this property is allowed.
The a11y:dateTranscribed property identifies the date the transcription was
created.
The property is defined in a meta tag with its
property attribute set to a11y:dateTranscribed.
The [=value=] SHOULD be an [[iso8601-1]] conformant date of the form YYYY-MM-DD.
If the full date is unknown, the month and year (YYYY-MM) or year
(YYYY) MAY be specified instead.
Only one instance of this property is allowed.
The a11y:producer property identifies the name(s) of the organization(s) or
individual(s) that produced the braille publication.
The property is defined in a meta tag with its
property attribute set to a11y:producer.
The a11y:producer and dc:publisher MAY identify the same
organization or individual, but they do not have to. The producer is responsible for
creating an eBraille publication, while the publisher may have only commissioned the work
from a producer.
Repeat the property for each organization or individual.
The a11y:tactileGraphics property identifies whether an [=eBraille publication=]
contains tactile graphics.
The property is defined in a meta tag with its
property attribute set to a11y:tactileGraphics.
The element's [=value=] is true if tactile graphics are present and
false if not.
If tactile graphics are present, the a11y:graphicType property MUST also be
set.
If more than one type of tactile graphics is used, list the formats in order of most used to least used.
Only one instance of this property is allowed.
The RECOMMENDED dc:publisher element identifies the name(s) of the
organization(s) or individual(s) that published the [=eBraille publication=].
The element MAY include the following attributes: dir, id, xml:lang [[epub-33]].
Repeat the property for each organization or individual.
The RECOMMENDED dc:description element provides an abstract, a table of
contents, or a free-text account of the resource.
The element MAY include the following attributes: dir, id, xml:lang [[epub-33]].
Only one instance of this element is allowed.
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.
The element MAY include the following attributes: dir, id, xml:lang [[epub-33]].
Repeat the element to include more than one rights statement.
When an [=eBraille publication=] is a transcription of another work, it is RECOMMENDED that
the source be identified in a dc:source element.
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]].
It is also RECOMMENDED to specify the publisher of the source work. Use a
dcterms:publisher property with a refines attribute that
references the dc:source element.
If not transcribing a published print work, the name of the organization or individual that produced the original text MAY be used as the publisher.
It is also RECOMMENDED to specify the date of publication of the source work. Use a
dcterms:date property with a refines attribute that references
the dc:source element.
It is RECOMMENDED that the date string conform to [[iso8601]], particularly the subset expressed in W3C Date and Time Formats [[datetime]].
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.
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.
Repeat the element for each subject.
For more information, refer to the definition of
the dc:subject element in [[epub-33]]
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.
Repeat the element if the publication is intended for more than one education level.
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, including metadata properties in the Accessible Formats Metadata Vocabulary that are not listed as required or recommended in the preceding sections.
Properties from other vocabularies are also allowed provided a prefix [[epub-33]] is defined.
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:
id
attribute [[epub-33]];href
attribute [[epub-33]]; andmedia-type attribute [[epub-33]].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-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.
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]].
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).
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 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.
An [=eBraille content document=] MUST be an XHTML content document as defined [[epub-33]] with additional constraints as defined in the following subsections.
[=eBraille content documents=] are expected 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:
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 restriction also applies to CSS styling that would generate non-braille characters (e.g.,
list styling for numbers, letters, and glyphs, and the use of the content property
to dynamically add text before or after elements). Reading systems are not expected to convert
such styling to braille characters.
This restriction does not prevent the use of CSS to insert braille characters.
The 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.
When authoring [[html]] ordered ([^ol^]) and unordered ([^ul^]) lists, [=eBraille creators=]
SHOULD embed the list number, letter, or glyph within each item (e.g., by setting
list-style-type to none to override the default styling). Do not
rely on [=reading systems=] to convert the automatic styling of lists to braille characters.
eBraille creators SHOULD only use CSS for marking list items when the style sheet supplies the
braille characters to display (e.g., by setting list-style-type: '⠿⠲ ' to insert
braille bullets).
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.
[=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:
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.
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]].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 andfont-variant
[[css-fonts]],color [[css-color]],text-decoration,text-shadow
andtext-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.
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.
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 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 par and other 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 standard's 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.
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.
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, for example, 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 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.
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.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:
eBraille reading systems not built on EPUB rendering engines MUST NOT add support for these features.
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:
mimetype is missing or
not encoded or stored as required.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.
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.
[=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".
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.
[=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]].
This vocabulary defines metadata properties for describing any accessible format, but with specific focus on the needs of [=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.
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.
The fields in the vocabulary definition tables have the following implicit requirements:
Specifies the REQUIRED type of value using [[xmlschema-2]] datatypes.
Describes the purpose of the property and specifies any additional usage requirements.
Provides non-normative usage examples.
Specifies the name of the property as it MUST appear in metadata.
| 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> |
| Name: |
dateTranscribed
|
|---|---|
| Description: | Identifies the date the transcription was created. |
| Allowed value(s): |
xsd:string
|
| Example: |
<meta property="a11y:dateTranscribed">2024-03-15</meta> |
| 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> |
| Name: |
brailleSystem
|
|---|---|
| Description: | Identifies the name of the braille system the publication has been formatted in conformance with. |
| Allowed value(s): |
xsd:string
|
| Example: |
<meta property="a11y:brailleSystem">UEB</meta> |
| 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> |
| 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
Required when |
| Allowed value(s): |
JPG | PDF | PNG | SVG
|
| Example: |
<meta property="a11y:graphicType">SVG</meta> |
| 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> |
| 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> |
| Name: |
tactileGraphics
|
|---|---|
| Description: | Identifies whether tactile graphics are present in the work. |
| Allowed value(s): |
true | false
|
| Example: |
<meta property="a11y:tactileGraphics">true</meta> |
application/ebrl+zip media typeThis 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.
application
ebrl+zip
None.
None.
OCF ZIP container files are binary files encoded in the
application/zip media type.
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.
None.
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.
This media type is in use for the distribution of braille documents in the eBraille format.
0: PK 0x03 0x04
eBraille container files are identified with the extension .ebrl.
ZIP
eBraille Working Group (ebraille@daisylists.org)
COMMON
DAISY Consortium
This section identifies substantive changes made to the eBraille specification between drafts. For a list of all changes, refer to the issue tracker.
There have been no substantive changes since the last working draft.
a11y:sourcePublisher and a11y:sourceDate
properties with guidance on using the refines attribute to attach
dcterms:publisher and dcterms:date to the source. Refer to issue 280.dc:identifier is not for the source work's
identifier(s). Refer to issue
171.code to brailleSystem. Refer to issue 195.a11y:created to a11y:dateTranscribed. Refer to
issue 198.a11y:sourcePublisher to the recommended metadata. Refer to issue 221.a11y:sourceDate to the recommended metadata. Refer to issue 200.dc:date as a required element. Refer to issue 263.dc:creator element examples and added
explanation and examples of using the file-as property to provide sorting info.
Refer to issue 218.