search

opds-community / drafts

Contains all the current drafts for the OPDS specifications
36 stars 10 forks source link

Added JSON Schema for catalogs feed / catalog-entry #38

Open danielweck opened 3 years ago

danielweck commented 3 years ago

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

danielweck commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

Note that Thorium does not support "catalogs" feeds yet, I filed an issue: https://github.com/edrlab/thorium-reader/issues/1336

danielweck commented 3 years ago

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

HadrienGardeur commented 3 years ago

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 https://github.com/opds-community/drafts/issues/19

leonardr commented 3 years ago

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 commented 3 years ago

@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 commented 3 years ago

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:

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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.

https://github.com/edrlab/thorium-reader/issues/1336

https://github.com/edrlab/thorium-reader/issues/274#issuecomment-856954435

CC @panaC