Page History

...

You are free to create ARK strings as you wish, provided you use only digits, letters (ASCII, no diacritics), and the following characters:

= ~ * + @ _ $ . /

The last two characters are reserved in the event you wish to disclose ARK relationships.

Another unique feature of ARKs is that hyphens ('-') may appear but are identity inert, meaning that strings that differ only by hyphens are considered identical; for example, these strings

ark:/12345/141e86dc-d396-4e59-bbc2-4c3bf5326152

ark:/12345/141e86dcd3964e59bbc24c3bf5326152

identify the same thing. The reason for this feature is that text formatting processes out in the world routinely introduce extra hyphens into identifiers, breaking links to any server that treats hyphens as significant.

...

ARKs distinguish between lower- and upper-case letters, which makes shorter identifiers possible (52 vs 26 letters per character position). The "ARK way", however, is to use lower-case only unless you need shorter ARKs. The restriction makes it easier for resolvers to support your ARKs in case they arrive from the world with mixed- or upper-case letters, which happens regrettably often due to the lingering 1960s-era view that identifiers are case-insensitive (one sign of which is the prominence of the Caps Lock key on most computer keyboards).

Alphanumeric characters (letters and digits) are generally adequate, but it is recommended to use the betanumeric subset, consisting only of digits and consonants minus 'l' (letter ell, often mistaken for the digit 1):

0123456789bcdfghjkmnpqrstvwxz

This happens to be the repertoire produced from minters (unique string generators) supported by the Noid tool and N2T.net (used by ezid.cdlib.org and the Internet Archive), which creates transcription-safe strings using the strongest mainstream identifier check digit algorithm. When generating unique strings automatically, the absence of vowels helps avoid accidentally creating words that users can misconstrue.

Regarding assignment, one common strategy is to leverage legacy identifiers. For example, a museum moth specimen number cd456f9_87 might be advertised under the ark:/12345/cd456f9_87. Some legacy identifiers may need to be altered in view of ARK character restrictions. The second common strategy is to make up entirely new strings for your ARKs. In this case it is important to consider whether to make them opaque or non-opaque (or a bit of both). 

What are opaque identifiers?

Persistent identifier strings are typically opaque, deliberately revealing little about what they're assigned to, because non-opaque identifiers do not age or travel well. Organization names are notoriously transient, which is why NAANs are opaque numbers. As titles and dates are corrected, word meanings evolve (e.g., innocent older acronyms may become offensive or infringing), strings meant to be persistent can become confusing or politically challenging. The generation and assignment of completely opaque strings comes with risk too, for example, numbers assigned sequentially reveal timing information and strings containing letters can unintentionally spell words (which is why vowels are missing from the recommended character repertoire). 

...

ARKs are not required to be opaque, but it is recommended that the base object name be made opaque, since it tends to name the main focus of persistence. If any qualifier strings follow that name, it is less important that they be opaque. To help choose your approach to opacity, you may wish to consider compatibility with legacy identifiers and ease of string generation and transcription (eg, brevity, check digits). New strings can be created (minted) with date/time, UUID, and number generators, as well as Noid (Nice Opaque Identifiers) minters. 

Opaque strings are "mute" and therefore challenging to manage, which is why ARKs were designed to be "talking" identifiers. This means that if there's metadata, an ARK that comes in to your server with the '?' inflection should be able to talk about itself.

Anchor
servingARKs servingARKs

How do I make server content addressable with ARKs?

First, decide what the user experience of accessing your ARKs will be, for example, a spreadsheet file, a PDF, an image, a landing page filled with formatted metadata and a range of choices, etc. Whichever you choose, plan for your server to be able to respond with metadata if your ARK should arrive with a '?' inflection after it.

Otherwise, serving ARKs is like serving URLs. Normally incoming URL strings somehow address (get mapped to) content that your web server returns. If your server is ARK-aware, incoming ARKs (expressed as URLs) must be mapped to the same content. The term "map" here refers to a generic web server software process that associates the incoming URL with , for example, content such as a particular file or a database entry. The process varies greatly across servers, but can be thought of abstractly as a lookup in a two-column table: column 1 for each incoming URL and column 2 for the corresponding file, database entry, or another URL.

Unfortunately, this mapping table description is abstract because the details depend on your web server software. Fortunately, however, it On the other hand, the idea of mapping is very basic to how the web has worked since the 1990's and , so doing your own resolution is quite feasible. For example, most server configuration files can easily accommodate 100,000 mapping table rows with lines that look like "Redirect <incoming ARK> <URL on this or other server>" (columns 1 and 2, after you replace what is in <>'s). A common approach with ARKs is to map each incoming ARK (column 1) to the kind of URL that your web server already knows how to deal with, and you are done. With this approach, to keep the ARKs in column 1 stable you only need to keep the URLs in column 2 updated when they change. In this case your server is acting as a local resolver. If you don't want to implement this yourself, there are ARK software tools and services that can help.

Another approach is to run your web server without change, but instead of updating local tables, you would update ARK-to-URL mapping tables residing at a non-local resolver. Examples of this can be found among vendors and in any organization that updates tables via EZID.cdlib.org (which, due to a special relationship, updates resolver tables at n2t.net).

How do I cite or advertise an ARK?

The URL (https or http) form of the ARK is preferred, for example,

https://n2t.net/ark:/99166/w66d60p2

An ARK meant for external use is generally advertised (released, published, disseminated) in this way in order to be an actionable identifier. If a more compact visual display of an ARK is needed, it should be hyperlinked; for example, a compact display of an HTML hyperlink can be achieved with

<a href="https://n2t.net/ark:/99166/w66d60p2"> ark:/99166/w66d60p2 </a>

An important decision is whether your URL-based ARKs will use the hostname of your local resolver or the N2T.net resolver. If local control or branding is important enough, you would advertise ARKs based at your local resolver (see about serving content with ARKs). If you're concerned about the stability of your local hostname, you would advertise your ARKs based at n2t.net (see examples of both).

Resolving your ARKs through N2T is always possible for users, regardless of how you advertise them.

...

Yes, ARKs can be assigned at any level of granularity, such as to a manuscript, to chapters inside it, to chapter sections, subsections, etc. An ARK can also be assigned to a thing that encloses other things. In ARKs the character '/' is reserved to help the recipient understand about containment, for example, the first object below contains the second:

ark:/12148/btv1b8449691v

ark:/12148/btv1b8449691v/f29

That's the containment qualifier. There's only one other ARK qualifier, and it indicates variant forms of a thing by using the reserved character '.' in front of a suffix. For example, if these ARKs identify documents,

ark:/12148/btv1b8449691v/f29.pdf

ark:/12148/btv1b8449691v/f29.html

because they differ only by the suffix .pdf or .html, it can be inferred that they identify two different forms of the same document.

...

So shoulders allow ARK assignment operations under a NAAN to be delegated to autonomous projects or divisions, just as NAANs do under the overall ARK namespace. Even if an organization initially only wants to use ARKs for one project, plans may change. If other needs for ARKs arise later, setting aside a new shoulder for each new project or division makes it easy to ensure that autonomous assignment streams – present, past, or future – won't conflict with each other, thanks to non-overlapping namespaces. (Shoulders can also ease the namespace splitting problem.)

Why is there no "/" to mark the end of a shoulder?

In other words, in an ARK such as ark:/12345/x5wf6789, why is the shoulder "/x5" not followed by a "/"? According to ARK rules, if you had published

(please don't do this)     ark:/12345/x5/wf6789/c2/s4.pdf

the "/" after "/x5" implies

1. that ark:/12345/x5 is also an object and
2. that the object named ark:/12345/x5/wf6789/c2/s4.pdf is contained in it.

Both are likely untrue, at least in any way that can be easily explained to a user. It may seem natural to add a "/" because it makes the shoulder boundary obvious to in-house ARK administrators. Recalling that in-house specialists can afford to be inconvenienced, it doesn't help the end user either is uninterested and confused by your internal operational boundaries, or is so very interested that you risk their trying to hold you to account for their inferences (eg, about consistent support levels across objects sharing the apparent containing object). Less transparency about administrative structure hides messy details and can save you user-support time in the end.

In fact, in-house ARK administrators always know where the shoulder ends, provided it was chosen using the "first-digit convention". A primordinal shoulder is a sequence of one or more betanumeric letters ending in a digit. This means that the shoulder is all letters (often just one) after the NAAN up to and including the first digit encountered after the NAAN. Another advantage of primordinal shoulders is that there is an infinite number of them possible under any NAAN.

How do I implement a shoulder?

There are different ways to implement a shoulder. Fundamentally, a shoulder is a deliberate practice based on a decision you make to assign ARKs that start with a particular extension to your NAAN. A shoulder can then "emerge" as your practices consciously observe and incorporate that extension as a prefix in ARKs that you create.

Having said that, there are a couple of cases where shoulder implementation does involve a kind of "creation" step. A system such as ezid.cdlib.org supports both the purely "decision-based" shoulders above (that emerge from user practice, eg, Smithsonian) as well as the creation of system-recognized shoulders with accompanying minter services and registered API access points. In contrast, implementing a decision-based shoulder requires no explicit shoulder creation step, but does involve the creation of one or more ARKs that start with that shoulder. As a special case that works with the N2T.net resolver, it is possible to create a short ARK, such as ark:/99152/p0, that looks and acts like a shoulder; to make that happen, it is sufficient for the ARK to redirect to a server URL that can handle N2T's suffix passthrough, in which case that ARK (while technically an identifier) is effectively the root of a shoulder namespace.

A completely different kind of shoulder "creation" step is needed to implement a shoulder under one of the few shared NAANs (below).

Are there restrictions on the use of NAANs and shoulders?

Yes. It is important never to invent or use a NAAN that is not listed in the public NAAN registry. In general ARKs that an organization creates always start with its NAAN, but exceptions are made for four special NAANs meant to be shared across organizations. To avoid the possibility of conflicting ARK assignments on a shared NAAN, the simple solution is for organizations to reserve a shoulder by filling out the usual form to request a shoulder under a shared NAAN.

Each shared NAAN has certain immutable connotations that software (and people with enough training) can recognize and benefit from.

...

Purpose, meaning, or connotation of ARKs with this NAAN

...

12345 examples

...

99152 terms

...

99166 agents

...

99999 test

...

ARKs for test, development, or experimental purposes, often at scale. They might resolve, but no link checker need be concerned if they don't. They should never be used for long term reference.

...

Are there restrictions on the use of NAANs and shoulders?

Yes. It is important never to invent or use a NAAN that is not listed in the public NAAN registry. In general ARKs that an organization creates always start with its NAAN, but exceptions are made for four special NAANs meant to be shared across organizations. To avoid the possibility of conflicting ARK assignments on a shared NAAN, the simple solution is for organizations to reserve a shoulder by filling out the usual form to request a shoulder under a shared NAAN.

Each shared NAAN has certain immutable connotations that software (and people with enough training) can recognize and benefit from. Normally NAANs do not carry meaning, but we make exceptions when we expect that the meanings cannot be changed over time.

The 99999 and 12345 ARKs are especially useful if you are responsible for reviewing broken link reports because they can all safely be ignored. Despite providers' best efforts, these test and example ARKs frequently "escape into the wild" for all to see. Recipients (eg, people and link checkers) that would normally be concerned with broken links have only to recognize these two special NAANs in order to not become distracted by such ARKs.

What are the key takeaways about shoulders?

1. If you don't use shoulders from the beginning, even for one simple stream of assignments, you risk creating a mild but permanent chaos in your NAAN namespace, and you may end up needing a new NAAN for future assignment streams.

2. The very useful non-opaque NAANs listed above require shoulders because they can be shared across organizations only if there is a way to keep independent assignment operations from conflicting.

If you would like to learn more about shoulders, please see the brief ARK Shoulders FAQ.

Why is there no "/" to mark the end of a shoulder?

In other words, in an ARK such as ark:/12345/x5wf6789, why is the shoulder "/x5" not followed by a "/"? According to ARK rules, if you had published

(please don't do this)     ark:/12345/x5/wf6789/c2/s4.pdf

the "/" after "/x5" implies

1. that ark:/12345/x5 is also an object and
2. that the object named ark:/12345/x5/wf6789/c2/s4.pdf is contained in it.

Both are likely untrue, at least in any way that can be easily explained to a user. It may seem natural to add a "/" because it makes the shoulder boundary obvious to in-house ARK administrators. Recalling that in-house specialists can afford to be inconvenienced, it doesn't help the end user either is uninterested and confused by your internal operational boundaries, or is so very interested that you risk their trying to hold you to account for their inferences (eg, about consistent support levels across objects sharing the apparent containing object). Less transparency about administrative structure hides messy details and can save you user-support time in the end.

In fact, in-house ARK administrators always know where the shoulder ends, provided it was chosen using the "first-digit convention". A primordinal shoulder is a sequence of one or more betanumeric letters ending in a digit. This means that the shoulder is all letters (often just one) after the NAAN up to and including the first digit encountered after the NAAN. Another advantage of primordinal shoulders is that there is an infinite number of them possible under any NAAN.

How do I implement a shoulder?

There are different ways to implement a shoulder. Fundamentally, a shoulder is a deliberate practice based on a decision you make to assign ARKs that start with a particular extension to your NAAN. A shoulder can then "emerge" while your practices consciously observe and incorporate that extension as a prefix in ARKs that you assign. This sort of shoulder appears gradually instead of suddenly in one moment of creation.

Having said that, there are two special cases where shoulder implementation does involve a kind of "creation" step. First, a system such as ezid.cdlib.org supports both the purely "decision-based" shoulders above (that emerge from user practice, eg, Smithsonian) as well as an administrative action that sets up a system-defined shoulder. The details depend on the system, for example, an "EZID shoulder" has accompanying minter service and registered API access point. By contrast, implementing a decision-based shoulder requires no explicit shoulder creation step, but does involve the creation of one or more ARKs that start with that shoulder.

As a second special case applicable to ARKs stored in the N2T.net resolver (EZID, Internet Archive, and YAMZ ARKs), it is possible to create a short ARK identifier, such as ark:/99152/p0, that looks and acts like a shoulder. To make it work, it suffices for that ARK to redirect to a server URL that can handle N2T's suffix passthrough feature. The more familiar you are with this feature, the more you will be able to see that short ARK identifier as the root of a namespace that is, effectively, a shoulder.

A completely different kind of shoulder "creation" step is needed to implement a shoulder under one of the few shared NAANs (below)The 99999 and 12345 ARKs are especially useful if you are responsible for reviewing broken link reports because they can all safely be ignored. Despite providers' best efforts, these test and example ARKs frequently "escape into the wild" for all to see. Recipients (eg, people and link checkers) that would normally be concerned with broken links have only to recognize these two special NAANs in order to not become distracted by such ARKs.

Is there a quick way to get started creating test ARKs?

...