DOC: added information on how to reuse properties in yaml files

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
 =========