From 96588bb1e472cd691725c2f0c931c445b78ab4cc Mon Sep 17 00:00:00 2001
From: Alexander Schlemmer <alexander@mail-schlemmer.de>
Date: Thu, 6 Oct 2022 12:29:19 +0200
Subject: [PATCH] DOC: added information on how to reuse properties in yaml
 files

---
 src/doc/yaml_interface.rst | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/src/doc/yaml_interface.rst b/src/doc/yaml_interface.rst
index 78ff4cdd..3cad3a39 100644
--- a/src/doc/yaml_interface.rst
+++ b/src/doc/yaml_interface.rst
@@ -74,6 +74,41 @@ If the data model depends on record types or properties which already exist in C
 added using the ``extern`` keyword: ``extern`` takes a list of previously defined names.
 
 
+Reusing Properties
+==================
+
+Properties defined once (either as a property of a Record or as a separate Property) can be reused
+later in the yaml file. That requires that after the first occurrence of the property, the
+attributes have to be empty. Otherwise the reuse of the property would be conflicting with its
+original definition.
+
+Example:
+--------
+
+
+.. code-block:: yaml
+
+    Project:
+       obligatory_properties:
+          projectId:
+             datatype: INTEGER
+             description: 'UID of this project'
+          date:
+             datetype: DATETIME
+             description: Date of a project or an experiment
+
+    Experiment:
+       obligatory_properties:
+          experimentId:
+             datatype: INTEGER
+             description: 'UID of this experiment'
+          date:  # no further attributes here!
+
+
+The above example defines two Records: Project and Experiment
+The property ``date`` is defined upon its first occurrence as a property of ``Project``.
+Later, the same property is also added to ``Experiment`` where no additional attributes are
+allowed to specify.
 
 Datatypes
 =========
-- 
GitLab