4. Minting identifiers with Minid¶

Recipe Overview

Reading Time

10 minutes

Executable Code

Yes

Difficulty

Minting identifiers with Minid

Recipe Type

Hands-on

Audience

Software Developer, Data Scientist

Maturity Level & Indicator

[F+MM-1.1C] [F+MM-1.2C]

Cite me with FCB008

4.1. Main Objectives¶

The main purpose of this recipe is:

To create a persistent, globally unique and resolvable identifier using the Minid client accessing the Minid 2.0 release 2 1.

4.2. Graphical Overview¶

4.3. Capability & Maturity Table¶

Capability	Initial Maturity Level	Final Maturity Level
identifier minting	minimal	repeatable

4.4. FAIRification Objectives, Inputs and Outputs¶

Actions.Objectives.Tasks	Input	Output
service invokation	file	guid

4.5. Installing the minid 2.0 client¶

This is a prerequisite to be able to call the minid API hosted on a server at the following url http://minid.bd2k.org/minid

4.5.1. installing with pip¶

pip3 install --pre minid

4.5.2. building from source:¶

use the dev branch to obtain to source minid github repository

4.6. Configuration¶

prerequisite: create a minig-config.cfg file

As a convenience you need specify this information in a minid configuration file (~/.minid/minid-config.cfg) To do so from the command line, issue the following:

$ mkdir ~/Users/philippe/.minid
$ cd .minid
$ touch minid-config.cfg

Create a GlobusID account

Before using the API you first need to create a globus account

and validate your email address, as part of the registration process. A unique code will be sent to your email address. You must present this code along with your email address when accessing the API.

Accessing minid service from the command line

With the completion of the previous steps, you are now ready to use the minid service. The first thing to do is to invoke to minid login command

$ minid login

This will open the GlobusID login page. Simply enter your credentials obtained from 2.

followed by:

If all goes well, the following browser screen will be shown:

While the terminal will show the following:

You have been logged in.

This means you are now ready to use the minid service from the command line.

4.7. Usage¶

The CLI supports the following simple operations (Note: the --test flag creates names in a test namespace that is removed periodically; remove that flag to create production minids.):

Check a known minid identifier

$ minid check hdl:20.500.12633/1HK1DTv1wPt3a

if everything is setup correctly, the command will return:

Minid:               hdl:20.500.12633/1HK1DTv1wPt3a
Title:
Checksums:           e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 (sha256)
Created:
Landing Page:        https://identifiers.fair-research.org/hdl:20.500.12633/1HK1DTv1wPt3a
EZID Landing Page:   https://ezid.cdlib.org/id/hdl:20.500.12633/1HK1DTv1wPt3a
Locations:           http://example.com/foo.txt

Create a new identifier (the --location option, if provided, must be at the end).

$ minid --register [--title <title>] <file_name> [--locations <loc1>..<locN>]

Update metadata about an identifier:

$ minid --update [--title <title>] [--status <status>] [--obsoleted_by <minid>] [--locations <loc1> <loc2>] <identifier>

View all minid options:

$ minid -h

Landing pages are accessible via the minid website: http://minid.bd2k.org/minid/landingpage/<identifier>.

4.7.1. file manifest format¶

Minids can only be assigned to a single file. In order to assign a minid to a collection of files, we recommend using a BDBag <https://github.com/ini-bdds/bdbag>_ or the minid file manifest format.

The minid file manifest format is a JSON-based format that enumerates a list of files as JSON objects that have the following attributes:

length: The length of the file in bytes.
filename: The filename (or path) relative to the manifest file.
One or more (only one of each) of the following algorithm:checksum key-value pairs:
- md5:<md5 hex value>
- sha256:<sha256 hex value>
- sha512:<sha512 hex value>
url: the URL to the file.

The manifest may be used to create a minid for a collection of files or alternatively as input to the minid batch-register command.

Below is a sample file manifest configuration file:

  [
      {
          "length":321,
          "filename":"file1.txt",
          "md5":"5bbf5a52328e7439ae6e719dfe712200",
          "sha256":"2c8b08da5ce60398e1f19af0e5dccc744df274b826abe585eaba68c525434806",
          "url" : "globus://ddb59aef-6d04-11e5-ba46-22000b92c6ec/share/godata/file1.txt"
      },
      {
          "length": 632860,
          "filename": "minid_v0.1_Nov_2015.pdf",
          "sha256": "cacc1abf711425d3c554277a5989df269cefaa906d27f1aaa72205d30224ed5f",
          "url" : "http://bd2k.ini.usc.edu/assets/all-hands-meeting/minid_v0.1_Nov_2015.pdf"
      }
  ]

4.8. Conclusions¶

Using the Minid service, resources can now generate stable, resolvable identifiers for their digitial documents. The Minid service thus provides a key component to enable interoperability and reusability by ensuring digital assets can be looked up using a standard protocol (HTTP request). The service also supports data integrity checks thanks to the native support of checksumming functions, with sha256 being recommended.

4.9. References¶

4.10. Authors¶

Authors

Name

ORCID

Affiliation

Type

ELIXIR Node

Contribution

Mike d’Arcy

University of Southern California

Writing - Original Draft

Philippe Rocca-Serra

University of Oxford

Writing - Review & Editing