DOC: Update and extend importance and inheritance

src/doc/specification/RecordType.rst

@@ -4,20 +4,23 @@ RecordType
 Overview
 --------
 
-RecordTypes function as templates for :doc:`Records <Record>`, they
+RecordTypes function as templates for :doc:`Records <Record>`. They
 provide a description for a type of Record and define which
-:doc:`Properties <AbstractProperty>` should be present. Properties
-come with an `importance` attribute which tells the user or client
-program how strongly necessary the Property is. (As all other
-entities,) RecordTypes can be inherited from other RecordTypes (or any
-Entities). When RecordTypes inherit from other RecordTypes, the
-`inheritance` flag tells which properties shall be
+:doc:`Properties <AbstractProperty>` could, should, or must be
+present. Properties come with an `importance` attribute which tells
+the user or client program how strongly necessary the Property is. (As
+all other entities,) RecordTypes can be inherited from other
+RecordTypes (or any Entities). When RecordTypes inherit from other
+RecordTypes, the `inheritance` flag tells which properties shall be
+inherited from the parents to the children.
 
 Importance
 ~~~~~~~~~~
 
-Importances are more of a recommendation, Records with omitted
-Properties can technically still be committed.
+The importance value of a Property states whether it may, should, or
+has to be present in all children of this Entity. The table below
+lists the possible importances, together with the default behavior of
+the server when the property is not present in a child.
 
 .. list-table::
    :widths: 25 25 50
@@ -29,22 +32,40 @@ Properties can technically still be committed.
      - Consequence when omitted
    * - ``OBLIGATORY``
      - Property must be present
-     - *FIXME* Can be forced to be committed the server, but usually an error will be returned.
+     - Can be forced to be committed the server, but usually
+       an error will be returned.
    * - ``RECOMMENDED``
      - Property should be present (makes sense for most users)
-     - *FIXME* Usually an error will be returned?
-   * - ``SUGGESTED`` (*FIXME* the default?)
+     - No consequence right now, but in future versions a warning will
+       be returned.
+   * - ``SUGGESTED`` (default)
      - Property may be present (may make sense for some users)
-     - *FIXME* No negative consequence? 
-
+     - No negative consequence
+   * - ``FIX``
+     - Property is not present in any child
+     - ---
+
+The default behavior can be overridden for individual transaction by
+setting the `force-missing-obligatory` flag to `ERROR`, `WARN`, or
+`IGNORE`, in which case a transaction that would lead to an entity
+without (at least) an obligatory property causes an error, is executed
+with a warning, or is executed without a warning, respectively. The
+importance value ``FIX`` is used for properties that are specific to
+the Entity itself and is explained :ref:`below <Inheritance>`.
+       
+.. note::
 
-*FIXME* Did I get recommended and suggested right?
+   Note that in contrast to RecordTypes, all properties of a
+   :doc:`Record` have importance ``FIX`` since in general, even in the
+   rare case of a Record having children, its properties are not
+   inherited.
 
 Inheritance
 ~~~~~~~~~~~
 
-The _inheritance_ flag decides which [[Property|Properties]] are inherited from parents.
-
+The `inheritance` flag specifies which :doc:`Properties
+<AbstractProperty>` are inherited from the parent RecordType(s) to the
+child.
 
 .. list-table::
    :widths: 40 60
@@ -52,20 +73,40 @@ The _inheritance_ flag decides which [[Property|Properties]] are inherited from
 
    * - Inheritance
      - Meaning
-   * - _None_ (default)
+   * - `None` (default)
      - Nothing is being inherited
    * - ``OBLIGATORY``
-     - *FIXME* Properteis of importance ``OBLIGATORY`` and above?
+     - Properties of importance ``OBLIGATORY`` and above
+   * - ``RECOMMENDED``
+     - Properties of importance ``RECOMMENDED`` and above
    * - ``SUGGESTED``
-     - *FIXME* Properteis of importance ``SIGGESTED`` and above, so the same effect as ``ALL``?
+     - Properteis of importance ``SUGGESTED`` and above
    * - ``ALL``
      - Copy everything from the parent.
-   * - ``FIX``
-     - *FIXME* in `tests/test_inheritance.py` of pyint_test this is used, what does it mean???
+
+Note that inheritance ``All`` is essentially the same as ``SUGGESTED``
+right now, but this behavior might change in the future. Also note
+that properties of importance ``FIX`` are never inherited this
+way. This is precisely what this importance level is meant for:
+properties that are specific to the parent entity and are not
+inherited by default. You can still add this property to the child
+manually if you wish to, though, but this is not covered by the
+automatic inheritance.
+
+.. note::
+
+   The behavior of `inheritance` is currently not well-defined if the
+   child is a :doc:`Record`, not a RecordType.
 
 Examples
 --------
 
+.. warning::
+
+   The following examples have not been updated in a while and may
+   serve as a starting point, but are not guaranteed to be fully
+   applicable to the most recent versions of CaosDB.
+
 GET Requests
 ~~~~~~~~~~~~
 
@@ -144,7 +185,7 @@ Get all
 
 .. note::
 
-   Outdated?
+   Outdated? At least the bug tracker doesn't exist anymore.
 
 .. code-block:: XML