EPICUR: Description of URN transfer interfaces

URN management transfer conditions and interfaces at the German National Library

1. Introduction
2. Terms and Definitions
3. Data structure, syntax and semantics
4. Notes on data structure and syntax
5. URN transfer methods
      5.1 URN registration via existing workflow procedures
      5.2 Manual URN management
      5.3 E-mail
      5.4 OAI 2.0 protocol

1. Introduction

The German National Library is able to process data generated as part of the URN procedure using various transfer methods. The present document describes the technical conventions needed in these transfer methods and gives corresponding examples. It is possible to select between several alternatives concerning the technical transfer methods and that that provides the best solution for the institution's existing workflow.

2. Terms and Definitions

URN management

The term "URN management" is used to designate all procedures required for the productive application of URNs. The following procedures are of significance to the URN namespace administrator:

Allocating URNs for
- Complete objects
- Part objects
- Object versions
Transferring the URN-URL pair to the German National Library
- Updating URLs (deleting, adding, changing a URL)
- Maintenance of administrative data such as contact information

The URN related services at the German National Library are described under its URN strategy.

URN-URL pairs

What does a URN refer to? A URN points to at least one URL. URN- and URL related information must be captured together and registered at the German National Library. URNs in the form urn:nbn:de:gbv:089-3321752945 can only be applied, for example in an online catalogue, if the required information are registered at the German National Library.

URN-URL relationships

This term is used to describe all URN-URL relationships which arise in the context of a URN management:

1:1 relationship (1 URN refers to 1 URL)
1:n relationship (1 URN refers to several URLs)
hierarchical relationships from URNs of part documents to URNs of complete documents
semantic relationships of one URN to a URN for a new version of an object.

URL management

This term comprises the procedure for the initial registration of URN-URL pairs as well as all update processes such as deleting or updating URLs.

URN transfer methods

This term covers all the technical data transfer options for URN-URL pairs, for example via existing workflows from the URN namespace administrator to the German National Library.

XML record or record

This represents a unit of the registration format for URN-URL relationships, based on XML syntax.

3. Data structure, syntax and semantics

The description of the data records', data structure, syntax and semantics is based on XML and is explained in xepicur - XML data transfer format for the management of Persistent Identifiers.

4. Technical notes on data structure and syntax

Data received via the existing transfer interfaces described below are processed entirely automatically by the German National Library.

The description of the data record structure that can be processed by the German National Library can be found in the document specified in Point 3.

The description of the structure comprises details on permitted syntax, case sensitivity such as "epicur", "administrative_data", "record", "identifier", "isPartOf" and is comprehensive in regard to

the number of permitted and mandatory element and sub-element identifiers and
the possible combinations of attributes such as "scheme", "imt"
and the rules on repeating element identifiers such as "administrative_data", "record" or the "identifier" itself.

Specifically the following processing rules apply in cases of incompatibility between specifications and the actual metadata records delivered.

Structural incompatibility
- Insofar as structural incompatibility in records can be ascribed to XML, then the records will be returned automatically to the sender or to the registered contact person with an explanation.
Element identifiers
- If element identifiers that must be defined are missing from the records ("epicur", "administrative_data", "delivery", "update_status", "record", "identifier") then the records will be returned automatically to the sender or to the registered contact person with an explanation.
Using undefined element identifiers
- If element identifiers other than those set out in chapter 2 are used, then the records will be returned automatically to the sender or to the registered contact person with an explanation.
Attributes
- If attributes which must be defined ("type", "scheme", "imt") are missing, then the records will be returned automatically to the sender or to the registered contact person with an explanation.
Semantic incompatibility
- All incoming records will be checked against the following criteria:
  - Details supplied match the target of the record, such as initial URN registration or URL updating
  - Checking URN(s) and URL(s) for duplication
  - URN consistency checked using URN check digit

In case of errors, the records will be returned automatically to the sender or to the registered contact person with an explanation

5. URN transfer methods

5.1 URN registration via existing workflow procedures
5.2 Manual URN management
5.3 Email
5.4 OAI 2.0 protocol

The various URN transfer methods offer different functionality. The disadvantage if URNs registered at the German National Library using existing workflow procedures is that only URN registration is possible, and other procedures in context of the URN management for example to update URLs have to be performed using another transfer methods. For this reason the German National Library prefers either implementing transfer by e-mail of the implementation of the OAI 2.0 URN management system.

5.1 Registering URNs at the German National Library using existing workflow procedures

5.1.1 What is possible?

Type of registration
- Single registration
URN management
- Initial URN registration

5.1.2 What is NOT possible?

Type of registration
- Multiple registrations
URN management
- Initial URN registration for part documents
- Initial URN registration for new versions of objects
URL management
- Updating a single URL
- Deleting a single URL
- Inserting a new URL
Registering an additional Persistent Identifier for an object

5.1.3 Established workflow procedures for registering and archiving online resources at the German National Library

The following business procedures for registering and archiving online resources at the German National Library can be used for registering URNs.

In both workflow procedures metadata is delivered to the German National Library using a variety of transfer interfaces. A field is provided in the metadata for "Persistent Identifier" and "Uniform Resource Locator (URL)". These fields must be completed. URN registration then occurs automatically.

5.1.3.1 URN registration for networked publications using the interactive registration form

Step 1: Authenticating who is registering

The person registering authenticates him/herself using the identification details supplied (ID and password) on the website: http://deposit.d-nb.de/cgi-bin/epmeld_form.pl

Step 2: Registration of metadata

Metadata are then registered. The information required for archiving a networked publication at the German National Library are explained in detail in a separate comprehensive Registration form help.

Step 3: URN and URL details

Enter the URN in the "Adress/Identifier" field and click on the "URN" radio button.

Then repeat the field group, while pressing the "+" button.
Enter the URL in the "Address/Identifier" field and click on the "URL" radio button.

5.1.3.2 Registering URNs for academic publications.

Further information on registering URNs for online theses and dissertations

5.2 Manual URN management

This transfer method offers manual URN management

if you are expecting to manage a small number of URNs or

to compensate for lacking the functionality of the transfer interfaces described in point 5.1.

5.2.1 What is possible?

Type of registration
Single registration

URN management
Initial URN registration

Initial URN registration for part documents

Initial URN registration for a new version of a publication

URL management
Updating single URLs or all the URLs that are registered against a single URN

Adding a URL

Deleting a URL

Registering an additional Persistent Identifier for an object

5.2.2 What is NOT possible?

Type of registration
Multiple registrations

5.2.3 Production steps

Step 1: Authenticating the URN namespace administrator

The person registering authenticates him/herself using the identification details supplied (ID and password) on the website: http://nbn-resolving.de/login.php

Step 2: Selecting the intended action

After successful authentification various URN management functions will be available. The information which needs to be registered are explained in detail in a separate URN namespace management help.

Step 3: Registration the information

Information is captured using interactive forms.

5.3 Email

5.3.1 What is possible?

Type of registration

Single registration
Multiple registrations

URN management
Initial URN registration
Initial URN registration for part documents
Initial URN registration for a new version of a publication

URL management
Updating single URLs or all the URLs that are registered against a single URN
Adding a URL
Deleting a URL

5.3.2 Production steps

The procedure is carried out in the following steps:

Step 1: Target of registration process

The target of the registration process, such as, for example an initial URN registration, or updating a URL, requires different information to be registered. The information required is drawn from the descriptions in "xepicur - an XML data transfer format for the management of Persistent Identifiers".

Step 2: Creating a "[name].xml" text file

Create an XML file following the rules in "xepicur - an XML data transfer format for the management of Persistent Identifiers". The file can be given any name. The file extension must be "xml".

Example: urn:nbn:de:1111-20040405.xml

In this example the file name is derived from the URN sub-namespace and the date of delivery.

Step 3: Send the XML file as an attachment to an e-mail

The XML file created have to be sent as an attachment to an e-mail to the following address at the German National Library:

"urn-transaction@nbn-resolving.org"

Leave the subject line empty.
The body of the e-mail message is also empty.

Step 4: Finding out about processing status

The subsequent processing workflow at the German National Library is automated. A message will be generated containing the processing status (successful or unsuccessful).

5.3.3 Examples (ZIP)

Examples (XML)

URN management
Initial URN registration of entire object (Minimum, Maximum)
Initial URN registration of part object (Minimum, Maximum)
Initial URN registration of new version of object (Minimum, Maximum)

URL management
Updating URL (Minimum, Maximum)
Updating a single URL (Minimum, Maximum)
Deleting a single URL (Minimum, Maximum)
Inserting a new URL (Minimum, Maximum)

Registering an additional Persistent Identifier for an objectMinimum, Maximum)

5.4 OAI 2.0 protocol

5.4.1 What is possible?

Type of registration
Single registration

URN management
Initial URN registration
Initial URN registration for part documents
Initial URN registration for a new version of a publication

URL management
Updating URLs for all URLs registered against a single URN

5.4.2 Data provider's OAI minimum implementation requirements

Implementing OAI protocol version 2.0

daily, selective harvesting (from...until...)

OAI requests for various metadata schemata

Consistent date-stamp updating when altering data records

5.4.3 Data provider's OAI maximum implementation requirements

The minimum requirements must be met

Flow control using "Resumption Token"

Selective harvesting on an hourly basis (from... until...)

5.4.4 Production steps

Step 1: Extending the data provider OAI request following "metadataPrefix=epicur"

The OAI data provider must permit an OAI request for "metadataPrefix=epicur" .

Example

[...]
<request verb="ListRecords" from="2004-03-30T00:00:00Z" until="2004-03-31T00:00:00Z" metadataPrefix="epicur">

http://[OAI data provider domain]/[filepath]/[OAI script]

</request>
[...]

Step 2: Structuring metadata in "xepicur"

The previously created metadata are to be structured following the rules in "xepicur - an XML data transfer format for the management of Persistent Identifiers".

General notes on preparing metadata for URN management

Regardless of the data model used by the data provider, it may be necessary to extend the data model using the "update_status" field.

Consistently updating the date stamp, when changes to the URN related metadata.

When making changes, especially URL updates, essentially only the desired target status, thus for example only current URLs, will be created.

5.4.5 Examples (ZIP)

5.4.5.1 Example answer to an OAI request for "metadataPrefix=epicur"

<?xml version="1.0" encoding="UTF-8"?> <OAI-PMH xmlns="http://www.openarchives.org/OAI/2.0/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/
http://www.openarchives.org/OAI/2.0/OAI-PMH.xsd">
<responseDate>2004-03-31T15:43:26Z</responseDate>
<request verb="ListRecords" from="2004-03-30T00:00:00Z" until="2004-03-31T00:00:00Z" metadataPrefix="epicur">
http://edoc.hub-berlin.de/oai2.0/urnoai

</request>

<ListRecords>
<record>
  <header>
   <identifier>oai:hub:myurn</identifier>
   <datestamp>2004-03-30T16:20:12Z</datestamp>
  </header>

  <metadata>
   <epicur xmlns="urn:nbn:de:1111-2004033116" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance="    xsi:schemaLocation="urn:nbn:de:1111-2004033116
   http://nbn-resolving.de/urn/resolver.pl?urn=urn:nbn:de:1111-2004033116">
   

   <administrative_data>
    <delivery>
     <update_status type="urn_new"/>
    </delivery>
   </administrative_data>
   <record>
    <identifier scheme="urn:nbn:de" >urn:nbn:de:kobv:11-1008171</identifier>
    <resource>
     <identifier scheme="url">http://dochost.rz.hu-berlin.de/dissertationen/biologie/schmidt-kathrin/SGML/schmidt.did </identifier>
     <format scheme="imt">text/sgml</format>
    </resource>
   </record>
   </epicur>

  </metadata>

  [...]

</record>
</ListRecords>
</OAI-PMH>

5.4.5.2 Initial URN registration for complete and part objects

Notes

Updating the date stamp

The attribute of the "update_status" element is "urn_new" (update_status="urn_new")

Examples (XML)

Initial URN registration of complete object (Minimum, Maximum)

Initial URN registration of part object (Minimum, Maximum)

5.4.5.3 Initial URN registration for new versions of objects

Notes

Updating the date stamp

The attribute of the "update_status" element is "urn_new_version" (update_status="urn_new_version")

Examples (XML)

Minimum

Maximum

5.4.5.4 Updating URLs

Notes

Updating the date stamp

The attribute of the "update_status" element is "url_update_general" (update_status="url_update_general")

Only new URLs will be detailed.

Examples (XML)

Minimum

Maximum

02.01.2008