xepicur - Reference description "xepicur - an XML data transfer format for the administration of Persistent Identifiers"

xepicur - an XML data transfer format for the administration of Persistent Identifiers

Introduction
B Data transfer format
   1. General notes
    2. Data structure and syntax notes
    3. Description of data format, and sequence and structure of elements.

Introduction

The following document describes the data transfer format "xepicur". This XML based format provides a comprehensive URN administration. Data records are created by the authorised URN namespace administrator and can

be active reported to the German National Library directly or
harvested by the German National Library.

This includes the following procedures:

Initial registration of URNs for
- Complete objects
- Partial objects or
- Versions of objects
URL management
- updating of one or more URL
- adding one or more URL
- deleting one or more URL

Data records are created by the authorised URN namespace administrator and can be submitted as

single or
accumulated reports

and

can be active reported to the German National Library or
harvested by the German National Library.

The various transfer methods are detailed under Description of transfer interfaces.

"xepicur" was developed as part of the EPICUR project in co-coperation of the EPICUR with digital library tool developers and content providers.

B Data transfer format

1. General notes

Validity
- xepicur is mandatory for the transfer of all URN management data records, except for existing reporting procedures for archiving digital objects at the German National Library.

2. Notes on data structure and syntax

The XML document format has to be used for structuring the data record.

Types of elements
- The xml data record contains data elements which appear in a structured form, differentiated according to their element type. Each data element is preceded by an element descriptor (tag) which represent the name of the element.
- Example: <identifier>
Attributes
- Element descriptors are specified by their attributes. Mandatory ("type", "scheme", "imt") and optional ("role", "status" or "type") attributes have been defined.
- Example: <identifier scheme="url" role="primary">

3. Description of data format, and sequence and structure of elements

General structure

An XML data record comprises one root element

<epicur>

and two subordinated sub-elements

<administrative_data>
<record>

root element

"epicur" root element

Designation epicur

Attributes none

Sub-elements

"administrative_data"

"record"

repeatable no

mandatory yes

description The root element encapsulates the XML document.

Syntax <epicur>
<administrative_data>
[...]
</administrative_data>
<record>
[...]
</record>
</epicur>

"administrative_data" element group

"administrative_data" element

Designation administrative_data

Attributes none

Sub-elements

"delivery"

repeatable no

mandatory yes

description The element incorporates the verification data, the specification of the URN reporting process, the transfer interface used and type of confirmation concerning the processed data records.

Syntax <administrativ_data>
<delivery>
[...]
</delivery>
</administrative_data>

"authorization" element

Designation authorization

Attributes none

Sub-elements

"person_id"
Authorisation ID for a person.

"system_id"
Alternative to "person_id". This is an ID that only used in conjunction with automated URN reporting process.

"urn_snid"
This element contains the NBN sub-namespace such as urn:nbn:de:gbv:089. The aim of this is to determine authority for managing URN sub-namespaces.

"urn_snid"
This element contains the URN sub-namespace such as "urn:std".

repeatable no

mandatory no

description This information is used to specify the URN registration process, such as initial registration or updating process, the transfer interface used or the type of confirmation of processed data records.

Syntax <administrative_data>
<delivery>
  <authorization>
   <person_id>F6000123</person_id>
   <urn_snid>urn:nbn:de:089</urn_snid>
  </authorization>
</delivery>
</administrative_data>

"update_status" element

Designation update_status

Attributes "type" with the following content:

"urn_new"
"Initial URN registration" indicator. When integrated with OAI, "urn_new" must be specified when creating new records.

"urn_new_version"
Initial URN registration for a new document version.

"urn_alternative"
Persistent Identifier, which exists for an already registered URN, such as DOI.

"url_update"
When updating a URL, this attribute specifies to be altered URL if several URLs registered.

"url_update_general"
Updating URLs. This attribute must be specified if the record only contains "new" URLs. All registered URLs will be deleted and replaced with the "new" URL(s).

"url_delete"
This attribute is set if the URL is to be deleted.

"url_insert"
This attribute is set if a new URL is to be inserted (in the sense of a subsequent URL registration process).

Sub-elements none

repeatable no

mandatory yes

description This element is used to specify the registration process type.

Syntax <update_status type="urn_new"/>

"transfer" element

Designation transfer

Attributes "type" with the following content:

"email"

"http"

"ftp"

Sub-elements none

repeatable no

compulsory no

description Transfer interface or protocol details.

Syntax <transfer type="email"/>

"resupply" element

Designation resupply

Attributes "type" with the following content:

"email"

"ftp"

Sub-elements none

repeatable no

mandatory no

description Target address for information on processing status (success or error).

Syntax <resupply type="email"/>

"administrative_data" example

"record" element group

"record" element

Designation record

Attributes none

Sub-elements

"identifier"
With the "identifier" element URNs and URLs with different attributes are included.

"isVersionOf"
With the "isVersionOf" element, a URN for the new document version can be created.

"hasVersion"
The "hasVersion" element contains a Persistent Identifier such as a DOI which exists in addition to a URN and should be registered at the German National Library.

"resource"
The "resource" element, with its sub-elements "identifier" and "format", is used to illustrate the context of the URN and the URL.

"isPartOf"
The "isPartOf" element is used for recording information on URNs and URLs for part documents.

repeatable yes

mandatory yes

description The "record" element covers URN-URL relationships of the objects.

Syntax <record>
[...]
</record>

"identifier" element

Designation identifier

Attributes
The "identifier" element has the following attributes:
"scheme"
With the "scheme" attribute, the URN or URL belonging to the object is captured

The attribute for specifying the URN can have the following values:
  "urn"
  "urn:nbn"
  "urn:nbn:de"
  "urn:nbn:at"
  "urn:nbn:ch"

The attribute for specifiyng the URL has the following compulsory value:
  "url"

and in addition, the following optional attributes:

"type"
The optional attibute serves to identify a URL as a frontpage URL and has the value "frontpage".

"status"
This attribute is optional and is used in context of the update process to characterise a URL as "old" or "new". It can have the following alternative values:
  "new"
  "old"

"role"
This optional attribute indicates a URL as a "master URL" and is initially designated during the resolution procedure. This would be the case if more than one URL is registered against a single URN.
The attribute has the following value:
  "primary"

"origin"
This optional attribute specifies the origin of the object.
This attribute can have the following alternative values:
  "original"
  "external"
  "archive"

"target"
The indication target="transfer"" is optional and is used to identify a URL as a transfer URL for transferring an object in the legal deposit system of the German National Library.

Sub-elements none

repeatable yes

mandatory yes

description The "identifier" element contains information about a URL or URN. It is specified in more detail by means of mandatory and several optional attributes.

Syntax (Selection) <identifier scheme="urn:nbn:de">
  [...]
</identifier>
or
<identifier scheme="url">
  [...]
</identifier>
or
<identifier scheme="url" type="frontpage" role="primary" origin="archive">
  [...]
</identifier>

"isVersionOf" element

Designation isVersionOf

Attributes The namespace of the Persistent Identifier is determined by means of the "scheme" attribute. This attribute can have the following values:

"urn"

"urn:nbn"

"urn:nbn:de"

"urn:nbn:at"

"urn:nbn:ch"

Sub-elements none

repeatable no

mandatory no

description The optional "isVersionOf" element contains the Persistent Identifier of the new document version.

Syntax <isVersionOf scheme="urn:nbn:de">
[...]
</isVersionOf>

"hasVersion" element

Designation hasVersion

Attributes The namespace of the Persistent Identifier is determined by means of the "scheme" attribute. This attribute can have the following values:

"urn"

"urn:nbn"

"urn:nbn:de"

"urn:nbn:at"

"urn:nbn:ch"

"doi"

"handle"

"urn:issn"

"urn:isbn"

Sub-elements none

repeatable no

mandatory no

description The "hasVersion" element is optional and provides details as to whether, in addition to an already registered Persistent Identifier, such as "urn:nbn:de:...", a further Persistent Identifier such as DOI exists. This "external" Persistent Identifier must be specified using "scheme".

Syntax <hasVersion scheme="doi">
[...]
</hasVersion>

"resource" element

Designation resource

Attributes none

Sub-elements

"identifier"
the "identifier" element captures the URL of the object. For this reason, the scheme="url" attribute must be used. (see "identifier" element)

"format"
The "format" identifier is used to capture the object's mime type.

repeatable yes

mandatory no

description The "resource" identifier encapsulates the "identifier" sub-element with the scheme="url" attribute, and "format" is used to capture the object's URL and Mime Type (file format).

Syntax <resource>
  <identifier scheme="url">
   [object URL]
  </identifier>
  <format scheme="imt">
   [object's mime type]
  </format>
</resource>

"format" element

Designation format

Attributes The "format" element has the following attribute:
"imt", which contains the object's mime type as a value.

Sub-elements none

repeatable no

mandatory no

description The "format" element is used to cover the object's Mime Type (file format).

Syntax <format scheme="imt">
[Object mime type]
</format>

"isPartOf" element

Designation isPartOf

Attributes none

Sub-elements

"identifier"

"resource"

repeatable yes

compulsory no

description The "isPartOf" element includes information about URNs and URLs of part objects.

Syntax <isPartOf>
[...]
</isPartOf>

"record" example

<epicur>

<administrative_data>
[...]

<update_status type="urn_new"/>

[...]
</administrative_data>

<record>

<identifier scheme="urn:nbn:de">urn:nbn:de:gbv:089-3321752945</identifier>

<resource>

<identifier scheme="url" type="frontpage">http://edok01.tib.uni-hannover.de/edoks/e01dh01/</identifier>

<format scheme="imt">text/html</format>

</resource>

<isPartOf>

<identifier scheme="urn:nbn:de">urn:nbn:de:gbv:089-332175-teil1</identifier>

<resource>

<identifier scheme="url">http://edok01.tib.uni- hannover.de/edoks/e01dh01/teil1.pdf</identifier>

<format scheme="imt">application/pdf</format>

</resource>

</isPartOf>

<isPartOf>

<identifier scheme="urn:nbn:de">urn:nbn:de:gbv:089-332175-teil2</identifier>

<resource>

<identifier scheme="url">http://edok01.tib.uni-hannover.de/edoks/e01dh01/teil2.ps</identifier>

<format scheme="imt">application/postscript</format>

</resource>

</isPartOf>

</record>

</epicur>


02.01.2008

Designation	epicur
Attributes	none
Sub-elements	"administrative_data" "record"
repeatable	no
mandatory	yes
description	The root element encapsulates the XML document.
Syntax	<epicur> <administrative_data> [...] </administrative_data> <record> [...] </record> </epicur>

Designation	administrative_data
Attributes	none
Sub-elements	"delivery"
repeatable	no
mandatory	yes
description	The element incorporates the verification data, the specification of the URN reporting process, the transfer interface used and type of confirmation concerning the processed data records.
Syntax	<administrativ_data> <delivery> [...] </delivery> </administrative_data>

Designation	authorization
Attributes	none
Sub-elements	"person_id" Authorisation ID for a person. "system_id" Alternative to "person_id". This is an ID that only used in conjunction with automated URN reporting process. "urn_snid" This element contains the NBN sub-namespace such as urn:nbn:de:gbv:089. The aim of this is to determine authority for managing URN sub-namespaces. "urn_snid" This element contains the URN sub-namespace such as "urn:std".
repeatable	no
mandatory	no
description	This information is used to specify the URN registration process, such as initial registration or updating process, the transfer interface used or the type of confirmation of processed data records.
Syntax	<administrative_data> <delivery> <authorization> <person_id>F6000123</person_id> <urn_snid>urn:nbn:de:089</urn_snid> </authorization> </delivery> </administrative_data>

Designation	update_status
Attributes	"type" with the following content: "urn_new" "Initial URN registration" indicator. When integrated with OAI, "urn_new" must be specified when creating new records. "urn_new_version" Initial URN registration for a new document version. "urn_alternative" Persistent Identifier, which exists for an already registered URN, such as DOI. "url_update" When updating a URL, this attribute specifies to be altered URL if several URLs registered. "url_update_general" Updating URLs. This attribute must be specified if the record only contains "new" URLs. All registered URLs will be deleted and replaced with the "new" URL(s). "url_delete" This attribute is set if the URL is to be deleted. "url_insert" This attribute is set if a new URL is to be inserted (in the sense of a subsequent URL registration process).
Sub-elements	none
repeatable	no
mandatory	yes
description	This element is used to specify the registration process type.
Syntax	<update_status type="urn_new"/>

Designation	transfer
Attributes	"type" with the following content: "email" "http" "ftp"
Sub-elements	none
repeatable	no
compulsory	no
description	Transfer interface or protocol details.
Syntax	<transfer type="email"/>

Designation	resupply
Attributes	"type" with the following content: "email" "ftp"
Sub-elements	none
repeatable	no
mandatory	no
description	Target address for information on processing status (success or error).
Syntax	<resupply type="email"/>

<epicur>
	<administrative_data>
		<delivery>
			<authorization>
				<person_id>F6000123</person_id> or <system_id>034jf0249r843</system_id>
				<urn_snid>urn:nbn:de:gbv:089</urn_snid> or <urn_nid>urn:issn</urn_nid>
			<authorization>
			<update_status type="urn_new"/>
			<transfer type="http"/>
			<resupply type="email"/>
		</delivery>
	</administrative_data>
[...]
<epicur>

Designation	record
Attributes	none
Sub-elements	"identifier" With the "identifier" element URNs and URLs with different attributes are included. "isVersionOf" With the "isVersionOf" element, a URN for the new document version can be created. "hasVersion" The "hasVersion" element contains a Persistent Identifier such as a DOI which exists in addition to a URN and should be registered at the German National Library. "resource" The "resource" element, with its sub-elements "identifier" and "format", is used to illustrate the context of the URN and the URL. "isPartOf" The "isPartOf" element is used for recording information on URNs and URLs for part documents.
repeatable	yes
mandatory	yes
description	The "record" element covers URN-URL relationships of the objects.
Syntax	<record> [...] </record>

Designation	identifier
Attributes	The "identifier" element has the following attributes: "scheme" With the "scheme" attribute, the URN or URL belonging to the object is captured The attribute for specifying the URN can have the following values: "urn" "urn:nbn" "urn:nbn:de" "urn:nbn:at" "urn:nbn:ch" The attribute for specifiyng the URL has the following compulsory value: "url" and in addition, the following optional attributes: "type" The optional attibute serves to identify a URL as a frontpage URL and has the value "frontpage". "status" This attribute is optional and is used in context of the update process to characterise a URL as "old" or "new". It can have the following alternative values: "new" "old" "role" This optional attribute indicates a URL as a "master URL" and is initially designated during the resolution procedure. This would be the case if more than one URL is registered against a single URN. The attribute has the following value: "primary" "origin" This optional attribute specifies the origin of the object. This attribute can have the following alternative values: "original" "external" "archive" "target" The indication target="transfer"" is optional and is used to identify a URL as a transfer URL for transferring an object in the legal deposit system of the German National Library.
Sub-elements	none
repeatable	yes
mandatory	yes
description	The "identifier" element contains information about a URL or URN. It is specified in more detail by means of mandatory and several optional attributes.
Syntax (Selection)	<identifier scheme="urn:nbn:de"> [...] </identifier> or <identifier scheme="url"> [...] </identifier> or <identifier scheme="url" type="frontpage" role="primary" origin="archive"> [...] </identifier>

Designation	isVersionOf
Attributes	The namespace of the Persistent Identifier is determined by means of the "scheme" attribute. This attribute can have the following values: "urn" "urn:nbn" "urn:nbn:de" "urn:nbn:at" "urn:nbn:ch"
Sub-elements	none
repeatable	no
mandatory	no
description	The optional "isVersionOf" element contains the Persistent Identifier of the new document version.
Syntax	<isVersionOf scheme="urn:nbn:de"> [...] </isVersionOf>

Designation	hasVersion
Attributes	The namespace of the Persistent Identifier is determined by means of the "scheme" attribute. This attribute can have the following values: "urn" "urn:nbn" "urn:nbn:de" "urn:nbn:at" "urn:nbn:ch" "doi" "handle" "urn:issn" "urn:isbn"
Sub-elements	none
repeatable	no
mandatory	no
description	The "hasVersion" element is optional and provides details as to whether, in addition to an already registered Persistent Identifier, such as "urn:nbn:de:...", a further Persistent Identifier such as DOI exists. This "external" Persistent Identifier must be specified using "scheme".
Syntax	<hasVersion scheme="doi"> [...] </hasVersion>

Designation	resource
Attributes	none
Sub-elements	"identifier" the "identifier" element captures the URL of the object. For this reason, the scheme="url" attribute must be used. (see "identifier" element) "format" The "format" identifier is used to capture the object's mime type.
repeatable	yes
mandatory	no
description	The "resource" identifier encapsulates the "identifier" sub-element with the scheme="url" attribute, and "format" is used to capture the object's URL and Mime Type (file format).
Syntax	<resource> <identifier scheme="url"> [object URL] </identifier> <format scheme="imt"> [object's mime type] </format> </resource>

Designation	format
Attributes	The "format" element has the following attribute: "imt", which contains the object's mime type as a value.
Sub-elements	none
repeatable	no
mandatory	no
description	The "format" element is used to cover the object's Mime Type (file format).
Syntax	<format scheme="imt"> [Object mime type] </format>

Designation	isPartOf
Attributes	none
Sub-elements	"identifier" "resource"
repeatable	yes
compulsory	no
description	The "isPartOf" element includes information about URNs and URLs of part objects.
Syntax	<isPartOf> [...] </isPartOf>

<epicur>
	<administrative_data> [...]
		<update_status type="urn_new"/>
	[...] </administrative_data>
	<record>
		<identifier scheme="urn:nbn:de">urn:nbn:de:gbv:089-3321752945</identifier>
		<resource>
			<identifier scheme="url" type="frontpage">http://edok01.tib.uni-hannover.de/edoks/e01dh01/</identifier>
			<format scheme="imt">text/html</format>
		</resource>
		<isPartOf>
			<identifier scheme="urn:nbn:de">urn:nbn:de:gbv:089-332175-teil1</identifier>
				<resource>
					<identifier scheme="url">http://edok01.tib.uni- hannover.de/edoks/e01dh01/teil1.pdf</identifier>
				<format scheme="imt">application/pdf</format>
				</resource>
		</isPartOf>
		<isPartOf>
			<identifier scheme="urn:nbn:de">urn:nbn:de:gbv:089-332175-teil2</identifier>
			<resource>
					<identifier scheme="url">http://edok01.tib.uni-hannover.de/edoks/e01dh01/teil2.ps</identifier>
					<format scheme="imt">application/postscript</format>
			</resource>
		</isPartOf>
	</record>
</epicur>