English
Norsk Dansk English
Norsk Dansk English

Principles

View as Markdown The page’s .md file Open in ChatGPT Ask questions about the page Open in Claude Ask questions about the page

The decisions the specification is built on, and the principles the initiative is developed by — one statement and one reason per principle.

Last updated

PLAS is a specification, and most of its principles are stated in it. The first section repeats them as they stand in Provider API v0.6.5. The second section is the initiative’s principles — how Redia has proposed the standard be developed. The two don’t belong in the same place, so they are kept apart.

The specification

This is what Provider API v0.6.5 settles for anyone implementing or calling it.

  1. The library system implements, the product calls. The Provider API is the interface a library system exposes, so vendors of library products meet the same interface regardless of the system behind it. That is the whole purpose of the specification.

  2. The version is sent along, and an unknown version is an error. The client can send version on nearly every operation; if the provider doesn’t support that version, it responds with error code 600. A version mismatch becomes an error you can act on, not a missing field.

  3. One authentication pattern. OAuth 2.0 with client credentials against POST /authentication/oauth2/token; the token goes as Bearer in the Authorization header, and 401 means it is missing, invalid or expired. The token is recommended to be a JWT, so a third party can validate it without asking the provider.

  4. The provider decides who is calling. The spec describes two ways to tell customer and vendor apart: a base URL per library, or credentials that carry both. The choice is the provider’s — which is why the spec has no servers block, and the base URL is agreed with the provider.

  5. No HTML in responses. A response never contains HTML-formatted data unless the operation explicitly says so. The client must be able to show the content in its own interface without sanitising it first.

  6. One format for time. Points in time are RFC 3339 date-time with a capital T and an explicit time zone — the spec assumes none. Plain dates are YYYY-MM-DD. No exceptions, so no client has to guess.

  7. Parameters are URL-encoded. All URL and query parameters are expected to be encoded at request time; an id containing a comma in a comma-separated list becomes %2C.

  8. Known ids are answered, unknown ids are left out. When the client looks up a list of ids, the known ones appear in the response and the unknown ones don’t; if all are unknown, the response is an empty map. A lookup doesn’t fail because one id is wrong.

  9. Patron ids are UUIDs, and patron login is protected. The spec recommends a UUID as patronId (an integer id gets a UUID alongside it, and only that is used in PLAS) and rate limiting per patron identifier on POST /patron/authentication and POST /patron/authentication/no-password.

  10. The specification is still a work in progress. The spec says so itself: fields and structure may change. That is why the version is stated on every page here, and why the version table separates in production from in specification.

The initiative

This is Redia’s proposal for how PLAS is developed. The standard belongs to the sector, so these principles hold for as long as the sector adopts them.

  1. Access is standardised — not the systems. The sources stay different; it is the way in that becomes the same. A library doesn’t have to change systems to benefit from the standard.

  2. Machine-readable first. The interface is described in OpenAPI, so tools can generate clients and tests directly from the specification — and so the documentation here can be generated from the same file.

  3. Versioned, so a library can set requirements. The standard has releases. A library can write a specific version into a tender, and a vendor can say exactly what is supported.

  4. Domain by domain, at its own pace. Search, bibliographic data, holdings, patron data, circulation, interlibrary loans, digital media and shared services are each described on their own. A library system implements them when it makes sense, and the library can see what is supported.

  5. Open documentation, open process. The specification, its releases and the process for new proposals are in the open — that is what this site is for.

  6. Needs before timeline. The standard starts with the most important shared functions and grows with the needs of libraries and vendors, not according to a plan set in advance.

  7. The sector’s standard, not one vendor’s. Libraries contribute needs, system vendors implement and shape, data providers make their data available, and developers build on top and propose improvements. Redia proposed PLAS; the standard gets strong when many use it.

When a principle changes

The principles in the first section change only when the specification does — and this page then follows the version in production. The principles in the second section are the initiative’s and change in dialogue with the sector, not on this page.

Next steps