---
# System prepended metadata

title: EZID Resolver Design

---

---
title: EZID Resolver Design
subtitle: ARK and DOI identifier resolution for the EZID service
---

# EZID Resolver Design

Identifier resolution is the process of determining the location of an identified resource. For the EZID application, the resolution service is provided for ARK identifiers and is accessed using the HTTP protocol, and so ARK and HTTP specifications apply.


```
                               PREFIX
                         SCHEME  |          SUFFIX
                          /--\ /---\ /--------------------\ 
       http://example.org/ark:/12025/654xz321/s3/f8.05v.tiff
       \________________/ \__/ \___/ \______/ \____________/
         (replaceable)     |     |      |       Qualifier
              |       ARK Label  |      |    (NMA-supported)
              |                  |      |
    Name Mapping Authority       |    Name (NAA-assigned)
       Hostport (NMAH)           |
                        Name Assigning Authority Number (NAAN)
```

## Operations

There are two basic operations to be supported:

1. Resolution, redirection to the location registered with the identifier.
2. Instrospection, providing information about the identifier. Called "inflection" in the ARK spec.

Operation requirements include:

* Respond to HTTP GET and HEAD requests.
* Respect HTTP protocol semantics

### Resolution

The basic process of resolution is straight forward.

Current situation:
```plantuml
actor User as U
actor Owner as C
participant EZID as E
participant N2T as N
participant Target as T

== minting ==
C -> E: mint ark:123/a to target/foo
activate E
note right of E
pid = ark:123/a
url = https://n2t.net/ark:123/a
loc = https://target/foo
end note
E --> C: ok
E -> N: create ark:123/a to target/foo
N --> E: ok
deactivate E

== resolution ==
U -> N: ark:123/a
activate N
N --> U: 302, target/foo
deactivate N
U -> T: /foo
```

After transition of resolution to EZID:
```plantuml
actor User as U
actor Owner as C
participant EZID as E
participant Target as T

== minting ==
C -> E: mint ark:123/a to target/foo
activate E
note right of E
pid = ark:123/a
url = https://ezid/ark:123/a
loc = https://target/foo
end note
E --> C: ok
deactivate E

== resolution ==
U -> E: ark:123/a
activate E
E --> U: 302, target/foo
deactivate E
U -> T: /foo
```


A possible workflow for identifier resolution in EZID:

```plantuml
start
->IDENTIFIER;
:split identifier;
->t=SCHEME\np=PREFIX\ns=SUFFIX;
if (scheme is ARK?) then (no)
    :response = {
       status: 302,        
       location: doi.org/10.PREFIX/SUFFIX
       message: "doi.org" 
    };
else (yes)
    if (EZID prefix?) then (yes)
      :find longest suffix match;
      if (match?) then (yes)
        :response = {
           status: 302,        
           location: URL
           message: found
         };
      else (no)
        :response = {
           status: 404,
           message: "Not Found"
         };
      endif
    else (no)
      :response = {
         status: 404,
         message: "Not Found"
       };
    endif
endif
:return response;
stop
```

Questions:

1. Under what conditions should an existing identifier not be resolvable?
    * Withdrawn?
    * Deleted?
    * Target known to be unavailable?
    * Privacy?
    * Reserved
    Generally no change in policy, but edge cases need to be handled correctly.
2. If the prefix is not registered with EZID, should the response be 404 or redirect to another service (N2T)?
    * Perhaps redirect to N2T, need to ensure redirect loops don't happen
    * Better - provide information in the 404 response pointing to N2T for the place to go
4. What endpoint should be used for resolution?
    * **Suggest `ezid.cdlib.org/{PID}`**
    * ~~ark.ezid.cdlib.org/ark:/123/lkdfjg~~
6. OK to present the alternate link to metadata for the identifier (i.e. inflection URL) in the response?
    This would provide the client with a hint that details about the identifier can be obtained through the inflection URL. It would be in a response header like:
    ```
    Link: <https://ezid.net/info/ark:/12345/xyz>; rel="alternate"; 
      type="application/ld+json"; profile="https://w3id.org/ark/metadata"
    ```

7. Consider supporting shoulder listing, e.g. https://n2t-stg.n2t.net/ark:/99999
8. Verify suffix passthrough is working as expected (e.g. Smithsonian)
9. Existing arks will be updated to resolve to the EZID resolver location instead of the target.

### Inflection

The ARK spec indicates that an inflection request can be made by including one or more question ("?") characters at the end of a request URL. 

The basic workflow for inflection is much the same as for resolution. The main difference being the final action once the corresponding identifier record has been located.

```plantuml
start
->IDENTIFIER;
:split identifier;
->t=SCHEME\np=PREFIX\ns=SUFFIX;
if (EZID prefix?) then (yes)
  :find longest shoulder match;
  if (match?) then (yes)
    :Get record;
    :response = {
        status: 200,
        ID META
    };
  else (no)
    -> no;
    :Get prefix;
    :response = {
       status: 200,
       PREFIX META
     };
  endif
else (no)
  -> no;
  :response = {
     status: 404,
     message: "Not Found"
   };
endif
:return response;
stop
```

Questions:

1. Can the "?" char be reliably passed through the load balancer, Apache, Django stack?
    * No, only a double "??" can pass through, appearing as a single "?" in the query parameters.
    * May be possible to intercept at the load balancer and set a custom header forwarded to Apache / Django
3. What metadata should be presented in the response?
    * Privacy? Only reserved identifiers have no response
    * Different metadata for authenticated user? Owner? Nope.
5. Can we use "profile" recognition to implement inflection at the resolve end point?
    * Seems sensible to support, especially since DataCite (DOIs in general) fail in support for content negotiation.
8. Content negotion should support ANVL and probably JSON?
9. What is the media type of ANVL? (check with Kunze)

## Deployment

1. Implement and deploy resolution and inflection functionality for EZID. New PIDs still have `asURL` set to N2T
2. Notify users of impending change
3. New PIDs start using EZID for `asURL`
4. Update the target URLs for EZID ARKs on N2T to point to the EZID `asURL`
5. No further updates from EZID to N2T.


## Notes on conflicts with HTTP and URI specification

These notes are general to ARKs, not specific to EZID.


> The Name and Qualifier parts are strings of visible ASCII characters and should be less than 128 bytes in length. The length restriction keeps the ARK short enough to append ordinary ARK request strings without running into transport restrictions (e.g., within HTTP GET requests). Characters may be letters, digits, or any of these six characters:

```     
       =   #   *   +   @   _   $
```
>  The following characters may also be used, but their meanings are reserved:
```
       %   -   .   /
```

### Inflection

The ARK "inflection" is meant to "change the meaning" of the identifier, to reference the metadata associated with the ARK instead of the object identified by the ARK. The specification uses a "?" to do this. Also:

> "When the ARK is inflected by appending dual question marks ('??'), the returned metadata contains a commitment statement from the current provider."

The question char is a reserved character in the URI specification[^uri] which creates a behavior conflict when requesting ARK inflection from an ARK resolver over HTTP by way of embedding the ARK as part of the URL. 

Since these "?" chars are not to be interpreted as URL query delimiters according to RFC 3986, they should be escaped as `%3F`.

Here's some examples of inflection with n2t:
`https://n2t.net/ark:/86084/b4057cw7z%3F`:
```
erc:  
who: Tevel Gitlin. Award booklet, 1946
what: IS030_GITL_003
when: (:unav)
where: ark:/86084/b4057cw7z (currently
	https://blavatnikarchive.org/item/2964)
how: (:unav)

# inflections under construction
# reference https://n2t.net/e/n2t_apidoc.html
```
`https://n2t.net/ark:/86084/b4057cw7z%3F%3F`:
```
erc:  
who: Tevel Gitlin. Award booklet, 1946
what: IS030_GITL_003
when: (:unav)
where: ark:/86084/b4057cw7z (currently
	https://blavatnikarchive.org/item/2964)
how: (:unav)
id created: 2021.08.02_09:31:42
id updated: 2021.08.02_09:31:33
persistence: (:unav)

# inflections under construction
# reference https://n2t.net/e/n2t_apidoc.html
```

`https://n2t.net/doi:10.21239/V9F61N?`:
```
erc:  
who: (:unav)
what: (:unav)
when: (:unav)
where: doi:10.21239/V9F61N (currently
	https://siam.invemar.org.co/download-alfresco-file/241512)
how: Text

# inflections under construction
# reference https://n2t.net/e/n2t_apidoc.html
```

`https://n2t.net/doi:10.21239/V9F61N??`:
```
erc:  
who: (:unav)
what: (:unav)
when: (:unav)
where: doi:10.21239/V9F61N (currently
	https://siam.invemar.org.co/download-alfresco-file/241512)
how: Text
datacite: <?xml version="1.0"?>
<resource
	xmlns="http://datacite.org/schema/kernel-4"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://datacite.org/schema/kernel-4
	http://schema.datacite.org/meta/kernel-4/metadata.xsd"><identifier
	identifierType="DOI">10.21239/V9F61N</identifier><creators><creator><creatorName>Elías
	Alberto Blanco
	Mota</creatorName></creator></creators><titles><title
	xml:lang="spa">Informe técnico de levantamiento batimétrico
	Bahía de Buenaventura – Pacifico
	Colombiano</title></titles><publisher>INVEMAR</publisher><publicationYear>2015</publicationYear><resourceType
	resourceTypeGeneral="Text">Text</resourceType><subjects><subject>batimetria</subject></subjects><dates><date
	dateType="Created">2015</date></dates><language>spa</language><sizes><size>3
	MB</size></sizes><formats><format>PDF</format></formats><version>1</version><rightsList><rights>CC
	BY 4.0</rights></rightsList><descriptions><description
	descriptionType="Abstract" xml:lang="spa">Levantamiento
	batimétrico de precisión (líneas cada 50m) de La Bahía de
	Buenaventura sector Cascajal y esteros aledaños, en el
	departamento del Valle del Cauca.&#13;
La información fue
	tomada en el campo, en el periodo comprendido entre el 05 y 13
	de mayo de 2015, incluyendo ademas  perfiles de velocidad del
	sonido y sus ubicaciones geográficas en el área de estudio,
	así mismo la ubicación de ayudas a la navegación flotantes
	en la zona. abarcando un total 2509 Ha aproximadamente, desde
	una profundidad mínima promedio de -2.75 msnm hasta una
	máxima promedio de 19
	msnm.</description></descriptions><geoLocations><geoLocation><geoLocationPlace>Buenaventura,
	Valle,
	Colombia</geoLocationPlace></geoLocation></geoLocations></resource>
datacite.resourcetype: Text
id created: 2018.03.07_13:12:02
id updated: 2021.05.10_12:12:36
persistence: (:unav)

# inflections under construction
# reference https://n2t.net/e/n2t_apidoc.html
```

`https://n2t.net/ark:/53355/cl010066723?`
```
-> https://collections.louvre.fr/ark:/53355/cl010066723
```

`https://n2t.net/ark:/53355/cl010066723%3F%3F`
```
https://collections.louvre.fr/ark:/53355/cl010066723
```

`http://n2t.net/ark:/65665??`
```
ark:/65665:
    date: 2014.08.18
    manager: n2t
    na_policy: NP | (:unkn) unknown | 2014 |
    name: The Smithsonian Institution (=) TSI
    redirect: http://collections.nmnh.si.edu/ark:$id
    type: naan

ark:/65665/:
    date: 2015.03.31
    is_supershoulder: true
    manager: ezid
    minter: 
    name: National Museum of Natural History, Smithsonian Institution - empty shoulder
    type: shoulder

ark:/65665/n6:
    date: 2014.08.18
    manager: ezid
    minter: https://n2t.net/a/ezid/m/ark/65665/n6
    name: National Museum of Natural History, Smithsonian Institution
    type: shoulder
```

`http://n2t.net/ark:/65665/300008335-8d74-4c3f-873c-a9d8b4b3d6a8??`:
```
-> http://collections.nmnh.si.edu/id/ark:/65665/3000083358d744c3f873ca9d8b4b3d6a8??
```

Given the ambiguities of the ARK specification and conflict with HTTP URI structure, resolver support of inflection would be better provided through an alternate request and advertised via HTTP link headers [^link-headers].

Candidate [link header relations](https://www.iana.org/assignments/link-relations/link-relations.xhtml):

about
: Not applicable since the current URI is about the URI provided in the header. This needs to be inverted for ARK resolvers.

alternate
: Viable, with URI, type, profile, and optional title, lang. **This is the preferred option.**

describes, describedBy
: Encumbered by the POWDER spec, which appears to be essentially unused.

related
: Burdened by ATOM spec, not specific enough.


Recommendation: Use the HTTP Link Header response to advertise availability of ARK metadata.

For example:
```
GET https://ezid.net/resolve/ark:/12345/xyz

HTTP/1.1 302 Found
Location: https://example.net/data/12345/xyz
Link: <https://ezid.net/info/ark:/12345/xyz>; rel="alternate"; 
      type="application/ld+json"; profile="https://w3id.org/ark/metadata";
```

Provides that an alternate representation serialized in JSON-LD according to the profile identified by `https://w3id.org/ark/metadata` is available from URL `https://ezid.net/info/ark:/12345/xyz`


[^uri]: https://datatracker.ietf.org/doc/html/rfc3986#section-2.2


### Forward Slashes and Periods

ARKs use the forward slash character "/" as a delimiter. Slashes are not as problematic as the question chars specified for inflection. Basically everything starting at the beginning of `ark:` should be handled by the resolver.

Note however:
> The characters `/' and `.' are ignored if either appears as the last character of an ARK.
> ARK Spec § 2.6

### Hash Characters

The hash character "`#`" is allowed as a character in an ARK. When appearing in a URI, the `#` denotes a URI fragment, and URI fragments are not transmitted as part of a URL request sent to the server by a client. This means that the portion of the ARK starting from the `#` char will never be received by the resolver service unless it is percent encoded, i.e. `%23`.

### Hyphens

Hyphens are completely arbitrary and meaningless in ARK identifiers:

> Hyphens are considered to be insignificant and are always ignored in ARKs.  A '-' (hyphen) may appear in an ARK for readability, or it may have crept in during the formatting and wrapping of text, but it must be ignored in lexical comparisons.  As in a telephone number, hyphens have no meaning in an ARK.  It is always safe for an NMA that receives an ARK to remove any hyphens found in it.
> ARK Spec § 2.6


## Implementation

The EZID resolver will be implemented as a HTTP service.


### HTTP Methods

The principle HTTP method to be supported for resolution is GET. HEAD and POST should also be supported.

#### GET

The `GET` method requests transfer of a current selected representation for the target resource.

- https://datatracker.ietf.org/doc/html/rfc7231#section-4.3.1
- https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/GET

> "Request strings too long for GET may be sent using HTTP's POST command." 
> ARK Spec § 5.2.

#### HEAD

The `HEAD` method is identical to `GET` except that the server MUST NOT send a message body in the response

- https://datatracker.ietf.org/doc/html/rfc7231#section-4.3.2
- https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/HEAD

#### POST

See GET. For ARKs, the POST is considered the same as GET, just for longer request strings. It is OK for a POST response to return a 302 status and redirect information.


### Caching

Caching can significantly improve performance and reduce server load. At a minimum, the resolver should provide time stamps (e.g. `Last-Modified` response header) indicating when a resource was last modified.

## ARK Normalization

ARK Spec 2.7:

Normalization of an ARK for the purpose of octet-by-octet equality comparison with another ARK consists of four steps.  First, any upper case letters in the "ark:" label and the two characters following a '%' are converted to lower case.  The case of all other letters inthe ARK string must be preserved.  Second, any NMAH part is removed(everything from an initial "http://" up to the next slash) and allhyphens are removed.

Third, structural characters (slash and period) are normalized.Initial and final occurrences are removed, and two structuralcharacters in a row (e.g., // or ./) are replaced by the firstcharacter, iterating until each occurrence has at least one non-structural character on either side.  Finally, if there are any components with a period on the left and a slash on the right, either the component and the preceding period must be moved to the end of the Name part or the ARK must be thrown out as malformed.

The fourth and final step is to arrange the suffixes in ASCII collating sequence (that is, to sort them) and to remove duplicate suffixes, if any.  It is also permissible to throw out ARKs for which the suffixes are not sorted.


[^uri-parts]: https://datatracker.ietf.org/doc/html/rfc3986#section-3
[^link-headers]: https://datatracker.ietf.org/doc/html/rfc8288

## References
- [ARK General Info](https://arks.org/about/)
- [ARK Specification v.18](https://www.ietf.org/archive/id/draft-kunze-ark-18.txt)
- [HTTP Specification](https://datatracker.ietf.org/doc/html/rfc7231)
- [Link Headers]()

