Key

The key element identifies a metadata record in the ANDS Collections Registry. A key must be unique and persistent in the sense that, once allocated, it does not change.

Keys are created or assigned in the source system. They also form part of the public technical infrastructure of the ANDS Registry; they are searchable but are not displayed in Research Data Australia. They are used as the mechanism for linking related objects to each other, and for update and delete functions as part of the harvesting and Registry ingest process.

Note that the key does not identify the object being described, only the record containing a description of the object.

Preventing accidental overwriting of records

If a newly harvested record has the same key as an existing record from the same Data Source, it is treated as an updated record, and overwrites (replaces) the existing record.

However, if the newly harvested record has the same key as an existing record from a different Data Source, the key re-use is considered to be an error, and the new record is rejected. The Harvest Log will display an error message, and you will need to change the key of the problem record before it can be ingested.

Error message example: Registry Object with key hdl:1959.4/004_41 already exist in a different datasource

It is important to note that this overwrite prevention function does not operate across all environments. When ingesting into Sandbox, the overwrite prevention function only checks Sandbox for duplicate keys. When ingesting into Production, the overwrite prevention function only checks Production for duplicate keys.

It is good practice to start using properly formed unique keys for your records as early as possible.

RIF-CS best practice guidelines

How to create keys

Data providers need to decide whether to mint ANDS persistent handle identifiers, use existing persistent identifiers available in their existing systems, or create local keys. ANDS has no preference as long as these principles are followed:

Principles for keys

Each registry object must have a key.
Each key must be unique at least within its context of use (that is, in the ANDS Collections Registry).
Keys should be persistent, that is, not change once allocated.
Content providers are responsible for the uniqueness and persistence of the keys they supply.
A key may be any unique string.
A key may be, but is not required to be, a URL.
Keys should preferably be globally unique to support discovery in federated global registries.

Option—Minting persistent handle identifiers for use as keys

Guaranteed persistent unique keys can be created by minting persistent handle identifiers (using either the ANDS persistent identifier service for handles or an equivalent). This approach implies a commitment to maintaining the currency of the location component of the key into the future.

For more information, see Identify My Data, the Identify My Data Guide, or technical documentation for this ANDS machine-to-machine (M2M) service.

Option—Creating local keys

If minting persistent handle identifiers to use as metadata record keys is not a suitable solution for a data provider, local primary keys or identifiers may be used, although these cannot be guaranteed to be globally unique. These keys should not be changed in the local system once created.

Local keys can be programmatically enhanced by adding a server or domain name from your own institution, or some other unambiguous and unique identifier, to an existing object identifier.

Example: myrepository.myedu.au/mycollectionidentifier

Keys must be 512 characters or less, and only 255 characters can be displayed. Keys cannot include ampersands (the & character). Contact services@ands.org.au if you have technical questions about what keys can be accepted by ANDS systems.

Keys for party records

Each record provided to ANDS, including any party record, should contain a unique key of its own.

One way to construct a party key is to use a local unique identifier for the person or group that is maintained internally by the institution or agency, such as a staff number or username. That locally unique identifier should be prepended with the provider's domain name and a trailing slash to make it globally unique.

Example: myuni.edu.au/s3799332

The NLA party identifier must NOT be used as the record key. If the NLA party identifier for a person or a group is known, it may be provided in the <identifier> element. This will allow any records about the same party (whether sourced from the National Library of Australia or from within the ANDS Registry) to be displayed together in Research Data Australia.

RIF-CS examples

An ANDS persistent handle identifier:

An actionable (resolvable) ANDS persistent handle identifier:

<key>http://hdl.handle.net/102.100.100/8</key>

A local key prepended by the domain name of the provider:

<key>myuni.edu.au/s3799332</key>

Date	Change history
April 2010	Consultation draft
26 October 2010	Changed recommendations for keys for parties, additional information about minting ANDS persistent identifiers
15 April 2011	Corrected to state that keys are searchable
18 July 2011	Added information about overwrite prevention function, simplified key information
20 Sept 2011	Added information about maximum length permitted for keys

Please send any feedback on this page to guides@ands.org.au