URI-based reference

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

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 description 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 class

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.

Person class

class Person

a subclass of Individual being used to refer to a person. 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.

License class

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:

{
    "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

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:

{
    "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	used when the subject being described is a supplement to the citation.