From faf62ecb69cc18f1850e1553b2bac728f4cfc50d Mon Sep 17 00:00:00 2001
From: Yaroslav Halchenko <debian@onerussian.com>
Date: Thu, 3 Oct 2024 13:55:23 -0400
Subject: [PATCH] Add ContextURI to allow to define the context for the entity
 values

It is often desired to be able to determine that values used
for entities in the dataset belong to some controlled vocabulary,
or simply defined centrally within some "id" authority. E.g. could be
unique scanning session IDs per scanning center, or similarly subject_ids defined
per study or centrally for the center.

It is of particular interest for large studies where multiple datasets could be
created, one per site or primary data modality, to later possibly be composed
into a single dataset or just to become parts of the one larger multi-site one.
In such cases it becomes quite important to annotate that particular entities
(subject_id, session_id and possibly even _desc- or _acq- values) are defined
in the scope of the specific  larger study and thus correspond to the "same" thing
given the same contextURI and value.
---
 src/common-principles.md         | 15 +++++++++++++++
 src/modality-agnostic-files.md   |  5 ++++-
 src/schema/objects/metadata.yaml |  9 +++++++++
 3 files changed, 28 insertions(+), 1 deletion(-)

diff --git a/src/common-principles.md b/src/common-principles.md
index 0a42e4a885..3bf804ab53 100644
--- a/src/common-principles.md
+++ b/src/common-principles.md
@@ -540,6 +540,7 @@ and a guide for using macros can be found at
         "Units": "RECOMMENDED",
         "Delimiter": "OPTIONAL",
         "TermURL": "RECOMMENDED",
+        "ContextURI": "RECOMMENDED",
         "HED": "OPTIONAL",
    }
 ) }}
@@ -592,6 +593,20 @@ like in the example below.
 }
 ```
 
+The `ContextURI` can be used to provide a URL to a controlled vocabulary or ontology, or simply to provide a URL to a page that provides more context for the values in the column.
+It is to be used, so if combined with the value in that value (`<label>` or `<index>`), it would establish a unique identifier for the entity to be used across BIDS datasets.
+In the example below it would establish that `participant_id` is shared across datasets of the center, which would allow to differentiate center's subjects apart from subject ids used by other datasets used in the lab.
+
+```JSON
+{
+    "participant_id": {
+        "Description": "Unique identifier used for study subjects in the lab across studies",
+        "ContextURI": "https://thelab.example.com/term/subject/"
+    }
+}
+```
+
+
 ### Compressed tabular files
 
 Large tabular information, such as physiological recordings, MUST be stored with
diff --git a/src/modality-agnostic-files.md b/src/modality-agnostic-files.md
index b93ee17638..e835c7cfb5 100644
--- a/src/modality-agnostic-files.md
+++ b/src/modality-agnostic-files.md
@@ -267,6 +267,9 @@ to date of birth.
 
 ```JSON
 {
+    "participant_id": {
+        "ContextURI": "http://thelab.example.com/term/subject/"
+    },
     "age": {
         "Description": "age of the participant",
         "Units": "year"
@@ -422,7 +425,7 @@ about the questionnaire and `adhd_b` and `adhd_c_dx` correspond to individual
 columns.
 
 In addition to the keys available to describe columns in all tabular files
-(`LongName`, `Description`, `Levels`, `Units`, and `TermURL`) the
+(`LongName`, `Description`, `Levels`, `Units`, `TermURL`, and `ContextURI`) the
 `participants.json` file as well as phenotypic files can also include column
 descriptions with a `Derivative` field that, when set to true, indicates that
 values in the corresponding column is a transformation of values from other
diff --git a/src/schema/objects/metadata.yaml b/src/schema/objects/metadata.yaml
index f97f629589..2f5f96c629 100644
--- a/src/schema/objects/metadata.yaml
+++ b/src/schema/objects/metadata.yaml
@@ -519,6 +519,15 @@ Columns:
   type: array
   items:
     type: string
+ContextURI:
+  name: ContextURI
+  display_name: Context URI
+  description: |
+    URI establishing the context for the values of this data.
+    For example, https://thelab.example.com/term/subject/ if used for "participant_id"
+    could be used to non-ambigously link participant data acquisitions across datasets.
+  type: string
+  format: uri
 ContinuousHeadLocalization:
   name: ContinuousHeadLocalization
   display_name: Continuous Head Localization