I · 04

Anatomy of an OpenURL

An OpenURL is an ordinary HTTP URL whose query string carries a structured citation. This page takes one apart, piece by piece.

Every OpenURL has the same coarse shape: a base URL identifying a link resolver, followed by a query string carrying the citation in Key/Encoded-Value (KEV) form. The query string follows the rules of Z39.88-2004; the URL itself is an ordinary HTTP(S) URL.

The example

Below is a complete OpenURL describing the Einstein, Podolsky and Rosen paper of 1935, with both a DOI and descriptive Referent metadata. Line breaks are added for readability; in transmission the URL is one continuous string.

https://resolver.example.edu/openurl?
url_ver=Z39.88-2004
&ctx_ver=Z39.88-2004
&rft_val_fmt=info:ofi/fmt:kev:mtx:journal
&rfr_id=info:sid/example.com:database
&rft_id=info:doi/10.1103/PhysRev.47.777
&rft.genre=article
&rft.atitle=Can+Quantum-Mechanical+Description+of+Physical+Reality+Be+Considered+Complete%3F
&rft.jtitle=Physical+Review
&rft.aulast=Einstein
&rft.aufirst=A.
&rft.au=Podolsky%2C+B.
&rft.au=Rosen%2C+N.
&rft.date=1935
&rft.volume=47
&rft.issue=10
&rft.spage=777
&rft.epage=780

Base URL

Everything to the left of the ? is the base URL: scheme, host and path of the resolver that will process the request. Each institution publishes its own; services such as Google Scholar's Library Links, Zotero and discovery systems are configured with it. The base URL is not defined by Z39.88-2004. See How to find your library's OpenURL resolver.

Query-string anatomy

Transport keys (`url_`)

url_ver=Z39.88-2004 is the OpenURL "signature" defined by Part 4 of the standard; it is required by all three OpenURL transports. Optional url_tim gives the creation time and url_ctx_fmt=info:ofi/fmt:kev:mtx:ctx declares the ContextObject format. Many real-world OpenURLs omit url_ver, and most resolvers tolerate that.

Administrative keys (`ctx_`)

ctx_ver=Z39.88-2004 declares the ContextObject version. Other administrative keys are ctx_enc (character encoding; UTF-8 is the default, info:ofi/enc:UTF-8), ctx_id (an identifier for the ContextObject) and ctx_tim (a timestamp). All are formally optional in the KEV ContextObject Format, but ctx_ver is almost always sent.

Format identifier

rft_val_fmt=info:ofi/fmt:kev:mtx:journal names the metadata format used for the rft. keys. It must be present whenever rft.* keys are. The formats used for scholarly linking are journal, book, dissertation and patent; see The OpenURL Registry for the full list.

Referent descriptors

Every key beginning rft. is a metadata field of the Referent, the item being requested. The names after the dot come from the format named in rft_val_fmt; for journals they include atitle, jtitle, aulast, volume, issue and spage. See Journal Format (KEV).

Identifiers

rft_id=info:doi/10.1103/PhysRev.47.777 identifies the Referent by URI. Identifiers and descriptive metadata may both be present, and rft_id may repeat (for example a DOI and a PubMed ID for the same article). See Identifiers.

Source identification

rfr_id=info:sid/example.com:database identifies the Referrer, the system that generated the OpenURL. An info:sid identifier is an Internet domain name associated with the source, optionally followed by a colon and a sub-identifier such as a database name. See Referrer (rfr).

Keys are plain; values are URL-encoded

Keys start with a letter or digit and contain only letters, digits, underscores and dots, so they never need encoding. Values must be URL-encoded. Appendix E of the standard spells out the procedure:

Letters, digits and the characters . - * _ stay as they are.
A space becomes + or %20.
Every other character is converted to UTF-8 bytes and each byte written as %XY. Strictly, that includes : and / inside values such as info:doi/….
Repeatable fields such as rft.au are sent as repeated pairs, not joined into one value.

In practice many sources leave : and / unencoded and resolvers accept both forms. A decoder should accept + and %20 for spaces and must never treat an encoded %26 as a pair separator.