Parse EPUB and RWPM accessibility metadata (#235)

Author: mickael-menu

CHANGELOG.md

@@ -10,12 +10,17 @@ All notable changes to this project will be documented in this file. Take a look
 
 #### Shared
 
+* Support for the accessibility metadata in RWPM per [Schema.org Accessibility Properties for Discoverability Vocabulary](https://www.w3.org/2021/a11y-discov-vocab/latest/).
 * [Extract the raw content (text, images, etc.) of a publication](Documentation/Guides/Content.md).
 
 #### Navigator
 
 * [A brand new text-to-speech implementation](Documentation/Guides/TTS.md).
 
+#### Streamer
+
+* Parse EPUB accessibility metadata ([see documentation](https://readium.org/architecture/streamer/parser/a11y-metadata-parsing)).
+
 ### Deprecated
 
 #### Shared

Sources/Shared/Publication/Accessibility.swift

@@ -28,6 +28,7 @@ public struct Metadata: Hashable, Loggable, WarningLogger {
     public let localizedSubtitle: LocalizedString?
     public var subtitle: String? { localizedSubtitle?.string }
 
+    public let accessibility: Accessibility?
     public let modified: Date?
     public let published: Date?
     public let languages: [String]  // BCP 47 tag
@@ -70,6 +71,7 @@ public struct Metadata: Hashable, Loggable, WarningLogger {
         conformsTo: [Publication.Profile] = [],
         title: LocalizedStringConvertible,
         subtitle: LocalizedStringConvertible? = nil,
+        accessibility: Accessibility? = nil,
         modified: Date? = nil,
         published: Date? = nil,
         languages: [String] = [],
@@ -102,6 +104,7 @@ public struct Metadata: Hashable, Loggable, WarningLogger {
         self.conformsTo = conformsTo
         self.localizedTitle = title.localizedString
         self.localizedSubtitle = subtitle?.localizedString
+        self.accessibility = accessibility
         self.modified = modified
         self.published = published
         self.languages = languages
@@ -151,6 +154,7 @@ public struct Metadata: Hashable, Loggable, WarningLogger {
             .map { Publication.Profile($0) }
         self.localizedTitle = title
         self.localizedSubtitle = try? LocalizedString(json: json.pop("subtitle"), warnings: warnings)
+        self.accessibility = try? Accessibility(json: json.pop("accessibility"), warnings: warnings)
         self.modified = parseDate(json.pop("modified"))
         self.published = parseDate(json.pop("published"))
         self.languages = parseArray(json.pop("language"), allowingSingle: true)
@@ -187,6 +191,7 @@ public struct Metadata: Hashable, Loggable, WarningLogger {
             "conformsTo": encodeIfNotEmpty(conformsTo.map { $0.uri }),
             "title": localizedTitle.json,
             "subtitle": encodeIfNotNil(localizedSubtitle?.json),
+            "accessibility": encodeIfNotEmpty(accessibility?.json),
             "modified": encodeIfNotNil(modified?.iso8601),
             "published": encodeIfNotNil(published?.iso8601),
             "language": encodeIfNotEmpty(languages),
@@ -255,6 +260,7 @@ public struct Metadata: Hashable, Loggable, WarningLogger {
         conformsTo: [Publication.Profile]? = nil,
         title: LocalizedStringConvertible? = nil,
         subtitle: LocalizedStringConvertible?? = nil,
+        accessibility: Accessibility?? = nil,
         modified: Date?? = nil,
         published: Date?? = nil,
         languages: [String]? = nil,
@@ -288,6 +294,7 @@ public struct Metadata: Hashable, Loggable, WarningLogger {
             conformsTo: conformsTo ?? self.conformsTo,
             title: title ?? self.localizedTitle,
             subtitle: subtitle ?? self.localizedSubtitle,
+            accessibility: accessibility ?? self.accessibility,
             modified: modified ?? self.modified,
             published: published ?? self.published,
             languages: languages ?? self.languages,

Sources/Shared/Publication/Metadata.swift

@@ -52,6 +52,7 @@ final class EPUBMetadataParser: Loggable {
             conformsTo: [.epub],
             title: mainTitle ?? fallbackTitle,
             subtitle: subtitle,
+            accessibility: accessibility(),
             modified: modifiedDate,
             published: publishedDate,
             languages: languages,
@@ -189,6 +190,101 @@ final class EPUBMetadataParser: Loggable {
     private lazy var mainTitle: LocalizedString? = localizedString(for: mainTitleElement)
 
     private lazy var subtitle: LocalizedString? = localizedString(for: titleElements(ofType: .subtitle).first)
+    
+    /// https://readium.org/architecture/streamer/parser/a11y-metadata-parsing
+    private func accessibility() -> Accessibility? {
+        let accessibility: Accessibility? = Accessibility(
+            conformsTo: accessibilityProfiles(),
+            certification: accessibilityCertification(),
+            summary: metas["accessibilitySummary", in: .schema].first?.content,
+            accessModes: accessibilityAccessModes(),
+            accessModesSufficient: accessibilityAccessModesSufficient(),
+            features: accessibilityFeatures(),
+            hazards: accessibilityHazards()
+        )
+        
+        return accessibility.takeIf { $0 != Accessibility() }
+    }
+    
+    private func accessibilityProfiles() -> [Accessibility.Profile] {
+        metas["conformsTo", in: .dcterms]
+            .compactMap { accessibilityProfile(from: $0.content) }
+    }
+    
+    private func accessibilityProfile(from value: String) -> Accessibility.Profile? {
+        switch value {
+        case "EPUB Accessibility 1.1 - WCAG 2.0 Level A",
+            "http://idpf.org/epub/a11y/accessibility-20170105.html#wcag-a",
+            "http://www.idpf.org/epub/a11y/accessibility-20170105.html#wcag-a",
+            "https://idpf.org/epub/a11y/accessibility-20170105.html#wcag-a",
+            "https://www.idpf.org/epub/a11y/accessibility-20170105.html#wcag-a":
+            return .epubA11y10WCAG20A
+            
+        case "EPUB Accessibility 1.1 - WCAG 2.0 Level AA",
+            "http://idpf.org/epub/a11y/accessibility-20170105.html#wcag-aa",
+            "http://www.idpf.org/epub/a11y/accessibility-20170105.html#wcag-aa",
+            "https://idpf.org/epub/a11y/accessibility-20170105.html#wcag-aa",
+            "https://www.idpf.org/epub/a11y/accessibility-20170105.html#wcag-aa":
+            return .epubA11y10WCAG20AA
+            
+        case "EPUB Accessibility 1.1 - WCAG 2.0 Level AAA",
+            "http://idpf.org/epub/a11y/accessibility-20170105.html#wcag-aaa",
+            "http://www.idpf.org/epub/a11y/accessibility-20170105.html#wcag-aaa",
+            "https://idpf.org/epub/a11y/accessibility-20170105.html#wcag-aaa",
+            "https://www.idpf.org/epub/a11y/accessibility-20170105.html#wcag-aaa":
+            return .epubA11y10WCAG20AAA
+        default:
+            return nil
+        }
+    }
+    
+    private func accessibilityCertification() -> Accessibility.Certification? {
+        let certifier = metas["certifiedBy", in: .a11y].first
+        let credential: String?
+        let report: String?
+        if let id = certifier?.id {
+            credential = metas["certifierCredential", in: .a11y, refining: id].first?.content
+            report = metas.links(withRel: "certifierReport", in: .a11y, refining: id).first?.href
+        } else {
+            credential = metas["certifierCredential", in: .a11y].first?.content
+            report = metas["certifierReport", in: .a11y].first?.content
+                ?? metas.links(withRel: "certifierReport", in: .a11y).first?.href
+        }
+        guard certifier != nil || credential != nil || report != nil else {
+            return nil
+        }
+        
+        return Accessibility.Certification(
+            certifiedBy: certifier?.content,
+            credential: credential,
+            report: report
+        )
+    }
+    
+    private func accessibilityAccessModes() -> [Accessibility.AccessMode] {
+        metas["accessMode", in: .schema]
+            .map { Accessibility.AccessMode($0.content) }
+    }
+    
+    private func accessibilityAccessModesSufficient() -> [[Accessibility.PrimaryAccessMode]] {
+        metas["accessModeSufficient", in: .schema]
+            .map {
+                $0.content.split(separator: ",")
+                    .map { $0.trimmingCharacters(in: .whitespacesAndNewlines) }
+                    .filter { !$0.isEmpty }
+                    .compactMap(Accessibility.PrimaryAccessMode.init(rawValue:))
+            }
+    }
+    
+    private func accessibilityFeatures() -> [Accessibility.Feature] {
+        metas["accessibilityFeature", in: .schema]
+            .map { Accessibility.Feature($0.content) }
+    }
+    
+    private func accessibilityHazards() -> [Accessibility.Hazard] {
+        metas["accessibilityHazard", in: .schema]
+            .map { Accessibility.Hazard($0.content) }
+    }
 
     /// Parse and return the Epub unique identifier.
     /// https://github.com/readium/architecture/blob/master/streamer/parser/metadata.md#identifier

Sources/Streamer/Parser/EPUB/EPUBMetadataParser.swift

@@ -128,7 +128,6 @@ enum OPFVocabulary: String {
 
 }
 
-
 /// Represents a `meta` tag in an OPF document.
 struct OPFMeta {
     let property: String
@@ -141,11 +140,22 @@ struct OPFMeta {
     let element: Fuzi.XMLElement
 }
 
+/// Represents a `link` tag in an OPF document.
+struct OPFLink {
+    let rel: String
+    /// URI of the rel's vocabulary.
+    let vocabularyURI: String
+    let href: String
+    /// ID of the metadata that is refined by this one, if any.
+    let refines: String?
+    let element: Fuzi.XMLElement
+}
 
 struct OPFMetaList {
 
     private let document: Fuzi.XMLDocument
     private let metas: [OPFMeta]
+    private let links: [OPFLink]
 
     init(document: Fuzi.XMLDocument) {
         self.document = document
@@ -155,7 +165,8 @@ struct OPFMetaList {
 
         // Parses `<meta>` and `<dc:x>` tags in order of appearance.
         let root = "/opf:package/opf:metadata"
-        self.metas = document.xpath("\(root)/opf:meta|\(root)/dc:*|\(root)/opf:dc-metadata/dc:*|\(root)/opf:x-metadata/opf:meta")
+        self.metas = document
+            .xpath("\(root)/opf:meta|\(root)/dc:*|\(root)/opf:dc-metadata/dc:*|\(root)/opf:x-metadata/opf:meta")
             .compactMap { meta in
                 if meta.tag == "meta" {
                     // EPUB 3
@@ -195,6 +206,29 @@ struct OPFMetaList {
                     )
                 }
             }
+        
+        self.links = document
+            .xpath("\(root)/opf:link")
+            .compactMap { link in
+                guard
+                    let originalRel = link.attr("rel"),
+                    let href = link.attr("href")
+                else {
+                    return nil
+                }
+                
+                let (rel, vocabularyURI) = OPFVocabulary.parse(property: originalRel, prefixes: prefixes)
+                        
+                var refinedID = link.attr("refines")
+                refinedID?.removeFirst()  // Get rid of the # before the ID.
+                return OPFLink(
+                    rel: rel,
+                    vocabularyURI: vocabularyURI,
+                    href: href,
+                    refines: refinedID,
+                    element: link
+                )
+            }
     }
 
     subscript(_ property: String) -> [OPFMeta] {
@@ -213,6 +247,14 @@ struct OPFMetaList {
         return metas.filter { $0.property == property && $0.vocabularyURI == vocabulary.uri && $0.refines == id }
     }
 
+    func links(withRel rel: String, in vocabulary: OPFVocabulary) -> [OPFLink] {
+        links.filter { $0.rel == rel && $0.vocabularyURI == vocabulary.uri }
+    }
+    
+    func links(withRel rel: String, in vocabulary: OPFVocabulary, refining id: String) -> [OPFLink] {
+        links.filter { $0.rel == rel && $0.vocabularyURI == vocabulary.uri && $0.refines == id }
+    }
+    
     /// Returns the JSON representation of the unknown metadata
     /// (for RWPM's `Metadata.otherMetadata`)
     var otherMetadata: [String: Any] {
@@ -262,14 +304,19 @@ struct OPFMetaList {
     /// List of properties that should not be added to `otherMetadata` because they are already
     /// consumed by the RWPM model.
     private let rwpmProperties: [OPFVocabulary: [String]] = [
+        .a11y: ["certifiedBy", "certifierCredential", "certifierReport"],
         .defaultMetadata: ["cover"],
         .dcterms: [
-            "contributor", "creator", "date", "description", "identifier", "language", "modified",
-            "publisher", "subject", "title"
+            "contributor", "creator", "date", "description", "identifier",
+            "language", "modified", "publisher", "subject", "title",
+            "conformsTo"
         ],
         .media: ["duration"],
         .rendition: ["flow", "layout", "orientation", "spread"],
-        .schema: ["numberOfPages"]
+        .schema: [
+            "numberOfPages", "accessMode", "accessModeSufficient",
+            "accessibilitySummary", "accessibilityFeature", "accessibilityHazard"
+        ]
     ]
 
     /// Returns whether the given meta is a known RWPM property, and should therefore be ignored in