From 0dd91eb75aeef963c20c8a7ab57d7785d47632d6 Mon Sep 17 00:00:00 2001
From: Lyuba Zehl <lyuba.zehl@ebrains.eu>
Date: Tue, 22 Oct 2024 17:31:21 +0200
Subject: [PATCH] Update vocabulary.rst (#24)

* Update vocabulary.rst

solves #3

* Update vocabulary.rst

* Update vocabulary.rst

* Update vocabulary.rst

* Update vocabulary.rst
---
 .../contribution_guidelines/vocabulary.rst    | 21 +++++++++++++++++--
 1 file changed, 19 insertions(+), 2 deletions(-)

diff --git a/docs/shared/contribution_guidelines/vocabulary.rst b/docs/shared/contribution_guidelines/vocabulary.rst
index a91ca142..fcae0460 100644
--- a/docs/shared/contribution_guidelines/vocabulary.rst
+++ b/docs/shared/contribution_guidelines/vocabulary.rst
@@ -4,10 +4,15 @@ Vocabulary
 
 If you want to contribute to openMINDS by adding information to the openMINDS vocabulary we advise you to first review this chapter.
 
+For each contribution, please raise an `ISSUE <https://github.com/openMetadataInitiative/openMINDS/issues>`_. Start the issue title with ``vocab: `` followed by an informative short title for your contribution. Please provide a more detailed explanation of your contribution in issue description. We will discuss your contribution with you before a pull request is made (by you or by us if you do not feel comfortable making a pull request yourself).
+
+
 Schema types
 ############
 
-The following code block sketches the vocabulary implementation for a single schema type:
+In openMINDS, schema types are considered version independent, meaning the general information about a schema type remains the same across versions (e.g. its description). We maintain this schema type information centrally on the main openMINDS GitHub repository under: `vocab/types.json <https://github.com/openMetadataInitiative/openMINDS/blob/main/vocab/types.json>`_
+
+In this JSON file, each vocabulary implementation for a single schema type is structured in the following way:
 
 .. code-block:: json
 
@@ -26,10 +31,16 @@ The following code block sketches the vocabulary implementation for a single sch
      }
    }
 
+.. note::
+
+   This file is auto-generated with each new schema commit on openMINDS. However, the attributes ``"color"``, ``"description"``, ``"label"``, and ``"semanticEquivalent"`` can be manually overwritten.
+
 Properties
 ##########
 
-The following code block sketches the vocabulary implementation for a single property:
+In openMINDS, general information on properties (e.g., description) are considered schema and (mostly) version independent. We maintain this information centrally on the main openMINDS GitHub repository under: `vocab/properties.json <https://github.com/openMetadataInitiative/openMINDS/blob/main/vocab/properties.json>`_
+
+In this JSON file, each vocabulary implementation for a single property is structured in the following way:
 
 .. code-block:: json
 
@@ -44,7 +55,9 @@ The following code block sketches the vocabulary implementation for a single pro
        },
        "description": "PROPERTYNAME_DESCRIPTION",
        "label": "PROPERTYLABEL",
+       "labelPlural": "PROPERTYLABEL",
        "name": "PROPERTYNAME_SHORT",
+       "namePlural": "PROPERTYLABEL",
        "semanticEquivalent": [
          "UNIQUEID_OF_EQUIVALENT_PROPERTY"
        ],
@@ -55,3 +68,7 @@ The following code block sketches the vocabulary implementation for a single pro
        }
      }
    }
+
+.. note::
+
+   This file is auto-generated with each new commit on openMINDS. However, the attributes ``"description"``, ``"label"``, ``"labelPlural"``, ``"namePlural"``, and ``"semanticEquivalent"`` can be manually overwritten.