Specification reference

ARC Provenance Core

Persistent identifier: https://w3id.org/arc/ro-crate/provenance-core/0.1

View this specification's source

This profile uses terminology from the RO-Crate 1.2 specification, and extends it with additional terms from the ARC ro-terms and Bioschemas namespace.

#Overview

The aim of the profile is to be able to fully represent ISA-JSON as RO-Crate, fully capturing the metadata and files in a non-lossy form such that it should be possible to convert between one to the other, in either direction, without loss of information.

The profile relies on types from Bioschemas types:

LabProtocol - A child of HowTo to make it clearer that it is intended to specifically describe the planned instructions for upcoming lab processes.

LabProcess - A child of Action, to specifically describe the details and outcomes of an executed LabProtocol. Thereby separating the "what was planned" and "what happened" between LabProtocol and LabProcess respectively. A working group is working on the new type and adaptations of existing types.

The following graph summarizes the Provenance Core model in terms of Bioschemas/Schema.org vocabulary:

Diagram source
flowchart TD

dataset[Dataset]

Process[LabProcess]

Protocol[LabProtocol]

Sample[Sample]

DataFile[File]


prop[PropertyValue]

dataset --hasPart----> DataFile
dataset --processSequence--> Process

Process --"result"---> DataFile
Process --"result"--> Sample
Process --"object"--> Sample
Process --executesLabProtocol--> Protocol
Process --parameterValue---> prop

Sample --additionalProperty--> prop

Protocol --labEquipment---> prop
Protocol --reagent---> prop

#Example Metadata File (ro-crate-metadata.json)

{
  "@context": [
    "https://w3id.org/ro/crate/1.2/context",
    {
      "Sample": "https://bioschemas.org/Sample",
      "LabProtocol": "https://bioschemas.org/LabProtocol",
      "LabProcess": "https://bioschemas.org/LabProcess",
      "computationalTool": "https://bioschemas.org/properties/computationalTool",
      "labEquipment": "https://bioschemas.org/properties/labEquipment",
      "reagent": "https://bioschemas.org/properties/reagent",
      "intendedUse": "https://bioschemas.org/properties/intendedUse",
      "executesLabProtocol": "https://bioschemas.org/properties/executesLabProtocol",
      "parameterValue": "https://bioschemas.org/properties/parameterValue",
      "columnIndex": "https://w3id.org/ro/terms/arc#columnIndex"
    }
  ],
  "@graph": [
    {
      "@id": "datafile.wiff",
      "@type": "File",
      "name": "datafile.wiff"
    },
    {
      "@id": "#CharacteristicValue_organism_Arabidopsis_thaliana",
      "@type": "PropertyValue",
      "additionalType": "CharacteristicValue",
      "name": "organism",
      "value": "Arabidopsis thaliana",
      "propertyID": "https://bioregistry.io/OBI:0100026",
      "valueReference": "http://purl.obolibrary.org/obo/NCBITAXON_3702"
    },
    {
      "@id": "#Material_MyObservable",
      "@type": "Sample",
      "additionalType": "Material",
      "name": "MyObservable",
      "additionalProperty": {
        "@id": "#CharacteristicValue_organism_Arabidopsis_thaliana"
      }
    },
    {
      "@id": "#Sample_MySample",
      "@type": "Sample",
      "additionalType": "Sample",
      "name": "MySample"
    },
    {
      "@id": "#CharacteristicValue_Temperature_25",
      "@type": "PropertyValue",
      "additionalType": "CharacteristicValue",
      "name": "Temperature",
      "value": "25",
      "propertyID": "https://bioregistry.io/NCIT:C25206",
      "unitCode": "http://purl.obolibrary.org/obo/UO_0000027",
      "unitText": "degree Celsius"
    },
    {
      "@id": "#Process_Preparation",
      "@type": "LabProcess",
      "name": "Preparation",
      "object": {
        "@id": "#Material_MyObservable"
      },
      "result": {
        "@id": "#Sample_MySample"
      },
      "parameterValue": {
        "@id": "#CharacteristicValue_Temperature_25"
      }
    },
    {
      "@id": "#Process_Measurement",
      "@type": "LabProcess",
      "name": "Measurement",
      "object": {
        "@id": "#Sample_MySample"
      },
      "result": {
        "@id": "datafile.wiff"
      }
    },
    {
      "@id": "LICENSE",
      "@type": "CreativeWork",
      "text": "ALL RIGHTS RESERVED BY THE AUTHORS"
    },
    {
      "@id": "./",
      "@type": "Dataset",
      "description": "An example of a ROCrate with a core process model, including preparation and measurement processes.",
      "name": "Experimental ARC Provenance Core Example",
      "hasPart": {
        "@id": "datafile.wiff"
      },
      "about": [
        {
          "@id": "#Process_Preparation"
        },
        {
          "@id": "#Process_Measurement"
        }
      ],
      "dateCreated": "2026-06-24T23:04:48.2431278",
      "license": {
        "@id": "LICENSE"
      }
    },
    {
      "@id": "ro-crate-metadata.json",
      "@type": "CreativeWork",
      "conformsTo": {
        "@id": "https://w3id.org/ro/crate/1.2"
      },
      "about": {
        "@id": "./"
      }
    }
  ]
}

#Requirements

#Dataset

schema.org/Dataset containing and contexualizing the processes.

PropertyRequiredExpected TypeDescription
@idMUSTText or URLAccording to ROCrate specification.
@typeMUSTTextMUST be 'schema.org/Dataset'
aboutSHOULDbioschemas.org/LabProcessThe processes described here and possibly leading up to the files grouped in this dataset.
hasPartCOULDFileData files resulting from the process sequence.

#LabProcess

Has the new Bioschemas DRAFT bioschemas.org/LabProcess type and maps to the ISA-JSON Process

PropertyRequiredExpected TypeDescription
@idMUSTText or URLCould identify the process using the isa metadata filename and the protocol reference or process name.
@typeMUSTTextMUST be 'bioschemas.org/LabProcess'
nameMUSTText-
objectSHOULDbioschemas.org/Sample or FileThe input of the process. If there are multiple inputs, they SHOULD be stored as a sorted list to establish correspondence with outputs. (Both lists need the same length in that case.)
resultSHOULDbioschemas.org/Sample or FileThe output of the process. If there are multiple outputs, they SHOULD be stored as a sorted list to establish correspondence with inputs. (Both lists need the same length in that case.)
executesLabProtocolSHOULDbioschemas.org/LabProtocolThe protocol executed
parameterValueSHOULDschema.org/PropertyValue (Parameter)A parameter value of the experimental process, usually a key-value pair using ontology terms

#LabProtocol

Is based on the Bioschemas bioschemas.org/LabProtocol type and maps to the ISA-JSON Protocol

PropertyRequiredExpected TypeDescription
@idMUSTText or URLCould be the url pointing to the protocol resource.
@typeMUSTTextMUST be 'bioschemas.org/LabProtocol'
descriptionSHOULDTextA short description of the protocol (e.g. an abstract)
intendedUseSHOULDschema.org/DefinedTerm or Text or URLThe protocol type as an ontology term
nameSHOULDTextMain title of the LabProtocol.
computationalToolCOULDschema.org/DefinedTerm or schema.org/PropertyValue (Component) or schema.org/SoftwareApplicationSoftware or tool used as part of the lab protocol to complete a part of it.
labEquipmentCOULDschema.org/DefinedTerm or schema.org/PropertyValue (Component) or Text or URLFor LabProtocols it would be a laboratory equipment use by a person to follow one or more steps described in this LabProtocol.
reagentCOULDschema.org/BioChemEntity or schema.org/DefinedTerm or schema.org/PropertyValue (Component) or Text or URLReagents used in the protocol.
urlCOULDURLPointer to protocol resources external to the ISA-Tab that can be accessed by their Uniform Resource Identifier (URI).
versionCOULDNumber or TextAn identifier for the version to ensure protocol tracking.

#Sample

Is based on the Bioschemas bioschemas.org/Sample type, and represents the ISA-JSON Sample, Source and Material

PropertyRequiredExpected TypeDescription
@idMUSTText or URLCould be the unique sample name.
@typeMUSTTextMUST be 'bioschemas.org/Sample'
nameMUSTTextA name identifying the sample.
additionalPropertySHOULDschema.org/PropertyValue (Characteristic or Factor)characteristics or factors

#Data

Describes and points to a Data file or a segment of a Data file (via data fragment selectors), and maps to the ISA-JSON Data

PropertyRequiredExpected TypeDescription
@idMUSTText or URLShould be the path pointing to the file
@typeMUSTTextMUST be 'File' or 'MediaObject'
nameMUSTText or URLThe name of the file.
encodingFormatCOULDText or URLMedia format as a MIME type
hasPartCOULDText or URLData fragments of this Data object, described by data fragment selectors. SHOULD not be used on data fragments.
usageInfoCOULDText or URLDescription/specification of the data fragment selector, if the object describes a data fragment and a selector is present in the path/@id. SHOULD only be used on data fragments.

Entities referenced by an processes's object or result SHOULD be of type File (an RO-Crate alias for MediaObject) for files, Dataset for directories and Collection for multi-file datasets, but MAY be a CreativeWork for other types of data (e.g. an online database); they MAY be of type PropertyValue to capture numbers/strings that are not stored as files.

Data entities involved in an application's input and output SHOULD have an @id that reflects the original file or directory name as processed by the application, but MAY be renamed to avoid clashes with other entities in the crate. In this case, they SHOULD refer to the original name via alternateName. This is particularly important to support reproducibility in cases where an application expects to find input in specific locations and with specific names (see the MIRAX example in Representing multi-file objects).

#DefinedTerm

Single ontology term.

PropertyRequiredExpected TypeDescription
@idMUSTText or URL
@typeMUSTTextMUST be 'schema.org/DefinedTerm'
nameMUSTTextThe term name.
termCodeSHOULDTextThe identifier within the ontology.
inDefinedTermSetCOULDURL or schema.org/DefinedTermSetLink to the ontology or object describing the ontology. In the latter case, the object MUST follow the DefinedTermSet profile.

#DefinedTermSet

An ontology, set of defined terms, or controlled vocabulary.

PropertyRequiredExpected TypeDescription
@idMUSTText or URL
@typeMUSTTextMUST be 'schema.org/DefinedTermSet'
nameMUSTTextHuman-readable name of the ontology, controlled vocabulary, or other term set.
identifierCOULDText or URLIdentifier of the term set, expressed as text or a URL.

#PropertyValue

General profile for key-value pairs. It is based on schema.org/PropertyValue.

PropertyRequiredExpected TypeDescription
@idMUSTText or URL
@typeMUSTTextMUST be 'schema.org/PropertyValue'
nameMUSTText or URLKey name
valueSHOULDTextValue text or number
propertyIDSHOULDURLKey ontology reference
additionalTypeCouldTextCan be used to further clarify the type of this property
unitCodeCOULDURLUnit ontology reference
unitTextCOULDTextUnit name
valueReferenceCOULDURLValue ontology reference

#Processes as graph edges

#Data Fragment-level annotation

Data Fragment-level annotation diagram
[
  {
    "@id": "raw_data1.wiff",
    "@type": "File",
    "name": "raw_data1.wiff"
  },
  {
    "@id": "raw_data2.wiff",
    "@type": "File",
    "name": "raw_data2.wiff"
  },
  {
    "@id": "processed_data.csv#col=1",
    "@type": "File",
    "name": "processed_data.csv#col=1",
    "encodingFormat": "text/csv",
    "usageInfo": "https://datatracker.ietf.org/doc/html/rfc7111"
  },
  {
    "@id": "processed_data.csv#col=2",
    "@type": "File",
    "name": "processed_data.csv#col=2",
    "encodingFormat": "text/csv",
    "usageInfo": "https://datatracker.ietf.org/doc/html/rfc7111"
  },
  {
    "@id": "#Process_DataProcessing_1",
    "@type": "LabProcess",
    "name": "DataProcessing_1",
    "object": {
      "@id": "raw_data1.wiff"
    },
    "result": {
      "@id": "processed_data.csv#col=1"
    }
  },
  {
    "@id": "#Process_DataProcessing_2",
    "@type": "LabProcess",
    "name": "DataProcessing_2",
    "object": {
      "@id": "raw_data2.wiff"
    },
    "result": {
      "@id": "processed_data.csv#col=2"
    }
  }
]

#Experimental process

#Computational process

#PropertyValue Annotations