ONIX Metadata

Other techniques for implementing EPUB accessibility metadata are available: Display Techniques for Displaying Accessibility Metadata

This document provides techniques for meeting the guidelines of the User Experience Guide for Displaying Accessibility Metadata. It provides practical examples for extracting information from the ONIX metadata for showing it to the end users.

ONIX messages describe products for the global book supply chain and will be sent from publisher or creator of the epub or digital books with full audio to those who will make the products available for sale, lending or subscription. These platforms may not yet have the actual files, as they may not yet be ready, or may only choose to list them for sale if they have certain accessibility features. ONIX also only describes a product, it cannot describe the features of the reading systems on which a product may be accessed. It is important to use ONIX metadata as a complement to the accessibility data embedded within the publication itself, if describing accessible books, books with full audio and related products for the global book supply chain. An ONIX file can be used to display accessibility information in advance of publication or when you do not have access to the metadata in the digital file itself. Some accessibility information may only be available when you have access to the file itself. If you are unfamiliar with ONIX, then there is more documentation available from EDItEUR.org.

It is important to note that ONIX 3.0 includes a number of new accessibility metadata codes, some of which may not be expressible in earlier versions of ONIX.

ONIX record examples

ONIX record describing an EPUB

Here is an example of an ONIX record (version 3.0), which will be used as a reference point for the following examples on EPUB accessibility metadata: the results of the XPath shown are based on this example.

ONIX record describing an audiobook

Here is an example of an ONIX record (version 3.0) for describing an audiobook, which will be used as a reference point for the some of the following examples on EPUB accessibility metadata: the results of the XPath shown are based on this example.

Conventions for implementations

The code conventions used in the provided code snippet follow a structure commonly found in programming languages like Python, Java, or C++. Here's an explanation of the conventions:

Conditionals and Control Flow:
IF, ELSE IF, and ELSE (in bold and capital letters) statements are used to define different conditions and the corresponding actions to be taken.
Operators:
Written operators (is present) are used to check if a particular code or codelist is present (or not) in the metadata record.
Logical operators:
Logical operators (AND, OR, NOT, in bold and capital letters) are used to combine conditions.
String Literals:
String literals are used to represent the text that should be displayed when a particular condition is met.
Variable Naming:
The terms like "codelist" and "code" are used in a way that suggests a variable or data structure representing a code or codelist to be accessed directly after the ingestion of the metadata record.
Indentation:
The code uses consistent indentation to define blocks of code within conditional statements. This is crucial for readability and maintaining a clear structure.
Readability:
The code is written in a way that is intended to be easily readable and understandable even by non-coders.

Common Functions

In this section we define the functions common to all techniques, which are called by them during execution.

Pre Processing

Before working directly with the metadata we must read the ONIX record. This is a common starting point for all techniques that allows us to query the record directly.

This algorithm takes the onix_record_as_text argument: a UTF-8 string representing the ONIX record.

To generate the internal representation, run the following steps:

  1. LET record be textual representation of the ONIX record for the publication given onix_record_as_text.
  2. LET onix be the DOM tree that results from parsing record using an XML DOM parser.
  3. Return onix.

Check for Node

Many of the techniques rely on checking for the presence or absence of metadata in the ONIX record.

This algorithm takes:

To check for node, run the following steps:

  1. IF onix contains path: THEN return True.
  2. ELSE return False.

Techniques

Supports nonvisual reading

This technique relates to Supports nonvisual reading key information.

This algorithm takes the onix_record_as_text argument: a UTF-8 string representing the ONIX record.

Understanding the variables

all_necessary_content_textual

If true it indicates that the code 52 of codelist 196 (All non-decorative content supports reading without sight) is present in the ONIX record, otherwise if false it means that the metadata is not present.

All non-decorative content supports reading without sight means that all contents of the digital publication necessary to use and understanding, including text, images (via their alternative descriptions), audio and video material (via their transcripts, descriptions, captions or subtitles) are fully accessible via suitable reading devices, for example text-to-speech screen readers or tactile reading devices (‘Braille displays’), and nothing in the digital publication prevents or blocks the use of alternative reading modes. The entire publication can be navigated and ‘read’ using only text rendered via sound or touch, and does not require visual perception.

real_text

If true it indicates that the code 10 of codelist 81 (Text) is present in the ONIX record, otherwise if false it means that the metadata is not present.

Text means that digital publication contains "real" text (user-selectable) as its main content (or as secondary content).

non_textual_content_still

If true it indicates that at least one of the following is present in the ONIX record:

This means that the content contains images of any type.

textual_alternative_still

If true it indicates that at least one of the following is present in the ONIX record:

This means that there are textual alternatives for images.

Variables setup

  1. LET onix be the result of calling pre processing given onix_record_as_text.
  2. LET all_necessary_content_textual be the result of calling check for node on onix, /ONIXMessage/Product/DescriptiveDetail/ProductFormFeature[ProductFormFeatureType = "09" and ProductFormFeatureValue = "52"].
  3. LET real_text be the result of calling check for node on onix, /ONIXMessage/Product/DescriptiveDetail/PrimaryContentType[text() = "10"] OR the result of calling check for node on onix, /ONIXMessage/Product/DescriptiveDetail/ProductContentType[text() = "10"].
  4. LET non_textual_content_still be the result of calling check for node on onix, /ONIXMessage/Product/DescriptiveDetail/PrimaryContentType[text() = "07" or text() = "18" or text() = "19" or text() = "12" or text() = "49" or text() = "20"] OR the result of calling check for node on onix, /ONIXMessage/Product/DescriptiveDetail/ProductContentType[text() = "07" or text() = "18" or text() = "19" or text() = "12" or text() = "49" or text() = "20"].
  5. LET textual_alternative_still be the result of calling check for node on onix, /ONIXMessage/Product/DescriptiveDetail/ProductFormFeature[ProductFormFeatureType = "09" and (ProductFormFeatureValue = "14" or ProductFormFeatureValue = "15" or ProductFormFeatureValue = "16")].

Instructions

  1. IF all_necessary_content_textual: THEN display "Readable in read aloud and braille".
  2. ELSE IF real_text AND non_textual_content_still AND NOT textual_alternative_still: THEN display "Not fully readable in read aloud and braille".
  3. ELSE display "May not be fully readable in read aloud and braille".

Visual adjustments

This technique relates to Visual adjustments key information.

This algorithm takes the onix_record_as_text argument: a UTF-8 string representing the ONIX record.

Understanding the variables

all_textual_content_can_be_modified

If true it indicates that the code 36 of codelist 196 (All textual content can be modified) is present in the ONIX record, otherwise if false it means that the metadata is not present.

All textual content can be modified means that the digital publication does not restrict the ability of users to modify and reflow the display of any textual content to the full extent allowed by the reading system (i.e. to change the text size or typeface, line height and word spacing, colors).

is_fixed_layout

If true it indicates that the code E201 of codelist 175 (Fixed format) is present in the ONIX record, otherwise if false it means that the metadata is not present.

Fixed format means that digital publication is in fixed format (e.g. EPUB Fixed Layout).

Variables setup

  1. LET onix be the result of calling pre processing given onix_record_as_text.
  2. LET all_textual_content_can_be_modified be the result of calling check for node on onix, /ONIXMessage/Product/DescriptiveDetail/ProductFormFeature[ProductFormFeatureType = "09" and ProductFormFeatureValue = "36"].
  3. LET is_fixed_layout be the result of calling check for node on onix, /ONIXMessage/Product/DescriptiveDetail/ProductFormDetail[text() = "E201"] AND NOT the result of calling check for node on onix, /ONIXMessage/Product/DescriptiveDetail/ProductFormDetail[text() = "E200"].

Instructions

  1. IF all_textual_content_can_be_modified: THEN display "Appearance can be modified".
  2. ELSE IF is_fixed_layout: THEN display "Appearance cannot be modified".
  3. ELSE display "Appearance modifiability not known".

Conformance

This technique relates to Conformance key information.

Pre-recorded audio

This technique relates to Pre-recorded audio key information.

Charts, diagrams, and formulas

This technique relates to Charts, diagrams, and formulas key information.

This algorithm takes the onix_record_as_text argument: a UTF-8 string representing the ONIX record.

Understanding the variables

contains_charts_diagrams

If true it indicates that the code 19 of codelist 81 (Figures, diagrams, charts, graphs) is present in the ONIX record, otherwise if false it means that the metadata is not present.

This means that there is a positive indication that the product has some information conveyed via some form of illustration, such as a graph, a chart, a diagram, a figure, etc).

charts_diagrams_as_non_graphical_data

If true it indicates that the code 16 of codelist 196 (Visualised data also available as non-graphical datas) is present in the ONIX record, otherwise if false it means that the metadata is not present.

This means that there is a positive indication that all data presented in a visual format (graph, chart, etc) has an alternative non-graphical presentation of the same data.

charts_diagrams_diagrams_as_long_text

If true it indicates that the code 15 of codelist 196 (Full alternative textual description) is present in the ONIX record, otherwise if false it means that the metadata is not present.

This means that there is a positive indication that a full alternative textual description has been supplied for all of the graphs, charts, diagrams, or figures necessary to understand the content.

contains_chemical_formula

If true it indicates that the code 47 of codelist 81 (Chemical content) is present in the ONIX record, otherwise if false it means that the metadata is not present.

This means that there is a positive indication that the publication contains chemical notations, formulae.

chemical_formula_as_chemml

If true it indicates that the code 18 of codelist 196 (Accessible chemistry content as ChemML) is present in the ONIX record, otherwise if false it means that the metadata is not present.

This means that there is a positive indication that the chemical formulae are presented using ChemML and works with compatible assistive technology.

contains_math_formula

If true it indicates that the code 48 of codelist 81 (Mathematical content) is present in the ONIX record, otherwise if false it means that the metadata is not present.

This means that there is a positive indication that the publication contains mathematical notation, equations, formulae.

math_formula_as_latex

If true it indicates that the code 35 of codelist 196 (Accessible math content as LaTeX) is present in the ONIX record, otherwise if false it means that the metadata is not present.

This means that there is a positive indication that the chemical formulae are presented using LaTeX and works with compatible assistive technology.

math_formula_as_mathml

If true it indicates that the code 17 of codelist 196 (Accessible math content as MathML) is present in the ONIX record, otherwise if false it means that the metadata is not present.

This means that there is a positive indication that all mathematical content is presented using MathML and works with compatible assistive technology.

Variables setup

  1. LET onix be the result of calling pre processing given onix_record_as_text.
  2. LET contains_charts_diagrams be the result of calling check for node on onix, /ONIXMessage/Product/DescriptiveDetail/DescriptiveDetail[PrimaryContentType = "19" or ContentType = "19"] .
  3. LET charts_diagrams_as_non_graphical_data be the result of calling check for node on onix, /ONIXMessage/Product/DescriptiveDetail/ProductFormFeature[ProductFormFeatureType = "09" and ProductFormFeatureValue = "16"].
  4. LET charts_diagrams_diagrams_as_long_text be the result of calling check for node on onix, /ONIXMessage/Product/DescriptiveDetail/ProductFormFeature[ProductFormFeatureType = "09" and ProductFormFeatureValue = "15"].
  5. LET contains_chemical_formula be the result of calling check for node on onix, /ONIXMessage/Product/DescriptiveDetail/DescriptiveDetail[PrimaryContentType = "47" or ContentType = "47"] .
  6. LET chemical_formula_as_chemml be the result of calling check for node on onix, /ONIXMessage/Product/DescriptiveDetail/ProductFormFeature[ProductFormFeatureType = "09" and ProductFormFeatureValue = "18"].
  7. LET chemical_formula_as_mathml be the result of calling check for node on onix, /ONIXMessage/Product/DescriptiveDetail/ProductFormFeature[ProductFormFeatureType = "09" and ProductFormFeatureValue = "34"].
  8. LET contains_math_formula be the result of calling check for node on onix, /ONIXMessage/Product/DescriptiveDetail/DescriptiveDetail[PrimaryContentType = "48" or ContentType = "48"] .
  9. LET math_formula_as_latex be the result of calling check for node on onix, /ONIXMessage/Product/DescriptiveDetail/ProductFormFeature[ProductFormFeatureType = "09" and ProductFormFeatureValue = "35"].
  10. LET math_formula_as_mathml be the result of calling check for node on onix, /ONIXMessage/Product/DescriptiveDetail/ProductFormFeature[ProductFormFeatureType = "09" and ProductFormFeatureValue = "17"].

Instructions

  1. IF contains_charts_diagrams AND charts_diagrams_diagrams_as_long_text: THEN display "Charts and diagrams have extended descriptions".
  2. IF contains_charts_diagrams AND charts_diagrams_as_non_graphical_data: THEN display "Visualised data also available as non-graphical data".
  3. IF contains_chemical_formula AND (chemical_formula_as_chemml OR chemical_formula_as_mathml): THEN display "Accessible chemistry content".
  4. IF contains_math_formula AND (math_formula_as_latex OR math_formula_as_mathml): THEN display "Accessible math content".
  5. IF (contains_charts_diagrams OR contains_chemical_formula OR contains_math_formula) AND NOT (charts_diagrams_diagrams_as_long_text OR charts_diagrams_as_non_graphical_data OR chemical_formula_as_chemml OR chemical_formula_as_mathml OR math_formula_as_latex OR math_formula_as_mathml): THEN display "Accessibility of formulas, charts, and diagrams unknown".

Hazards

This technique relates to Hazards key information.

This algorithm takes the onix_record_as_text argument: a UTF-8 string representing the ONIX record.

Understanding the variables

no_hazards_or_warnings_confirmed

If true it indicates that the code 00 of codelist 143 (No known hazards or warnings) is present in the ONIX record, otherwise if false it means that the metadata is not present.

This means there is a positive indication in the ONIX record confirming there are no associated hazard warnings with this product.

flashing_hazard

If true it indicates that the code 13 of codelist 143 (WARNING - Flashing hazard) is present in the ONIX record, otherwise if false it means that the metadata is not present.

This means that there is a positive indication that the product has a flashing hazard which must be displayed.

no_flashing_hazards

If true it indicates that the code 14 of codelist 143 (No flashing hazard warning necessary) is present in the ONIX record, otherwise if false it means that the metadata is not present.

This means there is a positive indication in the ONIX record confirming there are no flashing hazards associated with this product.

motion_simulation_hazard

If true it indicates that the code 17 of codelist 143 (WARNING - Motion simulation hazard) is present in the ONIX record, otherwise if false it means that the metadata is not present.

This means that there is a positive indication that the product has a motion simulation hazard which must be displayed.

no_motion_hazards

If true it indicates that the code 18 of codelist 143 (No motion simulation hazard warning necessary) is present in the ONIX record, otherwise if false it means that the metadata is not present.

This means there is a positive indication in the ONIX record confirming there are no motion simulation hazards associated with this product.

sound_hazard

If true it indicates that the code 15 of codelist 143 (WARNING - Sound hazard) is present in the ONIX record, otherwise if false it means that the metadata is not present.

This means that there is a positive indication that the product has a sound hazard which must be displayed.

no_sound_hazards

If true it indicates that the code 16 of codelist 143 (No sound hazard warning necessary) is present in the ONIX record, otherwise if false it means that the metadata is not present.

This means there is a positive indication in the ONIX record confirming there are no sound hazards associated with this product.

unknown_if_contains_hazards

If true it indicates that the code 08 of codelist 196 (Unknown accessibility) is present in the ONIX record, otherwise if false it means that the metadata is not present.

This means that the product has not been assessed for hazards and there is no information about potential hazards.

Variables setup

  1. LET onix be the result of calling pre processing given onix_record_as_text.
  2. LET no_hazards_or_warnings_confirmed be the result of calling check for node on onix, /ONIXMessage/Product/DescriptiveDetail/ProductFormFeature[ProductFormFeatureType = "12" and ProductFormFeatureValue = "00"].
  3. LET flashing_hazard be the result of calling check for node on onix, /ONIXMessage/Product/DescriptiveDetail/ProductFormFeature[ProductFormFeatureType = "12" and ProductFormFeatureValue = "13"].
  4. LET no_flashing_hazards be the result of calling check for node on onix, /ONIXMessage/Product/DescriptiveDetail/ProductFormFeature[ProductFormFeatureType = "12" and ProductFormFeatureValue = "14"].
  5. LET motion_simulation_hazard be the result of calling check for node on onix, /ONIXMessage/Product/DescriptiveDetail/ProductFormFeature[ProductFormFeatureType = "12" and ProductFormFeatureValue = "17"].
  6. LET no_motion_hazards be the result of calling check for node on onix, /ONIXMessage/Product/DescriptiveDetail/ProductFormFeature[ProductFormFeatureType = "12" and ProductFormFeatureValue = "18"].
  7. LET sound_hazard be the result of calling check for node on onix, /ONIXMessage/Product/DescriptiveDetail/ProductFormFeature[ProductFormFeatureType = "12" and ProductFormFeatureValue = "15"].
  8. LET no_sound_hazards be the result of calling check for node on onix, /ONIXMessage/Product/DescriptiveDetail/ProductFormFeature[ProductFormFeatureType = "12" and ProductFormFeatureValue = "16"].
  9. LET unknown_if_contains_hazards be the result of calling check for node on onix, /ONIXMessage/Product/DescriptiveDetail/ProductFormFeature[ProductFormFeatureType = "09" and ProductFormFeatureValue = "08"].

Instructions

  1. IF no_hazards_or_warnings_confirmed OR (no_flashing_hazards AND no_motion_hazards AND no_sound_hazards): THEN display "No hazards".
  2. ELSE IF flashing_hazard OR motion_simulation_hazard OR sound_hazard: THEN LET hazards be an empty array.
    1. IF flashing_hazard: THEN APPEND "flashing" to hazards.
    2. IF motion_simulation_hazard: THEN APPEND "motion" to hazards.
    3. IF sound_hazard: THEN APPEND "sound" to hazards.
    4. LET hazards_string be the result of:
      • calling join on hazards with the separator ", "
      • making uppercase the first character
      • replacing the last occurence of ", " with " and "
      • concatenating " hazards" to the end of the string IF (length of hazards) > 1 ELSE concatenating " hazard" to the end of the string.
    5. display hazards_string.
  3. ELSE IF unknown_if_contains_hazards: THEN display "The presence of hazards is unknown".
  4. ELSE display "No information about possible hazards".

    This key information can be hidden if metadata is missing.

Accessibility summary

This technique relates to Accessibility summary key information.

Additional accessibility information

This technique relates to Additional accessibility information key information.

Acknowledgements

Contributors

Reviewers