The Registry File
telling us about your repository

Overview || High-Level Registry File Structure || Metadata || Software || Contact || Organisation || Policy || API || Integration || Discovery

The Registry File is a JSON formatted document which your repository can make available which will allow OpenDOAR to create and update information about your repository automatically in the registry. By maintaining this file you will be able to manage your repository's presence in the registry without manually entering data into the OpenDOAR system.

This page outlines the registry file, and goes into detail on how it should be created and populated

Overview

Below is the full expression of the registry file, with all available fields shown. Later sections will go into detail on each of the sections.

    {
        "last_updated" : "# datestamp of last registry file modification #",

        "register" : {
            "replaces" : "# oarr info uri of repository this one replaces (info:oarr:[identifier]) #",
            "operational_status" : "Trial | Operational",

            "metadata" : [
                {
                    "lang" : "en",
                    "default" : true|false,
                    "record" : {
                        "country_code" : "# two-letter iso code for country #",
                        "twitter" : "# repository's twitter handle #",
                        "acronym" : "# repository name acronym #",
                        "description" : "# free text description of repository #",
                        "established_date" : "# date established #",
                        "language_code" : [# languages of content found in repo (iso-639-1) #],
                        "name" : "# name of repository #",
                        "url" : "# url for repository home page #",
                        "subject" : ["# list of subject classification terms for the repository #"],
                        "repository_type" : ["# list of vocabulary terms for the repository #"],
                        "certification" : ["# list of certifications held by this repository #"],
                        "content_type" : ["# list of vocabulary terms for the content in this repository #"]
                    }
                }
            ],
            "software" : [
                {
                    "name" : "# name of software used to provide this repository #",
                    "version" : "# version of software used to provide this repository #",
                    "url" : "# url for the software/this version of the software #"
                }
            ],
            "contact" : [
                {
                    "role" : ["# contact role with regard to this repository #"],
                    "details": {
                        "name" : "# contact name #",
                        "email" : "# contact email #",
                        "address" : "# postal address for contact #",
                        "fax": "# fax number of contact #",
                        "phone": "# phone number of contact #",
                        "lat" : "# latitude of contact location #",
                        "lon" : "# longitude of contact location #",
                        "job_title" : "# contact job title #"
                    }
                }
            ],
            "organisation" : [
                {
                    "role" : [# organisation roles with regard to this repository #],
                    "details" : {
                        "name" : "# name of organisation #",
                        "acronym" : "# acronym of organisation #",
                        "url" : "# organisation url #",

                        "unit" : "# name of organisation's unit responsible #"
                        "unit_acronym" : "# acronym of unit responsible #",
                        "unit_url" : "# url of responsible unit #",

                        "country_code" : "# two letter country code organisation resides in #",
                        "lat" : "# latitude of organisation/unit #",
                        "lon" : "# longitude of organisation/unit #"
                    }
                }
            ],
            "policy" : [
                {
                    "policy_type" : "# vocabulary term for policy type #",
                    "description" : "# description of policy terms, human readable #",
                    "terms" : ["# list of vocabulary terms describing the policy #"]
                }
            ],
            "api" : [
                {
                    "api_type" : "# api type from known list or free text #",
                    "version" : "# version of the API #",
                    "base_url" : "# base url of API #",

                    "metadata_formats" : [{"prefix" : "# prefix #", "namespace" : "# namespace #", "schema" : "# schema#"}],
                    "accepts" : [# list of accepted mimetypes #],
                    "accept_packaging" : [# list of accepted package formats #]
                }
            ],
            "integration": [
                {
                    "integrated_with" : "# type of system integrated with #",
                    "nature" : "# nature of integration #",
                    "url" : "# url of system integrated with, if available #",
                    "software" : "# name of software integrated with #",
                    "version": "# version of software integrated with #"
                }
            ]
        }
    }

High-Level Registry File Structure

The Registry file consists to a small collection of high-level elements which encapsulate all that we need to know about a repository.

    {
        "last_updated" : "# datestamp of last registry file modification #",

        "register" : {
            "replaces" : "# oarr info uri of repository this one replaces (info:oarr:[identifier]) #",
            "operational_status" : "Trial | Operational",

            "metadata" : [# list of metadata records #],
            "software" : [# list of software components which make up the repository #],
            "contact" : [# list of contacts for the repository #],
            "organisation" : [# list of organisations responsible for the repository #],
            "policy" : [# list of policies the repository implements #],
            "api" : [# list of APIs the repository provides #],
            "integration": [# list of systems the repository integrates with #]
        }
    }

Metadata

The Registry file SHOULD contain one or more metadata records for the repository. Each metadata record provides useful information about the repository of a generally human-readable or human-interest nature, such as the name of the repository or a description. Some of the fields may be suitable for translation or representation in other languages so the metadata part of the registry file allows for multiple metadata records, and a default metadata record which should be considered the primary record.

The consequence of this is that the metadata for a repository can be provided in any language for which there is a suitable translation, and in the event that no particular metadata field is available for that language, the default value can be used.

Consider the following (artificial) metadata record in two languages

FieldStored English (default)Stored SpanishRequested Spanish
NameDigital Academic Repository of the University of NavarraDepósito Académico Digital de la Universidad de NavarraDepósito Académico Digital de la Universidad de Navarra
DescriptionThis is an institutional repository for the University of Navarra. This is an institutional repository for the University of Navarra.
Twitter@darun@darun

The registry has two metadata records, one in English (which is the default) and one in Spanish. If we want to look at the metadata in Spanish, we see the Spanish values where such values exist, and the English values where they do not.

In the metadata section of the registry file, this repository would look like this:

    "metadata" : [
        {
            "lang" : "en",
            "default" : true,
            "record" : {
                "twitter" : "darun",
                "description" : "This is an institutional repository for the University of Navarra.",
                "name" : "Digital Academic Repository of the University of Navarra",
            }
        },
        {
            "lang" : "es",
            "default" : false,
            "record" : {
                "name" : "Depósito Académico Digital de la Universidad de Navarra",
            }
        }
    ]

The full specification for the metadata section of the registry file is as follows

    {
        "lang" : "en",
        "default" : true|false
        "record" : {
            "country_code" : "# two-letter iso code for country #",
            "twitter" : "# repository's twitter handle #",
            "acronym" : "# repository name acronym #",
            "description" : "# free text description of repository #",
            "established_date" : "# date established #",
            "language" : [# languages of content found in repo (names of) #],
            "language_code" : [# languages of content found in repo (iso-639-1) #],
            "name" : "# name of repository #",
            "url" : "# url for repository home page #",
            "subject" : ["# list of subject classification terms for the repository #"],
            "repository_type" : [# list of vocabulary terms for the repository #],
            "certification" : [# list of certifications held by this repository #],
            "content_type" : [# list of vocabulary terms for the content in this repository #]
        }
    }

Subject Classification

A subject classification allows us to specify the subjects covered by the repository in a formal way. OpenDOAR uses an ad hoc mechanism for defining the classifications, and you should check the API documentation to find out how to view the current list of active classifications.

It is RECOMMENDED that where possible and relevant you re-use classification terms that are already in existance

For example, to specify several classifications, you could use:

    "subject" : ["Architecture", "Civil Engineering", "Technology"]

Repository Certification

Repository certifications allow us to determine what policies or practicies the repository has in place, and to quickly locate repositories which meet certain criteria. The core OpenDOAR certifications are:

For example, to specify several of the certifications, you could use:

    "certification" : ["RIOXX", "ISO 16363:2012"]

Repository Content Types

Capturing repository content types allows us to easily categorise and locate relevant repositories. OpenDOAR uses an ad hoc mechanism for defining the content types, and you should check the API documentation to find out how to view the current list of active content types.

It is RECOMMENDED that where possible and relevant you re-use content types that are already in existance

For example, to specify several of the OpenDOAR content types, you could use:

    "content_type" : ["Bibliographic references", "Theses and dissertations"]

Software

The registry file MAY contain one or more records of software that is used to provision the repository

This is intended to denote the software which is actively engaged in providing the repository experience, rather than any supporting infrastructure (e.g. the operating system) or any systems with which the repository is integrated (for that, see the section on Integration), such as a CRIS.

The full specification for the software section of the registry file is as follows

    {
        "name" : "# name of software used to provide this repository #",
        "version" : "# version of software used to provide this repository #",
        "url" : "# url for the software/this version of the software #"
    }

For example, a simple DSpace installation may look like this:

    "software" : [
        {
            "name" : "DSpace",
            "version" : "3.1",
            "url" : "http://www.dspace.org"
        }
    ]

A more complex example which uses several pieces of software to provide the repository might be:

    "software" : [
        {
            "name" : "Fedora",
            "version" : "4.0",
            "url" : "http://www.fedoracommons.info"
        },
        {
            "name" : "Vital",
            "version" : "5.3",
            "url" : "http://www.vtls.com/products/vital"
        }
    ]

Contact

The registry file MAY contain one or more records for contacts for the repository

This is intended to provide end-users of the registry data a way to get in contact with the repository owners with regard to both policies and technical details.

The full specification for the contact section of the registry file is as follows

    {
        "role" : ["# contact role with regard to this repository #"]
        "details": {
            "name" : "# contact name #",
            "email" : "# contact email #",
            "address" : "# postal address for contact #",
            "fax": "# fax number of contact #",
            "phone": "# phone number of contact #",
            "lat" : "# latitude of contact location #",
            "lon" : "# longitude of contact location #",
            "job_title" : "# contact job title #"
        }
    }

Organisation

The registry file MAY contain one or more records for organisations responsible for the repository

This is intended to provide end-users of the registry data a way to effectively geo-locate the repository.

The full specification for the organisation section of the registry file is as follows

    {
        "role" : [# organisation roles with regard to this repository #],
        "details" : {
            "name" : "# name of organisation #",
            "acronym" : "# acronym of organisation #",
            "url" : "# organisation url #",

            "unit" : "# name of organisation's unit responsible #"
            "unit_acronym" : "# acronym of unit responsible #",
            "unit_url" : "# url of responsible unit #",

            "country" : "# country organisation resides in #",
            "country_code" : "# two letter country code organisation resides in #",
            "lat" : "# latitude of organisation/unit #",
            "lon" : "# longitude of organisation/unit #"
        }
    }

Policy

TODO: develop some standard vocabularies for policy terms, so that we can easily search across repositories by them. Right now there are lots of human readable strings, where we should strive for some standardisation

The registry file MAY contain one or more records of policies the repository implements

The following are the core polic types that OpenDOAR is interested in. You SHOULD try to provide policy information for terms in this list, but you MAY provide policies in any other areas

The full specification for the policy section of the registry file is as follows

    {
        "policy_type" : "# vocabulary term for policy type #",
        "description" : "# description of policy terms, human readable #",
        "terms" : [# list of vocabulary terms describing the policy #]
    }

API

The registry file MAY contain one or more records of APIs the repository provides

The following are the main APIs that OpenDOAR is familiar with; if you provide these APIs you MUST use the standard name for them in the api_type field:

If you have an API which is not in this list, you MAY provide your own type definition for it

The basic formulation of an API entry in the registry record is as follows:

    {
        "api_type" : "# api type from known list or free text #",
        "version" : "# version of the API #",
        "base_url" : "# base url of API #"
    }

Some APIs have additional fields that they can provide to improve the discovery experience of end-users of OpenDOAR. The next sections detail the extensions. You MUST NOT provide extensions to the API definition which are not already defined in this document.

OAI-PMH

For Example:

    {
        "api_type" : "oai-pmh",
        "version" : "2.0",
        "base_url" : "http://www.myrepo.edu/oai",
        "metadata_formats" : [
            {
                "prefix" : "oai_dc",
                "namespace" : "http://www.openarchives.org/OAI/2.0/oai_dc/",
                "schema" : "http://www.openarchives.org/OAI/2.0/oai_dc.xsd"
            }
        ]
    }

SWORD

For Example:

{
    "api_type" : "sword",
    "version" : "2.0",
    "base_url" : "http://www.myrepo.edu/swordv2/service-document",
    "authenticated" : true,
    "accepts" : ["application/zip"],
    "accept_packaging" : [
        "http://purl.org/net/sword/package/Binary",
        "http://purl.org/net/sword/package/SimpleZip"
    ]
}

Integration

The registry file MAY contain one or more records of Integrations with other systems that the repository has.

Common kinds of integrations would be with the institutional CRIS system, or single-sign-on. It may also include integration with national systems or agreements with other repositories to mirror content.

The formulation of an Integration's entry in the registry record is as follows:

{
    "integrated_with" : "# type of system integrated with #",
    "nature" : "# nature of integration #",
    "url" : "# url of system integrated with, if available #",
    "software" : "# name of software integrated with #",
    "version": "# version of software integrated with #"
}

Discovery

There are two ways that you can make your registry file discoverable by OpenDOAR

Auto-Discovery

Place a link to the file in your HTML link headers as follows:

    <link rel="oarr" type="application/json" href="[file url]">

Standardised Location

Place your file at a standard location at the root of your repository's domain, with the name oarr.json

So if your repository is at http://www.myrepo.edu/xmlui your registry file would be at http://www.myrepo.edu/oarr.json

This service is running at Cottage Labs. Please contact us if you have technical issues.