|HOME | HANDBOOK | FACTSHEETS | FAQs | RESOURCES | USERS | NEWS | MEMBERS AREA|
Table of Contents Previous Chapter: 8 Registration Agencies Next Chapter: Glossary of Terms
This Chapter summarises common procedures and rules for the registration and maintenance of DOI® names and associated metadata. Registration Agencies will adopt their own detailed operating procedures and these should be consulted in addition to this general guide.
© International DOI Foundation Last updated: December 13, 2012
The DOI Directory is a virtual service consisting of handle services and web proxies located and configured to provide highly reliable handle resolution, administration, and backup for all DOI names, regardless of the varying administrative arrangements of the Registration Agencies. This approach provides the flexibility RAs need to develop individual business models and meet customer requirements while guaranteeing reliable overall service.
The directory is comprised of local handle services (LHS) that include multiple handle sites. Each service contains a primary site, and at least one secondary (mirror) site. Some of the sites are managed by Registration Agencies that have chosen to run their own local handle services. The IDF requires each primary site to have a secondary site run by the IDF. An RA that does not wish to maintain its own handle service may opt to use the DOI® System's LHS managed by CNRI and known as the Default service, described below in Section 9.1.2.
The Default service primary and one of the secondaries are housed at a web hosting facility with a 99% uptime guarantee. The other secondary currently resides at CNRI. Running a separate handle service and using the Default service both require the Directory Manager to create and assign prefixes.
Note that the Directory infrastructure also includes proxy servers (all at the domain name dx.doi.org) with a load balancing system that spreads the load evenly across all of them. Proxy servers are housed both at the hosting site, and also at facilities controlled by RAs, but which use CNRI software and participate in the load balancing system.
9.1.1 DOI prefix assignment
A prefix is a unique string that makes up the first part of a DOI name and is stored as a handle in the Handle System's Global Handle Registry® (e.g., 0.NA/10.1000). Registration Agencies may receive and assign as many prefixes as they require.
All DOI name prefixes begin with 10, and are assigned in sequential order; no reserved prefixes may be requested. The second part of a DOI name is called the suffix and is the local string assigned by the owner or organization acting on their behalf (e.g., 10.1000/34004JFR). The prefix and suffix are separated by a forward slash(/). See Chapter 2, Numbering for suggested guidelines for suffix numbering.
It is recommend that prefixes are assigned at an appropriate level to deal with business requirements. Typically, a Registration Agency may issue one prefix per customer, but it might also be appropriate to issue a prefix per brand, or to some recognizable cluster of products (e.g. a publisher imprint). The choice is the RA's, but IDF and/or other RAs can discuss requirements and make recommendations.
Each RA will be allotted prefixes as a block of sequential numbers that have no special meaning. Each RA, especially those running their own local handle service, will need to understand the basic set up of their prefixes. Each prefix has 'service information' associated with it. This service information is the map/layout of the handle service. The service information is incorporated in a service handle (another level of indirection for ease of administration).
A prefix will have the following values: (Example)
Data Value: 100:HS_ADMIN 0.NA/10:200 (CNRI admin that points to another handle)
Data Value: 101:HS_ADMIN 0.NA/10.1201:200 (RA admin that points to a group within the prefix record see next in the list)
Data Value: 200:HS_VLIST (Group/list of administrators)
Data Value: 300:HS_PUBKEY (Public key for local server administration)
Data Value: 1:HS_SERV 0.SERV/10.1 (Service handle)
CNRI maintains administrative permission for the prefix as well as the RA. This is intended as backup for administration. Administration of DOI names will require the use of an admin DOI. Each admin DOI will begin with 10.1.admin/ or similar, differing slightly for each RA's LHS. It is the responsibility of the RA to inform CNRI and the IDF in the event of any major transaction that could possibly interrupt the mirroring mechanism. It is also the responsibility of the RA to inform CNRI of any configuration changes in their LHS. Information concerning prefix assignment, including prefix allocation and administration services, is provided to RAs by the Directory Manager (contact firstname.lastname@example.org).
9.1.2 Using the Default service
If an RA decides to use the Default service and is ready for a prefix, or block of prefixes, the RA must contact the Directory Manager. Each prefix or set of prefixes will have a user name and password associated with them, which is required for authentication when depositing DOI names. Currently there is a web form for depositing DOI names one at a time or in batch mode. The pages are located on a secure server managed by CNRI. The format for batch files is very simple. One line consists of the DOI name, a space, and then the URL. An example might be:
There is also a client side Java batch application that can be automated and run from an RA's site. This is available for download from the DOI.ORG® website. The instructions are included in the distribution. RAs may also develop their own client applications for depositing DOI names. The necessary Handle System® client libraries in Java and C are both available from the HANDLE.NET website.
Whether an RA chooses to use the Default service or run their own LHS as described below, it is essential to decide on what to identify at what levels of granularity, what information to associate with each identifier, work flow, permissions, etc. at the outset. At the current time there is no metadata database or mechanism for depositing metadata in the DOI Directory. See Section 9.14 below for an example of how an RA might want to configure their own metadata deposit process.
9.1.3 Running a local handle service
If an RA chooses to install and use a local handle service (LHS) for DOI names, the Directory Manager will still create the prefixes, however, there are additional steps on the part of the RA.
The first step is to download the server distribution (current version is 7). Next, the SimpleSetup script is run, per the instructions which are included in the distribution. To set up and manage a local handle service takes a system administrator-type person. The handle server is written in Java and can run on Windows or Unix, however it is recommended the computer be of server-type quality. The handle server must have an Internet presence; that is, it cannot be run behind a firewall unless the ports (2641 and 8000) required by the handle server are open to incoming and outgoing requests.
The SimpleSetup script will create a file called sitebndl.bin that will contain the service information for the local handle service. As per the instructions in the distribution, RAs will need to send the file to email@example.com (or directly to the Directory Manager at firstname.lastname@example.org). Name, organization name, and that fact that the request is coming from an IDF RA is important so that the Directory Manager knows to create prefixes that begin with 10. Each prefix is created in the GHR. The prefix includes information that uniquely identifies each local handle service, such as IP address and the server's public key. The GHR uses this information in determining where to send DOI name resolution requests.
At this point there maybe some discussion on the type of authentication an RA will want to use. The Handle System uses either private/public key or secret key. Permission to create DOI names is at the prefix level but each DOI name has its own administrator (usually a reference to a group in the prefix record). Additional technical information can be found in the Handle System Technical Manual.
It is IDF policy that RAs will be responsible for modification of the configuration of their handle servers to allow a secondary server installation at CNRI. The secondary server will house a complete database of the RA server's DOI names. This requires a minor change in the server's configuration file. This will be coordinated by the Directory Manager. After setup is complete a cron job will be created to check to see if the secondary server is able to connect to your server. If there is problem with the connection (i.e. your server is shut down) the RA will be notified by email and expected to correct the problem as soon as possible.
Choosing the option of running your own local handle service will require more technical expertise on the part of the RA. If you have technical difficulties, the Directory Manager will be there to help. It is not much different than setting up any other kind of server, other than that it will probably be less familiar to system administrators than web servers or mail servers.
Running a local handle service may the best choice for RAs who wish to have immediate control of business-critical infrastructure components such as DOI registration; RAs who plan to implement high performance standards for administration and resolution by choosing levels of performance appropriate to their application; RAs who are willing and able to provide IDF with an escrow copy of the required DOI deposit data without impeding their business; and RAs who wish to move rapidly to an "operating federation" structure, where the bulk of costs and operational income are borne by the RAs rather than by IDF. The fundamental assumption that "membership fees support development until operating federation can take over" is assumed to be still valid, but IDF seeks to encourage the migration.
If an RA is interested in running a local handle service it is wise to schedule a technical overview meeting with CNRI staff. To set this up or to answer any questions please send email to the Directory Manager at email@example.com.
9.1.4 Registering a DOI name with associated metadata
Registration Agencies support registration of DOI names with associated metadata declaration, i.e. using a DOI® Application Profile. Individual Registration Agencies develop their own workflow and procedures for the management of DOI name registration, and metadata deposit and maintenance, and provide their own information to their community of registrants.
The following procedure is as an example of the current process followed by an individual RA for the registration of DOI names with declared metadata. This procedure allows for the batch registration of DOI names and associated metadata records into a DOI System Central Metadata Directory run by the Registration Agency; this directory can subsequently be queried. The batch file format currently in use is XML as defined by a specific XML Schema, and submission is via HTTP POST. Security is HTTP basic authentication; PGP encryption will be added later. Batch receipt is confirmed to the sender via email.
Metadata Creation: The Registrant prepares XML batch files in accordance with the Schema; these are further constrained by a set of rules for the data, which define the expected content of each metadata element. An XML batch may contain metadata for hundreds of DOI names. The development and implementation of quality control measures used to ensure the validity of the metadata content are the responsibility of the Registrant. Quality control and data checking can be assisted by processes put in place in the RA's metadata collection process.
Metadata Collection: The XML is validated upon receipt against the Schema. If the XML does not parse, the batch is refused; the Registrant must correct the XML and resubmit the batch. XML batches are submitted to a named HTTP server via HTTP POST to a Java "servlet", which parses and validates the XML file, and notifies the Registrant in real time whether or not the XML is valid and has been accepted. The submission process captures and verifies a DOI system prefix holder login and password prior to validating the XML. The XML files themselves contain timestamps used as identifiers of the batch; should the Registrant so wish, each DOI name record may have its own timestamp.
DOI Name Deposit: The servlet then deposits each DOI name and its corresponding URL into the DOI system, adding timestamp data value. If the DOI name is not new and therefore already exists in the DOI system, the timestamp is key to determining whether the DOI name data being contributed is newer than the data that is already in the system; if so, the existing DOI name data is updated. A log file also written in XML is created for each batch, indicating the total number of DOI name records in the batch, the number of successful deposits into the DOI system, and the number of failures. For each failure, the DOI name is provided, along with the reason for the failure. While DOI system failures may be the result of system errors, they are most typically caused by an attempt to overwrite existing DOI name data with older data.
Metadata Database Record Generation: The original XML batch files, along with the log files for the batches, are made available daily to the metadata database deposit process, where they are indexed and then made available for searching. A final XML log file is generated to indicate the success of the database deposit (again, failures are due primarily to network or system errors) combined with those from the DOI name deposit process, and this combined XML batch diagnostic is emailed to the Registrant. The entire metadata collection process is expected to be completed and reported to the Registrant in as close to real time as possible; 24 hours is currently seen as a reasonable target time. However, when Registrants initially make deposits, there are large amounts of legacy material and coordination is needed on when the legacy batches are deposited or system performance can be affected.
Data Querying: The metadata database (MDDB) may be queried by submitting a batch file of known metadata fields in a specified format, currently pure ASCII text on separate lines, with fields delimited by vertical bars. The batch interface will query the database and return the corresponding DOI names (if known), or a diagnostic message. Batch query files are submitted by HTTP POST to a named HTTP server.
9.1.5 Transferring DOI names from one registrant to another
If a compilation of multiple assigned DOI names (for example, a journal containing a collection of articles; an imprint; a recording catalogue; etc) is transferred from one RA to another, the DOI names within that compilation are transferred as well. Each RA will develop appropriate procedures for proper transfers. Transfers may be a sale, or any form of exchange, commercial or otherwise. If the new owner is not already an RA, special arrangements may have to be made appropriate to the case; consult the IDF for guidance if necessary.
The individual DOI names stay the same, i.e., what the DOI name identifies is not changed. This is a fundamental requirement. The DOI name prefix does NOT change (recall that a prefix is not meaningful, but is initially assigned to a registrant for convenience in generating DOI names only; no reverse look-up can be inferred to a prefix). The administrative value is changed in order for the new owner to modify its data values (most likely the URL value). Both registrants involved in the transfer need to send email to the Directory Manager at firstname.lastname@example.org giving permission for the transfer. The Directory Manager will assist RAs to ensure an efficient and successful outcome.
9.1.6 Transferring DOI names from one Registration Agency to another
The IDF's Policy on Registration Agency collaboration notes that customers may, if they wish, use more than one RA service: but note that RA services vary and customers won't necessarily have access to the same services if they move.
The foremost technical issue in transfer is the one-to-one relation of prefix to local handle service. Therefore, RAs should allocate at least one separate prefix for each customer, and where appropriate more than one, since the fundamental constraint is that all DOI names under a given prefix must reside in the same handle service (this general architecture is a logical and efficient approach to a distributed service and is far from unique to the Handle System).
Moving an entire prefix worth of DOI names from one service to another is easy. Splitting control of a prefix between two administrative bodies who both use the same handle service (i.e., when it has not been possible to foresee a split by issuing seperate prefixes) is also possible but more complex; in general there are two solutions: (1) leave it with one or the other service (or the DOI default handle service run by CNRI on behalf of IDF) and split up the administration, such that the managers of one service allowed the 'foreign' admins access; or (2) alias all the DOI names under the old prefix to DOI names under a new prefix controlled by the new RA. The old DOI names don't have to be maintained other than ensuring resolution to the new DOI names.
All of the above is strictly from a DOI system point if view and does not address any internal workflow issues or value-added services that the RAs provide that interact with handle administration, which would of course be specific to the RA.
9.1.7 DOI system® error messages
It is inevitable that in adoption of DOI system technology, some mistakes or misunderstandings will occur. This may include actions which result in an attempted resolution not being successful; it is very important that such errors are detected and corrected. Automated procedures for common errors are possible in some cases, but a simple procedural agreement has been implemented and is in place. It is likely that the bulk of the error reports will go to RAs which represent the majority of deposits the current wording therefore reflects a typical message, but other RAs will probably use similar procedures.
"Thank you for reporting this error. It has been forwarded to the appropriate DOI name registrant contact for action. Note that if the item the DOI name identifies is new the DOI name may have been unintentionally made public before being registered with the DOI system and may be available later".
9.1.8 Procedures for prefix allocation and DOI name deposit
More detail on DOI name prefix allocation, and the specific DOI Directory services and sites, is available to IDF Members.
The Handle System® is a component of the Digital Object Architecture developed by CNRI. It provides a means for uniquely identifying Digital Objects ("DOs") and other network resources and for using the identifiers, known as handles, to store and retrieve records containing state information about the DOs. It also provides an administrative mechanism for managing identifiers over time. The DOI system uses the Handle System and inherits the underlying policies and procedures of that system. IDF has licensed rights from CNRI to technology and software, including copyright in Local Handle System software, U.S. Patent No. 6,135,646, the Handle System and Global Handle Registry® trademarks, and certain know-how relating to the Handle System Technology, and pursuant to its Handle System Technology Commercial License Agreement with CNRI, IDF is authorized to sublicense limited rights to the Handle System Technology.
CNRI is making the Handle System technology, specifically the HANDLE.NET® Software, available on a cost recovery basis to organizations and individuals for provision of handle resolution services. This is being done in such as way as to maintain the integrity of the system, while supporting the overall Handle System operation. All individuals and organizations that wish to provide resolution services using the Handle System technology, including RAs, must register as Local Handle Service (LHS) administrators and enter into an agreement with CNRI for this purpose. In most cases, this can be accomplished over the Internet.
9.2.1 Requirements for operating a local handle service
Maintaining overall integrity of the Handle System entails ensuring that each of the following conditions is met by LHS administrators, who must agree to operate their resolution services during the period while the authorization is in effect. The term "system" as used below refers to those LHS components run by each LHS administrator, and the interaction of these components with the Global Handle Registry (GHR) and the users of the LHS. Operational goals for LHS administrators include:
9.2.2 Requirements for providers of resolution services
Resolution service providers are responsible for taking the necessary steps to ensure the proper maintenance of their DOI prefixes and DOI names, including the following:
A requirement for compatibility test suite compliance covering performance, security and operations may be introduced.
9.2.3 Developing Handle System client software
An organization or individual developing Handle System client components is encouraged to use the CNRI client software and the standard interfaces supplied with it, and, in particular, shall not interfere with the normal operation of a local handle service or other client applications in interacting with the Handle System client software or the GHR. In the event an organization or individual wishes to use its own interface software, it is their responsibility to ensure that these interfaces remain compatible with the current Handle System interface specification, which may evolve over time, as posted at the Handle System web site.
9.3.1 Adding values to the Kernel controlled vocabularies
Additional values may be added by RAs to the Kernel controlled vocabularies open lists (see Section 4.3.3) for the following:
RAs who require such additional terms must do this via the IDF, which will arrange for the work to be co-ordinated and undertaken as part of IDF's central role. Terms will also be added into the VMF as part of IDF's activities: RAs do not have to use the procedure described at VMF Process for Registering New Terms or pay fees described there, although the technical process by which Terms are registered and mapped to other Terms in the VMF is the same.
Please provide your full contact details and a brief description of the terms or vocabulary(s) you are requesting to have added or mapped. Include as an attachment the full details of the vocabulary(s). This attachment may be in any suitable form (for example, MS Word, Excel, PDF, XML, RDF).
9.3.2 Adding other new terms to the Data Dictionary
RAs wishing to develop mappings for additional (non-Kernel) metadata terms and schemes are strongly encouraged to follow the same procedure for these too, so that they may be added to the DOI Data Dictionary consistently.
RAs wishing to develop de novo schemes and new metadata applications are also encouraged to take advantage of the IDF's metadata consultancy which is available to all members at no charge.
Reports are confidential to the IDF membership, and subject to the IDF's Data Policy.
Technical information on DOI-specific processes and procedures for RAs is available at http://www.doi.org/RA_Docs/index.html. Information categories, such as metadata mapping and handle data and configuration files, are explained, and a further set of links to individual documents and explanations is provided.
Previous Chapter: 8 Registration Agencies Next Chapter: Glossary of Terms