Requirements for validation in OPDS 1.1

[Hadrien Gardeur]

Hello,

I've extracted all the MUST / MUST NOT / SHOULD / SHOULD NOT of the current specification that are not covered by the Relax NG.

This is not a complete list (for SHOULD & SHOULD NOT) as I've only compiled requirements that we might use in our validation tools.

There is one major inconsistency as far as I can see:

• Links to OPDS Catalog Entry Document Resources MUST use a type attribute of "application/atom+xml;type=entry;profile=opds-catalog" 
  Links to OPDS Catalog Feed Document Resources MUST use a type attribute of "application/atom+xml;profile=opds-catalog"
• Links to Navigation Feeds SHOULD use the "type" attribute "application/atom+xml;profile=opds-catalog;kind=navigation"
  Links to Acquisition Feeds SHOULD use the "type" attribute "application/atom+xml;profile=opds-catalog;kind=acquisition"

I'm not sure if this should be a strong requirement (MUST) or a weak one (SHOULD).

I'll update this thread with a list of the most important requirements that should have priority over the rest in our validation tools.

MUST

Every OPDS Catalog Feed Document MUST either be an Acquisition Feed or a Navigation Feed.
Every OPDS Catalog MUST have one and only one OPDS Catalog Root.
Links using the "http://opds-spec.org/facet" relation MUST only appear in Acquisition Feeds.
An OPDS Catalog MAY provide a search facility through an [OpenSearch]description document. Links to [OpenSearch] description documents MUST use the "search" relation value and the "application/opensearchdescription+xml" media type
Each OPDS Catalog Entry Document MUST include at least one Acquisition Link
Any OPDS Catalog Entry without a link to a Complete Catalog Entry MUST include all metadata elements.
A Partial Catalog Entry MUST include an "alternate" link relation referencing the Complete Catalog Entry Resource and that atom:link MUST use the "type" attribute "application/atom+xml;type=entry;profile=opds-catalog".
An "atom:summary" element in an OPDS Catalog Entry MUST use a "type" attribute of "text"
The image Resources MUST be in GIF, JPEG, or PNG format.
All Acquisition Links MUST include a "type" attribute that advises clients on the media type of the representation that is expected to be returned when the value of the href attribute is dereferenced. 
This representation is called a Complete Acquisition Feed and each OPDS Catalog Entry MUST be ordered by atom:updated, with the most recently updated Atom Entries coming first in the document order
A Complete Acquisition Feed MUST include a fh:complete element from[RFC5005] unless pagination is required
OPDS Catalog providers MUST include Complete Catalog Entries when serializing a Complete Acquisition Feed
Links to OPDS Catalog Entry Document Resources MUST use a type attribute of "application/atom+xml;type=entry;profile=opds-catalog". 
Links to OPDS Catalog Feed Document Resources MUST use a type attribute of "application/atom+xml;profile=opds-catalog".
At a minimum, client and server implementations MUST be capable of being configured to use HTTP Basic Authentication [RFC2617] in conjunction with a connection made with TLS 1.0 [RFC2246] or a subsequent standards-track version of TLS supporting the conventions for using HTTP over TLS

MUST NOT

A Navigation Feed MUST NOT contain OPDS Catalog Entries but instead contains Atom Entries that link to other Navigation or Acquisition Feeds or other Resources. 
A Facet MUST NOT appear in more than a single group
In a group of Facets, an OPDS Catalog provider MUST NOT mark more than one Facet as active
One or more "dc:identifier" elements SHOULD be used to identify the represented Publication, if appropriate metadata is available, and MUST NOT identify the OPDS Catalog Entry.
A "dc:issued" element SHOULD be used to indicate the first publication date of the Publication and MUST NOT represent any date related to the OPDS Catalog Entry.
OPDS Catalog Entries MUST include an "atom:title" representing the Publication's title and MUST NOT use "dc:title"
Following Atom [RFC4287] Section 4.2.6, the content of an "atom:id" identifying an OPDS Catalog Entry MUST NOT change when the OPDS Catalog Entry is "relocated, migrated, syndicated, republished, exported, or imported" and "MUST be created in a way that assures uniqueness."
An "atom:summary" element in an OPDS Catalog Entry MUST use a "type" attribute of "text" and the content MUST NOT contain child elements
Clients MUST NOT assume that an OPDS Catalog Entry returned in the Acquisition Feed is a full representation of an OPDS Catalog Entry Resource, as described in the Section Partial and Complete Entries.

SHOULD / SHOULD NOT

Each OPDS Catalog Feed Document SHOULD contain an atom:link element with a link relation of "start", which references the OPDS Catalog Root Resource.
Links to Navigation Feeds SHOULD use the "type" attribute "application/atom+xml;profile=opds-catalog;kind=navigation"
Links to Acquisition Feeds SHOULD use the "type" attribute "application/atom+xml;profile=opds-catalog;kind=acquisition".
The OPDS Catalog provider SHOULD indicate that a Facet is active using the "opds:activeFacet" attribute set to "true".
In an [OpenSearch] description document, the search interface SHOULD use the media type associated to OPDS Catalogs
OPDS Catalog Feed Documents SHOULD contain one atom:link element with a "rel" attribute value of "self".
One or more "dc:identifier" elements SHOULD be used to identify the represented Publication, if appropriate metadata is available
A "dc:issued" element SHOULD be used to indicate the first publication date of the Publication 
OPDS Catalog Entries SHOULD use "atom:author" to represent the Publication's creators and SHOULD NOT use "dc:creator"
OPDS Catalog Entries SHOULD use "atom:category" to represent the Publication's category, keywords, key phrases, or classification codes and SHOULD NOT use "dc:subject".
OPDS Catalog Entries SHOULD include either "atom:summary" or "atom:content" elements or both to provide a description, summary, abstract, or excerpt of the Publication
The content of an "atom:summary" element SHOULD NOT duplicate the content of "atom:title" or "atom:content"
If an OPDS Catalog Entry includes both "atom:content" and "atom:summary", the "atom:content" SHOULD NOT be included in the Partial Catalog Entry. Both elements SHOULD be included in the Complete Catalog Entry.
Image resources related by http://opds-spec.org/image/thumbnail SHOULD be suitable for presentation at a small size
The atom:links with these relations SHOULD include at least one link with a type attribute of "image/gif", "image/jpeg", or "image/png"
OPDS Catalog providers SHOULD use a compressed Content-Encoding when transmitting Complete Acquisition Feeds over HTTP. See Section 14.11 of[RFC2616] for more on compression.
Publishers of OPDS Catalogs SHOULD use the "type" parameter to help clients distinguish between relations to OPDS Catalog Entries and OPDS Catalog Feeds.
Relations to OPDS Catalog Feed Document and OPDS Catalog Entry Document Resources SHOULD use a "profile" parameter following Section 4.3 of[RFC4288] with the value "opds-catalog"

Hadrien

[Hadrien Gardeur]

And here are the key requirements (I've rephrased them this time) for the opcoming OPDS validation tools:

Very high priority

A feed can't be a navigation & acquisition feed at the same time

Each catalog entry must have a link (pretty much the same thing than the previous requirement based on how we define an acquisition feed)

Each acquisition link must have a type

Search links must use the rel search and OpenSearch mimetype (many issues with pre-OPDS catalogs on that one)

High priority

Linked image resources must be a bitmap

Catalogs should use the right rel for images (OPDS 1.0+ vs OPDS 0.9 or pre-OPDS)

atom:summary must be plain text

Check for dc elements usages that should only be represented with Atom (dc:creator, dc:title, dc:subject)

Normal priority

atom:content shouldn't duplicate atom:title & atom:summary

Check for the presence of a link to a single catalog root

Presence of "profile" and "kind" parameters

Low priority

Requirements for facets

Requirements for complete feeds

Very low priority

Support for Basic Auth over SSL

Support for compression

Hope that helps everyone, not just with validation tools, but also whenever you're trying to build a catalog...

Hadrien