Skip to content
Snippets Groups Projects
Commit d6ebda86 authored by florian's avatar florian
Browse files

DOC: Update and extend importance and inheritance

parent 5c5c82b3
No related branches found
No related tags found
1 merge request!22DOC: Update and extend importance and inheritance
Pipeline #9121 passed
......@@ -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
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment