npm package: @nypl/opds
Description: OPDS Typescript Models
Author: NYPL
Latest version: 0.1.0-alpha.0

# About

This package has both OPDS 1 and OPDS 2 types. The OPDS 1 types are mainly a collection of link relation constants and some JSON that is specific to the Library Simplified Circulation Manager - not formally part of OPDS. The OPDS 2 types are newer and actually represent real OPDS 2 spec.

In the future, this package is not a place to put PJR or Library Simplified specific types, but should conform to the official OPDS spec. The only exception is with profiles we have defined ourselves, such as the [PDF profile](./opds2/profiles/pdf/README.md) and the [Work profile](./opds2/profiles/work/README.md). In the future, we would like to find a better place to define PJR-specific constants such as link relations and media types.

# OPDS 2 Types

The OPDS 2 Typescript type definitions are build to match the [OPDS 2.0 Draft Spec](https://drafts.opds.io/opds-2.0). It is primarily based on the JSON schemas stored in the Readium Github:

- [OPDS 2.0 Draft Schema](https://github.com/opds-community/drafts/tree/master/schema)
- [Readium Webpub Manifest Schema](https://github.com/readium/webpub-manifest/tree/master)

The OPDS 2.0 spec is based on the same model as the Readium Webpub Manifest, but extends it to allow an OPDS document to represent a Feed or a Publication. The primary difference between a Webpub Manifest and a Publication is that a Webpub Manifest must have a `readingOrder`: the reasources needed to read the publication need to be listed directly in the manifest. A Publication represents a more abstract concept, and might not be directly readable. Thus it doesn't need the `readingOrder`.

## Extensions & Modules

The OPDS 2.0 and Webpub Manifest spec allow for extensions. An extension specifies additional metadata, link properties and collection roles that a Publication or Feed can have. To use an extension, the Publication should declare that it conforms to a profile using the `metadata.conformsTo` property. We have implemented the following profiles:

1. [Epub Profile](https://github.com/readium/webpub-manifest/blob/master/profiles/epub.md) - use the `OPDS2.EpubWebpubManifest` type to represent a webpub that conforms to the Epub profile.
1. [Encryption module](https://github.com/readium/webpub-manifest/blob/master/modules/encryption.md) - any resource can be declared as encrypted. You don't need to declare conformance with a profile. I'm not exactly sure what the difference between a module and an extension is meant to be in the spec, but there is no way to specify that the module is used, so it's allowed on all resources.

# Not implemented

We have not implemented the following profiles yet:

- [Presentation hints module](https://github.com/readium/webpub-manifest/blob/master/modules/presentation.md) - both the EPUB profile and this module allow the addition of presentation hints, sometimes in a conflicting way. This [Github discussion](https://github.com/readium/webpub-manifest/discussions/94) indicates that the presentation hints module will likely be deprecated or renamed to be Divina-specific. Thus, we don't plan to implement it at the moment.
- Audiobook profile - we will implement when we get there.

## Other future improvements

1. Improve the range of media types defined. We can fill this in as needed.
1. Figure out a way to add LibrarySimplified and future Project R specific types on top of the base OPDS2 types. For example, LibrarySimplified defines an additional "revoke" role for an acquisition link.