From 6ac417aad641b798b6a7186d134f86e16f03e17b Mon Sep 17 00:00:00 2001
From: Alexander Schlemmer <alexander@mail-schlemmer.de>
Date: Fri, 16 Jul 2021 15:21:36 +0200
Subject: [PATCH] DOC: added documentation for the yaml interface

---
 src/doc/yaml_interface.rst | 92 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 92 insertions(+)
 create mode 100644 src/doc/yaml_interface.rst

diff --git a/src/doc/yaml_interface.rst b/src/doc/yaml_interface.rst
new file mode 100644
index 00000000..d0ec15af
--- /dev/null
+++ b/src/doc/yaml_interface.rst
@@ -0,0 +1,92 @@
+YAML-Interface
+--------------
+
+The yaml interface is a module in caosdb-pylib that can be used to create and update
+CaosDB models using a simplified definition in YAML format.
+
+Let's start with an example taken from https://gitlab.indiscale.com/caosdb/src/caosdb-advanced-user-tools/-/blob/dev/unittests/model.yml.
+
+.. highlight:: yaml
+
+    Project:
+       obligatory_properties:
+          projectId:
+             datatype: INTEGER
+             description: 'UID of this project'
+    Person:
+       recommended_properties:
+          firstName:
+             datatype: TEXT 
+             description: 'first name'
+          lastName:
+             datatype: TEXT 
+             description: 'last name'
+    LabbookEntry:
+       recommended_properties:
+          Project:
+          entryId:
+             datatype: INTEGER
+             description: 'UID of this entry'
+          responsible:
+             datatype: Person
+             description: 'the person responsible for these notes'
+          textElement:
+             datatype: TEXT
+             description: 'a text element of a labbook recording'
+          associatedFile:
+             datatype: FILE
+             description: 'A file associated with this recording'
+          table:
+             datatype: FILE
+             description: 'A table document associated with this recording'
+
+This example defines 3 RecordTypes:
+- A Project with one obligatory property "datatype"
+- A Person with a "firstName" and a "lastName" (as recommended properties)
+- A LabbookEntry with multiple recommended properties of different data types
+
+One major advantage of using this interface (in contrast to the standard python interface) is that properties can be defined and added to record types "on-the-fly". E.g. the three lines for "firstName" as sub entries of Person have two effects on CaosDB:
+- A new property with name "firstName", datatype "TEXT" and description 'first name' is inserted (or updated, if already present) into CaosDB.
+- The new property is added as a recommended property to record type Person.
+
+Any furhter occurrences of "firstName" in the yaml file will reuse the definition provided for Person.
+
+Note the difference between the three property declarations of LabbookEntry:
+- "Project": This record type is added directly as a property of LabbookEntry. Therefore it does not specify any further attributes. Compare to the original declaration of record type "Project".
+- "responsible": This defines and adds a property with name "responsible" to LabbookEntry which has a datatype "Person. Person is defined above.
+- "firstName": This defines and adds a property with the standard data type "TEXT" to record type Person.
+
+Datatypes
+---------
+
+You can use any data type understood by CaosDB as datatype attribute in the yaml model.
+
+List attributes are a bit special:
+
+.. highlight::yaml
+
+  datatype: LIST(DOUBLE)
+
+would declare a list datatype of DOUBLE elements.
+
+.. highlight::yaml
+
+  datatype: LIST(Project)
+
+would declare a list of elements with datatype Project.
+
+
+Keywords
+--------
+
+- parent: Parent of this entity.
+- importance: Importance of this entity.
+- datatype: The datatpye of this property, e.g. TEXT, INTEGER or Project.
+- unit: The unit of the property, e.g. "m/s".
+- description: A description for this entity.
+- recommended_properties: Add properties to this entity with importance "recommended".
+- obligatory_properties: Add properties to this entity with importance "obligatory".
+- suggested_properties: Add properties to this entity with importance "suggested".
+- inherit_from_recommended: Inherit from another entity using the specified importance level including the higher importance level "obligatory". This would add a corresponding parent and add all obligatory and recommended properties from the parent.
+- inherit_from_suggested including higher importance levels: Inherit from another entity using the specified importance level. This would add a corresponding parent and add all obligatory, recommended and suggested properties from the parent.
+- inherit_from_obligatory: Inherit from another entity using the specified importance level. This would add a corresponding parent and add all obligatory properties from the parent.
-- 
GitLab