From 7bdc58961a7ae4312c1444802a32fd0dbd0176dc Mon Sep 17 00:00:00 2001
From: Johannes Nussbaum <39048939+jnussbaum@users.noreply.github.com>
Date: Thu, 25 Nov 2021 12:50:24 +0100
Subject: [PATCH] fix(schema): list root node needs a comments object (DEV-61)
 (#122)

* list root node needs a "comments" object

* add node without comment to test onto

* Update documentation regarding comments for lists

Co-authored-by: irinaschubert <irina.schubert@dasch.swiss>
---
 docs/dsp-tools-create.md           | 13 +++++++++----
 knora/dsplib/schemas/ontology.json |  8 +++++++-
 testdata/test-onto.json            |  5 +----
 3 files changed, 17 insertions(+), 9 deletions(-)

diff --git a/docs/dsp-tools-create.md b/docs/dsp-tools-create.md
index 40d50ee39..ac7b3b883 100644
--- a/docs/dsp-tools-create.md
+++ b/docs/dsp-tools-create.md
@@ -181,7 +181,8 @@ A node of a list may have the following elements:
 - _labels_: Label with language tags in the form `{ "<lang>": "<label>", "<lang>": "<label>", ... }`. The `labels`
   element is mandatory. It needs to specify at least one language. Currently, "de", "en", "fr" and "it" are supported.
 - _comments_: Comment with language tags in the form `{ "<lang>": "<comment>", "<lang>": "<comment>", ... }`.
-  The `comments` element is optional. Currently, "de", "en", "fr" and "it" are supported.
+  Currently, "de", "en", "fr" and "it" are supported. The `comments` element is mandatory for the root node of the list.
+  For all other nodes, it is optional. If not used, the element should be omitted.
 - _nodes_: Array of sub-nodes. The `nodes` element is optional and can be omitted in case of a flat list.
 
 Example of a list:
@@ -309,6 +310,10 @@ file(s) can be directly referenced inside the list definition by defining it as
     "en": "List from an Excel file",
     "de": "Liste von einer Excel-Datei"
   },
+  "comments": {
+    "en": "This is just an example.",
+    "fr": "C'est un example."
+  },
   "nodes": {
     "folder": "excel-lists"
   }
@@ -319,7 +324,7 @@ The nodes section must contain the field:
 
 - _folder_: Path to the folder where the Excel files are stored
 
-Further details to this functionality can be read
+Further details to this functionality can be found
 [here](dsp-tools-excel#create-a-list-from-one-or-several-excel-files).
 
 The `lists` element is optional. If not used, it should be omitted.
@@ -355,7 +360,7 @@ Example:
 }
 ```
 
-The `groups` element is optional. It is currently not recommended using it.
+The `groups` element is optional. If not used, it should be omitted. It is currently not recommended using it.
 
 ### Users
 
@@ -401,7 +406,7 @@ Example:
 }
 ```
 
-The `users` element is optional.
+The `users` element is optional. If not used, it should be omitted.
 
 ### Ontologies
 
diff --git a/knora/dsplib/schemas/ontology.json b/knora/dsplib/schemas/ontology.json
index e997664e9..a13890ec8 100644
--- a/knora/dsplib/schemas/ontology.json
+++ b/knora/dsplib/schemas/ontology.json
@@ -500,7 +500,13 @@
                 "lists": {
                     "type": "array",
                     "items": {
-                        "$ref": "#/definitions/node"
+                        "$ref": "#/definitions/node",
+                        "comments": {
+                            "$ref": "#/definitions/comment"
+                        },
+                        "required": [
+                            "comments"
+                        ]
                     }
                 },
                 "ontologies": {
diff --git a/testdata/test-onto.json b/testdata/test-onto.json
index 97853c2a3..35601a8f2 100644
--- a/testdata/test-onto.json
+++ b/testdata/test-onto.json
@@ -39,10 +39,7 @@
                     {
                         "name": "b",
                         "labels": {
-                            "en": "b_label"
-                        },
-                        "comments": {
-                            "en": "no comment"
+                            "en": "b_label with no comment"
                         },
                         "nodes": [
                             {