Skip to content

MHD Common Data Model v0.1

MHD Common Data Model is a connected graph of nodes and edges. MHD Domain Objects and MHD Cv Term Objects define the graph nodes and MHD Relationship Object (including both external and embedded relationships) define the edges. This graph-based structure allows for flexible, modular, structured, and consistent representation of metabolomics datasets.

MHD Common Data Model Nodes

MHD Domain Objects

Each of MHD Domain Objects corresponds to a concept commonly used in metabolomics dataset metadata files.

List of MHD Domain Objects:

The following properties are common for all MHD Domain Objects.

Property Name Necessity Type Description
id required str The id property uniquely identifies the object. All MHD Domain Objects have unique identifiers even if their values are exactly same.
type required str The type MUST be lower case and '-' seperated value of node name. e.g. raw-data-file for Raw Data File
created_by_ref optional str The id of the data provider.
tags optional list of KeyValue Key and values. key and values may be CV Term
descriptors optional list of CvTerm Descriptors for the object
external_references optional list of KeyValue List of external references that describes the resource represented by the node. Key MUST be a URI type (FTP, URL, etc.)
uri_list optional list of KeyValue List of URI addresses to access the resource represented by the node

MHD Cv Term Objects

MHD Common Data Model defines a set of data types (MHD Cv Term Objects) presented as CV Term.

List of MHD Cv Term Objects: Characteristic Type, Characteristic Value, Data Provider, Factor Type, Factor Value, Parameter Type, Protocol Type, Parameter Value, Uri Type

The following properties are common for all MHD Cv Term Objects.

Property Name Necessity Type Description
id required str The id property uniquely identifies the object. All MHD Cv Term Objects have same identifiers if their values are exactly same.
type required str The type MUST be lower case and '-' seperated value of node name. e.g. parameter-value for Paramter Value

MHD Common Data Model Relationships

A relationship is a link between MHD Domain Objects or MHD Cv Term Objects that describes the way in which the objects are related. Relationships can be represented using an MHD Relationship Object or a property (embedded relationship) in a node. Property names that used as embedded relationship in a node end with _ref or _refs (for multiple), and their values are id's of target nodes.

MHD Relationship Object has the following properties.

Property Name Necessity Type Description
id required MhdRelationshipObjectId The id property uniquely identifies the object.
type required str The type MUST be 'relationship'
created_by_ref optional str The id of the data provider.
tags optional list[KeyValue] Key and values. key and values may be CV Term
external_references optional list[KeyValue] List of external references that describes the resource represented by the relationship. Key MUST be a URI type (FTP, URL, etc.)
uri_list optional list[KeyValue] List of URI addresses to access the resource represented by the relationship
source_ref required CvTermValueObjectId or CvTermObjectId or MhdObjectId The id of source node
relationship_name required str Relationship name
target_ref required CvTermValueObjectId or CvTermObjectId or MhdObjectId The id of target node
source_role optional str Role name of source node
target_role optional str Role name of target node

Node and Relationship Property Types

Primitive Types

Primitive data types are string (str), number (int or float), boolean (bool), and null (None).

The following string formatted JSON schema data types are also supported:

  • date: ISO 8601 calendar date. e.g. 2025-05-18
  • time: ISO 8601 time without timezone. e.g. 14:30:00
  • date-time: ISO 8601 full timestamp. e.g. 2025-05-18T14:30:00Z
  • email: RFC 5322 email address. e.g. help@metabolomicshub.org
  • uri: Full URI. e.g. https://metabolomicshub.org/docs

Node and Relationship Ids

MhdObjectId

The id property of MHD Domain Objects MUST have three parts. These parts are merged with "--" seperator to create id.

  1. mhd constant
  2. [type name, e.g. study, protocol, etc.]
  3. UUID4 value
# Pattern for id property of MHD Domain Objects
^mhd--[-a-zA-Z0-9]+--[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

# Example MHD Domain Object id
mhd--study--51be6a20-0e5a-4c2d-9177-f261193dc30c

CvTermObjectId

The id property of MHD Cv Term Objects MUST have three parts. These parts are merged with "--" seperator to create id.

  1. cv constant
  2. [type name, e.g. technology-type, factor-definition, etc.]
  3. UUID5 value of source, accession, and name fields' values [namespace is MHD namespace with a constant efb4f8e4-d08b-4979-916e-600c4985e7f2]
# Pattern for id property of MHD Cv Term Objects
^cv--[-a-zA-Z0-9]+--[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

# Example MHD Cv Term Object id
cv--factor-definition--66be6a20-0e5a-4c2d-9177-f261193dc30c

CvTermValueObjectId

The id property of MHD Cv Term Objects with value MUST have three parts. These parts are merged with "--" seperator to create id.

  1. cv-value constant
  2. [type name, e.g. data-provider, metabolite-definition, etc.]
  3. UUID5 value of source, accession, name and value fields' values [namespace is MHD namespace with a constant efb4f8e4-d08b-4979-916e-600c4985e7f2]
# Pattern for id property of MHD Cv Term Value Objects
^cv-value--[-a-zA-Z0-9]+--[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

# Example MHD Cv Term Value Object id
cv-value--data-provider--88be6a20-0e5a-4c2d-9177-f261193dc30c

MhdRelationshipObjectId

The id property of MHD Relationship Object MUST have three parts. These parts are merged with "--" seperator to create id.

  1. rel constant
  2. relationship constant
  3. UUID5 value of source_ref, relationship_name, target_ref fields' values [namespace is MHD namespace with a constant efb4f8e4-d08b-4979-916e-600c4985e7f2]
# Pattern for id property of MHD Relationship Object
^rel--[-a-zA-Z0-9]+--[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

# Example MHD Relationship Object id
rel--relationship--99be6a20-0e5a-4c2d-9177-f261193dc30c

CvTerm

Property Name Necessity Type Description
source required str Source of CV term. e.g., NCIT, EFO, etc.
accession required str Accession number CV Term in CURIES format. e.g., EFO:0001742
name required str Label of CV Term. e.g., publication status

QuantitativeValue

Property Name Necessity Type Description
value required str or int or float Value associated with CV Term. e.g., 2
unit optional CV Term Unit of value. [OBI, OBI:0000984, dose]

CvTermValue

Property Name Necessity Type Description
source required str Source of CV term. e.g., NCIT, EFO, etc.
accession required str Accession number CV Term in CURIES format. e.g., NCIT:C189151
name required str Label of CV Term. e.g., Study Data Repository
value required str Value associated with CV Term. e.g., MetaboLights
unit optional CV Term Unit of value.

KeyValue

Property Name Necessity Type Description
key required str or CvTermObjectId or MhdObjectId or CvTerm Key of the object. It can be a id of a node, str or CV Term
value required CvTermValueObjectId or CvTermObjectId or MhdObjectId or str or CvTerm or CvTermValue or QuantitativeValue Value of the object. It can be a id of a node, str, CV Term or Cv Term Value