“Referrable” objects

The classes below are used to refer to unique objects on the web based on their URIs.

The classes are supplied to fulfill our needs for the time being, but it may be substituted later if there exists any structure general enough to be used.

Note

TODO: make a nice class diagram

referrable

class referrable

the base class being used to refer to anything “referrable” on the web. Both name and uri properties are required.

name

a human-readable string name of this object.

uri

a string representing the URI-based ID of this object. Can be null (but not recommended), if this Referrable does not have any ID (although it may sound paradoxical).

individual

Any individuals (people, institutions, companies etc.) being referred to through the URI, are represented by the individual class.

For reference to a person, in particular, the person class is used.

class individual

a subclass of referrable being used to identify any individuals (people, institutions, companies etc.).

name

a required property inherited from referrable.name. It would typically reflect what would appear as the “full-name” on the web pages.

uri

a required property inherited from referrable.uri.

  • for an institution/company: the URL for its website (starting with https://)
  • for a person: the ORCID (starting with ORCID:)

Can be null (but not recommended), if this individual does not have any ID.

institution class

class institution

This is a subclass of the individual class, with no additional properties. This class is used to e.g. represent the affiliated institution(s) of a contributor.

Typical “institution” object
{
    "name": "Chaos Software",
    "uri":  "https://www.chaos-software.cc"
}
name

a required property inherited from individual.name. It represents the human-readable expression of this institution.

uri

a required property inherited from individual.uri. It represents the URL (i.e. starting with https://) of the institution.

person

class person

a subclass of individual being used to refer to a person.

Typical “person” object
{
    "name":       "Keisuke S.K. Sehara",
    "lastname":   "Sehara",
    "firstnames": "Keisuke S.K.",
    "uri":        "ORCID:0000-0000-0000-0000",
    "contact":    "kkkkkeeeeiiiissssuuuukkkkeeee@mail.chaos-software.cc"
}

All of the properties described below are necessary.

name

inherited from individual.name. The full name as it would appear on the web pages.

uri

inherited from individual.uri. The ORCID (a string starting with ORCID:) of this person.

lastname

a string representing the last name of this person. This is used to identify the person across the database, especially if the uri property is set to be null.

firstnames

a string representing the first names (i.e. other than the last name) of this person. This is used to identify the person across the database, especially if the uri property is set to be null.

contact

a string representing the contact information of this person.

It is recommended to contain the e-mail address of the person here, but it can be the mailing address, too.

This field can well be null if this person does not have, or is not willing to share, a contact.

contributor

class contributor

It is a subclass of person, and represents the contributor to a project.

Typical “contributor” object
{
    "name":       "Keisuke S.K. Sehara",
    "lastname":   "Sehara",
    "firstnames": "Keisuke S.K.",
    "uri":        "ORCID:0000-0000-0000-0000",
    "contact":    "kkkkkeeeeiiiissssuuuukkkkeeee@mail.chaos-software.cc",
    "affiliation": [
        { "$ref": "/affiliations/ChaosSoftware" }
    ],
    "roles": [
        "data-curation",
        "software"
    ]
}

All the superclass properties are necessary:

In addition, all of the properties described below are necessary.

affiliation

an institution object, or a reference to one, or an array of multiple of them, corresponding to the affiliations for this contributor, in relation with this dataset publication.

roles

an array of roles of this contributor, specified in terms of the contributor roles (as it is defined in the CRediT taxonomy).

license

class license

a class being used to represent a license type of the subject being described.

For example, a CC0-license may be represented using license as follows:

Typical “license” object
{
    "name":    "CC0",
    "uri":     "http://creativecommons.org/publicdomain/zero/1.0",
    "year":    "2019",
    "authors": { "$ref": "/organization/people" }
}

a license object must have properties below:

name

equivalent to referrable.name. It represents the shorthand of the license e.g. “CC0”, “MIT”, “GPL2”.

uri

equivalent to referrable.uri. It may be the terms and conditions representing this license.

authors

a set of JSON objects, or a reference to it, representing the holder(s) of this license.

year

a string representing the year (or a range of years) when this license is valid from.

citation

class citation

a subclass of referrable being used to refer to a unique article on the web.

For example, a citation may be described using citation as follows:

Typical “citation” object
{
    "reference_type": "is-supplement-to",
    "name": "Sehara K, Colomb J, Larkum ME (2019) Dendritic mechanisms underlying foraging behavior of human subjects.",
    "uri": "doi:10.1101/000000"
}

The following properties are required:

name

equivalent to referrable.name, and is used to represent the human-readable citation.

uri

equivalent to referrable.uri. It represents the URI of the article, and may start either with https:// or with doi:, depending on the type of the article.

reference_type

a string representing how this citation works. valid types may be found below:

type description
is-supplement-to this citation is based on the dataset being described.
is-described-by this citation describes how the dataset being described was generated.
is-referenced-by this citation refers to this dataset, but neither of the above applies.