From 3e71faaf078d432a73bdc9f809c65464046e737a Mon Sep 17 00:00:00 2001
From: Viicos <65306057+Viicos@users.noreply.github.com>
Date: Mon, 29 Apr 2024 16:13:28 +0200
Subject: [PATCH 1/2] [#4044] Add `sphinxcontrib-mermaid` dependency

---
 docs/conf.py         | 1 +
 requirements/ci.txt  | 2 ++
 requirements/dev.txt | 4 ++++
 requirements/docs.in | 1 +
 4 files changed, 8 insertions(+)

diff --git a/docs/conf.py b/docs/conf.py
index 2af2dea738..0293b335cc 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -40,6 +40,7 @@
     "sphinx.ext.todo",
     "sphinx.ext.intersphinx",
     "sphinx_tabs.tabs",
+    "sphinxcontrib.mermaid",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
diff --git a/requirements/ci.txt b/requirements/ci.txt
index d6237de5f1..b442f49e24 100644
--- a/requirements/ci.txt
+++ b/requirements/ci.txt
@@ -943,6 +943,8 @@ sphinxcontrib-jquery==4.1
     # via sphinx-rtd-theme
 sphinxcontrib-jsmath==1.0.1
     # via sphinx
+sphinxcontrib-mermaid==0.9.2
+    # via -r requirements/docs.in
 sphinxcontrib-qthelp==1.0.7
     # via sphinx
 sphinxcontrib-serializinghtml==1.1.10
diff --git a/requirements/dev.txt b/requirements/dev.txt
index 5f6f7a426b..a052c71ac5 100644
--- a/requirements/dev.txt
+++ b/requirements/dev.txt
@@ -1087,6 +1087,10 @@ sphinxcontrib-jsmath==1.0.1
     #   -c requirements/ci.txt
     #   -r requirements/ci.txt
     #   sphinx
+sphinxcontrib-mermaid==0.9.2
+    # via
+    #   -c requirements/ci.txt
+    #   -r requirements/ci.txt
 sphinxcontrib-qthelp==1.0.7
     # via
     #   -c requirements/ci.txt
diff --git a/requirements/docs.in b/requirements/docs.in
index 2533283667..b759e7dc66 100644
--- a/requirements/docs.in
+++ b/requirements/docs.in
@@ -4,3 +4,4 @@
 sphinx
 sphinx-rtd-theme
 sphinx-tabs
+sphinxcontrib-mermaid

From 4516997343636c3dbc9fa48c2b52b179f1881d5f Mon Sep 17 00:00:00 2001
From: Viicos <65306057+Viicos@users.noreply.github.com>
Date: Mon, 25 Mar 2024 17:45:35 +0100
Subject: [PATCH 2/2] [#4044] Add more documentation on formio configuration

---
 .../backend/core/_assets/forms-models.mmd     | 46 +++++++++++++++
 docs/developers/backend/core/formio.rst       | 57 +++++++++++++++++++
 docs/developers/backend/core/index.rst        | 18 ++++++
 3 files changed, 121 insertions(+)
 create mode 100644 docs/developers/backend/core/_assets/forms-models.mmd

diff --git a/docs/developers/backend/core/_assets/forms-models.mmd b/docs/developers/backend/core/_assets/forms-models.mmd
new file mode 100644
index 0000000000..c6409623ee
--- /dev/null
+++ b/docs/developers/backend/core/_assets/forms-models.mmd
@@ -0,0 +1,46 @@
+---
+Forms model relationship
+---
+erDiagram
+Category {
+    UUIDField uuid
+    CharField path
+    CharField name
+}
+Form {
+    UUIDField uuid
+    SlugField slug
+    CharField name
+    ForeignKey category
+}
+FormDefinition {
+    UUIDField uuid
+    CharField name
+    SlugField slug
+    JSONField configuration
+    BooleanField login_required
+    BooleanField is_reusable
+}
+FormStep {
+    UUIDField uuid
+    SlugField slug
+    ForeignKey form
+    ForeignKey form_definition
+    BooleanField is_applicable
+}
+FormVariable {
+    ForeignKey form
+    ForeignKey form_definition
+    TextField name
+    TextField key
+    CharField source
+    CharField data_type
+    CharField data_format
+    BooleanField is_sensitive_data
+    JSONField initial_value
+}
+Form }|--|| Category : category
+FormStep }|--|| Form : form
+FormStep }|--|| FormDefinition : form_definition
+FormVariable }|--|| Form : form
+FormVariable }|--|| FormDefinition : form_definition
diff --git a/docs/developers/backend/core/formio.rst b/docs/developers/backend/core/formio.rst
index d71fc23082..d6b308f087 100644
--- a/docs/developers/backend/core/formio.rst
+++ b/docs/developers/backend/core/formio.rst
@@ -20,6 +20,62 @@ the code for this is organized in the ``openforms.formio`` package.
     and all of the separate registries (formatters, normalizers...) were merged into a
     single compoment registry.
 
+Form.io configuration
+=====================
+
+A form.io configuration is an object containing a ``"components"`` key mapped to an array of objects
+representing the definition of form components for a specific form step.
+The following is an example of such a configuration:
+
+.. code-block:: json
+
+    {
+        "display": "form",
+        "components": [
+            {
+                "type": "textfield",
+                "key": "field_1",
+                "label": "Field 1"
+            },
+            {
+                "type": "number",
+                "key": "field_2",
+                "label": "Field 2"
+            }
+        ]
+    }
+
+Whenever a submission is created, submission data will be attached to it. The layout of this submission
+data will depend on the components configuration. For instance, with the example configuration given above,
+submission data will look like:
+
+.. code-block:: json
+
+    {
+        "field_1": "some_value",
+        "field_2": 1
+    }
+
+
+Components can be roughly categorised as layout and data components. Layout components don't have
+a matching entry in the submission data.
+
+Every component has two required properties:
+
+* ``"key"``: A unique identifier across the form. The key represents a structured path "into" the submission
+  data. A period (``.``) represents a level of nesting in this data.
+* ``"type"``: The corresponding component type.
+
+.. note::
+
+    Submission data should be interpreted along with components configuration, as it is impossible
+    to determine how data needs to be handled without this context. At times, the submission data
+    can also influence the component configuration, e.g. with conditionals expressing when a component
+    is visible or not.
+
+The `form.io playground`_ can be used to play with the different components and how the submission data will
+look like.
+
 Supported features
 ==================
 
@@ -132,3 +188,4 @@ Module: ``openforms.formio.rendering``
     :members:
 
 .. _form.io: https://www.form.io/
+.. _form.io playground: https://formio.github.io/formio.js/app/builder
diff --git a/docs/developers/backend/core/index.rst b/docs/developers/backend/core/index.rst
index ed057de8eb..f1628fef06 100644
--- a/docs/developers/backend/core/index.rst
+++ b/docs/developers/backend/core/index.rst
@@ -25,3 +25,21 @@ The following Django apps are considered core functionality:
   operations
 
 .. _form.io: https://www.form.io/
+
+Data model
+==========
+
+The following is a simplified relationship diagram of the Django models that relates to forms:
+
+.. mermaid:: _assets/forms-models.mmd
+
+Each :class:`~openforms.forms.models.Form` can have multiple :class:`~openforms.forms.models.FormStep`'s
+defined, which acts as a proxy model to a :class:`~openforms.forms.models.FormDefinition`
+(as these can be reusable across forms). The :class:`~openforms.forms.models.FormDefinition` model
+has a ``configuration`` JSON field, holding the form.io configuration.
+
+The submissions data model mirrors this model in some way:
+
+- A :class:`~openforms.submissions.models.Submission` is tied to a :class:`~openforms.forms.models.Form`.
+- A :class:`~openforms.submissions.models.SubmissionStep` is tied to a :class:`~openforms.forms.models.FormStep`.
+- A :class:`~openforms.submissions.models.SubmissionValueVariable` is tied to a :class:`~openforms.forms.models.FormVariable`.