[#4044] Add more documentation on formio configuration

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

docs/developers/backend/core/formio.rst

@@ -20,6 +20,60 @@ 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.
+
+
 Supported features
 ==================
 

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`.