Added JSON Schema for catalogs feed / catalog-entry

[danielweck]

This JSON Schema ships in r2-streamer-js and has been tested with:

• http://libraries.aldiko.com/home.json
• https://libraryregistry.librarysimplified.org/libraries

[danielweck]

https://libraryregistry.librarysimplified.org/libraries

=>

http://readium2.herokuapp.com/opds-v2-browse/https%3A%2F%2Flibraryregistry.librarysimplified.org%2Flibraries

(scroll to the bottom of the page to see the JSON Schema validation errors, which are due to mailto: URI-references)

[danielweck]

http://libraries.aldiko.com/home.json

=>

http://readium2.herokuapp.com/opds-v2-browse/http%3A%2F%2Flibraries.aldiko.com%2Fhome.json

...for example click on the "france" __href__ link:

https://libraries.aldiko.com/countries/france.json

=>

http://readium2.herokuapp.com/opds-v2-browse/https%3A%2F%2Flibraries.aldiko.com%2Fcountries%2Ffrance.json

(no JSON Schema errors)

[danielweck]

Note that Thorium does not support "catalogs" feeds yet, I filed an issue: edrlab/thorium-reader#1336

[danielweck]

I have just also fixed validation errors as per AJV, see: https://github.com/ajv-validator/ajv/releases/tag/v7.0.0

[HadrienGardeur]

I think that we really need to publish a draft or a technical note before we can merge that work in our core schema for OPDS 2.0.

@leonardr thoughts?

We already have an issue for that question BTW #19

[leonardr]

I can write up a description of the collections role similar to the descriptions of other roles in the core spec. Is there anything about the collections role that would require a change in the core spec? I remember some debate about this but I don't remember the conclusion.

[llemeurfr]

@HadrienGardeur @leonardr would it be possible to finalize the spec relative to this new collections role, so that we can safely develop the feature in Thorium Reader?

[leonardr]

Here's a formal writeup to motivate discussion. This is very close to my current server implementation but not exactly the same (we'll be changing this soon so that won't be a problem for us).

First, a summary of the catalogs role designed to fit in the table in section 1.

Role	Semantics	Compact?	Required?	Reference
catalogs	Describes and links to OPDS catalogs	No	No	TBD

Second, a more detailed description that could, e.g. become section 1.6 of the OPDS 2.0 spec:

Catalogs

A catalogs collection allows one OPDS catalog to describe and link to other OPDS catalogs.

Each catalog listed in a catalogs collection MUST be represented as a collection, with the following additional constraints:

• It MUST contain a title in its metadata.
• It MUST contain a reference to itself using a self link in links. The type of this link SHOULD indicate that it is either an OPDS 2.0 Catalog Feed (application/opds+json) or an OPDS 1 feed (application/atom+xml;profile=opds-catalog) .
• It SHOULD contain an images subcollection, as defined in section 1.3 of OPDS 2.0. These images represent the catalog itself, e.g. a library or corporate logo.
• It SHOULD contain a reference to an Authentication For OPDS document, using a link in links with a type of application/vnd.opds.authentication.v1.0+json.

No subcollections are required for a catalog in a catalogs collection: not readingOrder (as is required by Readium Web Publication Manifest), nor any of navigation, publication, or groups (as is required by OPDS 2.0 Catalog Feed), nor images (as suggested in this section).

Example

{ 
  "metadata": { 
    "title": "Example OPDS feed that uses the 'catalogs' collection role" 
  },

  "links": [
    {
      "rel": "self",
      "href": "http://example.com/opds",
      "type": "application/opds+json"
    }
  ],

  "catalogs": [
    {
      "metadata": {
        "title": "Alice's Bookstore",
       },
       "links": [
          {"rel": "self", "href": "https://bookstore.alice/books.opds", "type": "application/opds+json"},
          {"href": "https://bookstore.alice/authentication", "type": "application/vnd.opds.authentication.v1.0+json"}
       },
       "images": [
            {"href="https://bookstore.alice/logo.png", "type": "image/png"}
        ]
    },
    {
      "metadata": {
        "title": "Bobville Public Library",
       },
       "links": [
          {"rel": "self", "href": "https://library.bob/catalog/", "type": "application/atom+xml;profile=opds-catalog;kind=navigation"},
          {"href": "https://library.bob/catalog/authentication.opds", "type": "application/vnd.opds.authentication.v1.0+json"}
       },
       "image": {"href="https://images.library.bob/logo.gif", "type": "image/gif"}
    }
  ]
}

[leonardr]

I have two specific questions:

1. Do people want this to be in the core OPDS 2.0 spec? If so, I'll put up a PR for it. If not, I'll rewrite this as a standalone technical note and put up a PR for that.

2. This sentence in the Overview isn't compatible with reasonable usage of the catalogs role:

"it MUST contain at least one collection identified by the following roles: navigation, publications or groups"

If catalogs goes into the core 2.0 spec, there's no problem; we just add catalogs to that list. But if it's a separate technical note, the only way to generate a valid OPDS 2.0 feed that uses catalogs is to also include a redundant, empty collection using one of the required roles.

[leonardr]

I went through the JSON Schema and updated my proposed writeup to bring the two into sync.

Notably, I wrote an English definition of image, which I take to be analogous to the images collection. In my implementation we're putting images into links, using the IANA icon link relation, but it's no problem for us to change this.

I have one concern about image: what's the rationale for giving a catalog a single image rather than using a subcollection with the images role? We define the images role for publications "to support responsive images across all types of devices". Presumably the same reasoning would apply to the image associated with a catalog.

I also want to make explicit that the changes in JSON Schema imply that catalogs will make its way into the core OPDS 2.0 spec. So I'm leaning towards putting up a PR based on this branch which also modifies the English-language spec.

[llemeurfr]

We'll implement this catalogs structure in Thorium, for a specific use case (first): importing a set of feeds at runtime (see #274).
Therefore please decide if image is singular or plural, as we imagine using the image of the feed in a future evolution of Thorium's UI. Therefore implementing the feed parsing correctly is desirable.

[leonardr]

Coming back to this, I'm going to unilaterally say that image doesn't make sense when we already have images.

I've updated my proposed spec changes to refer to the images subcollection defined in 1.3 instead of defining a new image item. This is how we at NYPL will implement the catalogs subcollection.

[danielweck]

Ha ha!
I was following this discussion but I have just remembered that this is in fact my PR :)

Where can I find the latest specification proposal, so I can update my PR's JSON Schema? Or are you creating your own? At any rate, I will update my copies in the micro validation service which I maintain for testing purposes.

http://libraries.aldiko.com/home.json
=>
http://readium2.herokuapp.com/opds-v2-browse/http%3A%2F%2Flibraries.aldiko.com%2Fhome.json

https://libraryregistry.librarysimplified.org/libraries
=>
http://readium2.herokuapp.com/opds-v2-browse/http%3A%2F%2Flibraries.aldiko.com%2Fhome.json

Do you know of any other URLs which we could use for testing?

PS: Thorium merely checks for the presence of the catalogs JSON property for "duck typing" purposes, but currently does not implement any significant support for catalogs / registries yet.

edrlab/thorium-reader#1336

edrlab/thorium-reader#274 (comment)

CC @panaC