From 36e2e3c923f6460eb7351ea17201749c4a801771 Mon Sep 17 00:00:00 2001
From: Remi Gau <remi_gau@hotmail.com>
Date: Mon, 11 Sep 2023 10:18:07 -0400
Subject: [PATCH] [ENH] allow Levels values to be objects (#1603)

* update level description

* Apply suggestions from code review

Co-authored-by: Sebastian Urchs <surchs@users.noreply.github.com>

* add link to glossary

* rm weird file

* fix path

---------

Co-authored-by: Sebastian Urchs <surchs@users.noreply.github.com>
---
 src/common-principles.md         | 23 +++++++++++++++++++++++
 src/schema/objects/metadata.yaml |  5 +++--
 2 files changed, 26 insertions(+), 2 deletions(-)

diff --git a/src/common-principles.md b/src/common-principles.md
index c268e19203..2dc9905d9a 100644
--- a/src/common-principles.md
+++ b/src/common-principles.md
@@ -513,6 +513,29 @@ Example:
 }
 ```
 
+Each level can be described with a string as in the example above,
+or with an object containing the fields [`Description`](./glossary.md#description-metadata)
+and [`TermURL`](./glossary.md#termurl-metadata)
+like in the example below.
+
+```JSON
+{
+    "sex": {
+        "Description": "sex of the participant as reported by the participant",
+        "Levels": {
+            "M": {
+                "Description": "Male",
+                "TermURL": "https://www.ncbi.nlm.nih.gov/mesh/68008297"
+            },
+            "F": {
+                "Description": "Female",
+                "TermURL": "https://www.ncbi.nlm.nih.gov/mesh/68005260"
+            },
+        }
+    }
+}
+```
+
 ### Key-value files (dictionaries)
 
 JavaScript Object Notation (JSON) files MUST be used for storing key-value
diff --git a/src/schema/objects/metadata.yaml b/src/schema/objects/metadata.yaml
index 5347a5d5b5..f39d0d0465 100644
--- a/src/schema/objects/metadata.yaml
+++ b/src/schema/objects/metadata.yaml
@@ -3371,9 +3371,10 @@ TermURL:
   name: TermURL
   display_name: TermURL
   description: |
-    URL pointing to a formal definition of this type of data in an ontology
-    available on the web.
+    URL pointing to a formal definition of this type of data in an ontology available on the web.
+    For example: https://www.ncbi.nlm.nih.gov/mesh/68008297 for "male".
   type: string
+  format: uri
 TimeZero:
   name: TimeZero
   display_name: Time Zero