Skip to content

Identifier Minting Service with MINID Client

Authors: * Philippe Rocca-Serra * Mike D'Arcy

Maintainers: Philippe Rocca-Serra

Version: 1.0

License: CC0 1.0 Universal (CC0 1.0) Public Domain Dedication

Table of Contents

  1. Main Objectives
  2. Graphical Overview of the FAIRification Recipe Objectives
  3. Installing the minid 2.0 client
  4. Minid Client Configuration
  5. Minid Client Usage
  6. Authors
  7. License

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.

Graphical Overview of the FAIRification Recipe Objectives

drawing

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/

installing with pip

pip3 install --pre minid

building from source

use the dev branch to obtain to source minid github repository

Configuration

  1. 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
  1. Create a GlobusID account

drawing

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.

  1. 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

bash $ minid login

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

drawing

followed by:

drawing

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

drawing

While the terminal will show the following:

bash You have been logged in.

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

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>.

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"
      }
  ]

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 get 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.

References:

  1. Madduri R, Chard K, D’Arcy M, Jung SC, Rodriguez A, Sulakhe D, et al. (2019) Reproducible big data science: A case study in continuous FAIRness. PLoS ONE 14(4): e0213013. https://doi.org/10.1371/journal.pone.0213013

  2. https://minid.readthedocs.io/en/develop/identifiers.html#minids-vs-handles