From 67909c92352ad9f70aba1ad1ec3a494e0893c98c Mon Sep 17 00:00:00 2001
From: florian <f.spreckelsen@inidscale.com>
Date: Mon, 15 May 2023 16:16:19 +0200
Subject: [PATCH] DOC: Add some user documentation on pattern properties
---
src/doc/index.rst | 1 +
src/doc/json_schema_interface.rst | 75 +++++++++++++++++++++++++++++++
2 files changed, 76 insertions(+)
create mode 100644 src/doc/json_schema_interface.rst
diff --git a/src/doc/index.rst b/src/doc/index.rst
index 5fdb78da..6c2c5f98 100644
--- a/src/doc/index.rst
+++ b/src/doc/index.rst
@@ -15,6 +15,7 @@ This documentation helps you to :doc:`get started<getting_started>`, explains th
Concepts <concepts>
The Caosdb Crawler <crawler>
YAML data model specification <yaml_interface>
+ Specifying a datamodel with JSON schema <json_schema_interface>
_apidoc/modules
diff --git a/src/doc/json_schema_interface.rst b/src/doc/json_schema_interface.rst
new file mode 100644
index 00000000..09fe10fa
--- /dev/null
+++ b/src/doc/json_schema_interface.rst
@@ -0,0 +1,75 @@
+Defining datamodels with a JSON schema specification
+====================================================
+
+TODO, see https://gitlab.com/caosdb/caosdb-advanced-user-tools/-/issues/42
+
+Further information
+###################
+
+Pattern Properties
+%%%%%%%%%%%%%%%%%%
+
+The JSON-schema parser has rudimentary support for ``patternProperties``. Since
+their names (only the pattern that their names will suffice) are not known a
+priori, we create RecordTypes for all pattern properties. The names of these
+RecordTypes are created from their parent element's name by appending the string
+``"Entry"`` and possibly a number if there are more than one pattern properties
+for one parent.
+
+All the RecordTypes created for pattern properties have at least an boligatory
+``__matched_pattern`` property which will -- as the name suggests -- store the
+matched pattern of an actual data entry.
+
+.. note::
+
+ The ``__matched_pattern`` property is added automatically to your datamodel
+ as soon as there is at least one pattern property in your JSON schema. So be
+ sure that you don't happen to have an entity with exactly this name in your
+ database.
+
+E.g., a json schema with
+
+.. code-block:: json
+
+ "dataset": {
+ "patternProperties": {
+ "^[0-9]{4,4}": {
+ "type": "boolean"
+ },
+ "^[0-9]{4,4}-[0-9]{2,2}-[0-9]{2,2}": {
+ "type": "object",
+ "properties": {
+ "date_id": {
+ "$ref": "#/definitions/uuid"
+ }
+ }
+ }
+ }
+ }
+
+Would result in a ``Dataset`` RecordType that has the two properties
+``DatasetEntry_1`` and ``DatasetEntry_2`` (as always, name can be overwritten
+explicitly by specifying the ``title`` property), referencing corresponding
+``DatasetEntry_1`` and ``DatasetEntry_2`` Records.
+
+Apart from the aforementioned ``__matched_pattern`` property, ``DatasetEntry_1``
+also has the ``DatasetEntry_1_value`` property with datatype ``BOOLEAN``, that
+stores the actual value. In turn, ``DatasetEntry_2`` is of ``type: object`` and
+is treated like any other RecordType. Consequently, it has, appart from the
+``__matched_pattern`` property, a ``date_id`` property as specified in its
+``properties``.
+
+Array entries without ``items`` specification
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+JSON schema allows for properties of ``type: array`` without the ``items``
+specification that consequently can be arrays of any (and of mixed) types. While
+this is in general problematic when specifying a data model, sometimes these
+properties cannot be specified further, e.g., when you're using an external
+schema that you cannot change.
+
+These properties can still be added to your datamodel by specifying their types
+explicitly in a dictionary or, alternatively, they can be ignored. See the
+``types_for_missing_array_items`` and ``ignore_unspecified_array_items``
+parameters of ``models.parser.JsonSchemaParser``, respectively, for more
+information.
--
GitLab