doc(structured data concepts)

docs/concepts.rst

@@ -61,10 +61,10 @@ Structured data is also called the Rougail format.
 
    structured data
 
-       A configuration-first DSL (domain-specific language) designed for describing variables, consistency
+       A variable-first :term:`DSL` (Domain-Specific Language) designed for describing variables, consistency
        and describe the relationships between variables in a declarative style.
 
-       The language is a mix of YAML ans Jinja Templating.
+       The language is a mix of YAML and Jinja Templating.
 
        It goes beyond traditional schema languages (like JSON Schema, OpenAPI, Cuelang)
        by combinig type systems, powerful validation, consistency of the configuration and documentation.
@@ -345,14 +345,6 @@ The properties can be defined permanently or according to the result of a calcul
 
 There is two main properties.
 
-The lifespan of the variables
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-A picture is worth a thousand words:
-
-.. image:: images/dessin.png
-
-
 Hidden variable
 ~~~~~~~~~~~~~~~
 
@@ -369,6 +361,10 @@ A `disabled` variable is a variable that will not be accessible to any of the ac
 
 This property is generally used dynamically to remove access to the variable depending on the context.
 
+A picture is worth a thousand words:
+
+.. image:: images/dessin.png
+
 .. list-table::
    :header-rows: 1
 

docs/structured_data/concepts.rst

@@ -0,0 +1,270 @@
+A variable-first DSL
+===============================
+
+.. glossary::
+
+   DSL
+
+       A DSL stands for **Domain-Specific Language**, it is a programming or markup language designed for a specific application domain.
+       Unlike general-purpose languages (like Python or Java), DSLs are optimized for a narrow set of problems, offering concise syntax and specialized features tailored to their domain.
+
+
+
+Rougail format (or :term:`structured data`) is a DSL (Domain-Specific Language) designed for describing variables and consistency.
+
+Declarative abstraction
+-----------------------
+
+The variables are described using a declarative model.
+This means that the user simply defines the desired final state of the variable.
+Tiramisu will then determine the actions necessary to reach that state.
+
+In other words, the user defines the variable schema, which will then be applied deterministically.
+
+The language is a mix of YAML 1.2 and Jinja Templating.
+
+Each variables are declaring in a mapping object in YAML (the keys are variable properties).
+
+There is an execption. That what we call the short-hand declaration.
+
+.. glossary::
+
+   Short-hand notation
+
+        Shorthand notation allows you to condense as much information as possible when creating a variable.
+        Generally, the declaration is done on a single line (or at most, a very small number of lines).
+
+        Of course, it's not possible to fully customize the variable with this notation.
+
+        Use shorthand notation whenever possible. This makes the file easier to read.
+
+Data integrity
+---------------
+
+Data integrity refers to the fact that data must be reliable and accurate throughout its lifecycle.
+
+This means that the value must be:
+
+- of high quality
+- appropriate to the overall context
+
+Data quality
+~~~~~~~~~~~~
+
+The values of the variables must be individually of good quality.
+
+Typing
+^^^^^^
+
+Strongly-typed
+''''''''''''''
+
+Rougail is a strongly-typed DSL.
+
+This means that loading user data requires attention to the variable types.
+
+.. For untyped user data (such as environment variables), the value type will be adapted during preprocessing.
+
+Dynamicly-typed
+'''''''''''''''
+
+During the structured data definition, the type is dynamic.
+
+That is to say, the integrator can change the type of the variable at any time.
+
+However, the operator who adapts the value does not have the possibility of redefining the type of the variable.
+
+.. seealso:: :doc:`the variable mutability <../concepts>`
+
+Type inference
+''''''''''''''
+
+Type inference is the process where Rougail automatically figures out the types without explicit annotations.
+In fact, the variable type comes from the type of its default value.
+
+The type inference is in particular use in :term:`short-hand notation`.
+
+Standard types
+''''''''''''''
+
+Rougail accepts the following standard types:
+
+- string (default type of a variable)
+- integer
+- float
+- boolean
+
+.. seealso:: :doc:`the variable documentation <variable>`
+
+Specialized type
+''''''''''''''''
+
+But we will also find a whole series of specialized types:
+
+- IP
+- domainname
+- port
+- MAC         
+- choice
+- secret
+- ...
+
+.. seealso:: :doc:`the variable documentation <variable>`
+
+Type parameters
+'''''''''''''''
+
+For certain types, there are a number of parameters that can be used to further type the variables.
+
+.. seealso:: :doc:`the variable documentation <variable>`
+
+Nullable variable
+'''''''''''''''''
+
+The `null` type (or `None` in Python) does not exist in Rougail.
+
+All variables, regardless of their type, can be nullable (see the remarks on the list type below).
+
+Even if all types can accept this value, but by default, they do not.
+
+In reality, the variable is not accessible in `read-only` mode (which is the case during the output steps).
+In `read/write` mode, the access is indeed granted.
+
+.. seealso:: tutorial with a real world sample :doc:`nullable variable <../tutorial/nullable>`
+
+The `list` type
+'''''''''''''''
+
+A list is not a type either.
+It is a property of a variable.
+This means that all type could have multiple value by a list cannot contain values of multiple types.
+
+A multiple variable could be nullable. This means that `null` can be accepted as a value in the list (which is not permitted by default).
+But the multiple variable could also be without value (without is not permitted too by default).
+
+.. seealso:: tutorial with a real world sample :doc:`multiple variable <../tutorial/multiple>`
+
+Family
+''''''
+
+The `mapping` type
+""""""""""""""""""
+
+A mapping is a collection of key: value pairs.
+
+This is a YAML example:
+
+.. code-block:: json
+
+    {
+      "my_variable": "my_value"
+    }
+
+In Rougail the mapping type is call :term:`family`.
+It is a container designed to hold variables.
+
+Families manage the tree structure. It is possible to create subfamilies.
+
+.. seealso:: :doc:`the family documentation <family>`
+
+The dynamically built family
+""""""""""""""""""""""""""""
+
+A dynamically built family is a special family.
+
+.. glossary::
+
+   dynamically built family
+
+        A dynamically built family is a fictitious family linked to a list of uniq identifiers.
+
+        This means that families will appear or disappear folling the context.
+
+.. seealso:: :doc:`the dynamically built family documentation <family>`
+
+Homogeneous elements sequence
+"""""""""""""""""""""""""""""
+
+.. glossary::
+
+   homogeneous elements sequence
+
+        A specific type of mapping, called a `sequence`, allows you to have a list of homogeneous objects.
+
+        For example, if I want to be able to create an unlimited number of users associated with a secret, I can't use lists; I need a list of objects.
+
+        In JSON we will have:
+
+        .. code-block:: json
+
+           [
+                {
+                  "user": "login1",
+                  "secret": "MySecret"
+                },
+                {
+                  "user": "login2",
+                  "secret": "MySecret"
+                }
+           ]
+
+Validation
+^^^^^^^^^^
+
+Type validation is the first and most important check.
+But it is possible to add additional validations.
+
+For example, one might want numbers, but only odd numbers.
+
+Overall coherence
+~~~~~~~~~~~~~~~~~
+
+An isolated variable can be considered to be of quality but become inconsistent depending on the context.
+
+Validation
+^^^^^^^^^^
+
+For example, if a minimum value and then a maximum value are requested, the minimum must be less than the maximum.
+
+Overall consistency is initially managed by personality validators who will validate the value of a variable in relation to others.
+
+Access control
+''''''''''''''
+
+Access control is implemented as soon as an attempt is made to access a variable.
+
+There are two main types of access control:
+
+- Properties
+- Modes
+
+Properties
+""""""""""
+
+We already see the property access control.
+
+Remember, we talked about :doc:`the hidden and disabled variables`.
+
+These properties become fully meaningful when managing overall consistency.
+
+Why ask for the domain name of a service if we haven't activated that service just before?
+
+Mode
+""""
+
+By default, the mode is not configured. It is an optional feature.
+
+Let's start by defining what we want to do with the modes.
+
+We'll present a common example, but you'll need to define your own modes according to your needs.
+
+Here is our classic case of mode definition. We'll use three modes:
+
+- basic: automatically sets mandatory variables without default values (in this case, the actor adapting the configuration will have to enter values) and manually sets variables that the actor defining the variables deems necessary.
+- standard: automatically sets all other variables
+- advanced: sets variables that the actor defining the variables decides to include. These variables are intended for a knowledgeable audience who know what to do.
+
+Documentation
+-------------
+
+FIXME

docs/structured_data/family.rst

@@ -130,10 +130,10 @@ Parameters
    If a subfamily or a subvariable already has the name of a parameter it is possible to use the "_<parameter>" name.
    You can have a look at the tutorial with a real world sample :doc:`of parameter with "_" <tutorial/underscore_parameter>`.
 
-Shorthand declaration
+Short-hand declaration
 ----------------------------
 
-Shorthand declaration is a way to declare a family in a single line.
+Short-hand declaration is a way to declare a family in a single line.
 
 To create a family, just add a key with it's name and variables as values:
 
@@ -160,9 +160,9 @@ It's a best practice to description a family. Just add comment in same line of n
       my_variable:
     ...
 
-But in shorthand notation, you can only define family name and description.
+But in short-hand notation, you can only define family name and description.
 
-.. attention:: Any other parameters will be considered as a variable. Do not use shorthand in this case.
+.. attention:: Any other parameters will be considered as a variable. Do not use short-hand in this case.
 
 A family
 ---------
@@ -191,10 +191,8 @@ Here is a simple example:
 A dynamically built family
 -----------------------------
 
-To create a family dynamically, you must create a fictitious family linked to a list of uniq identifiers.
+To create a :term:`dynamically built family`, you must create a fictitious family linked to a list of uniq identifiers.
-This list could be hard coded or resulting from a calculation
+This list could be hard coded or resulting from a calculation.
-
-In this case if the result of calculation were to evolve, new dynamic families will appear or disappear.
 
 The name of this family is particular. You have to add `{{ identifier }}` string inside. It will be replace by each identifiers.
 

docs/structured_data/index.rst

@@ -8,6 +8,7 @@ Common informations on structured data
    :titlesonly:
    :caption: Structured data
 
+   concepts
    naming_convention
    variable
    family

docs/structured_data/variable.rst

@@ -286,10 +286,10 @@ Parameters
 
        .. important:: This parameter is only available for variable with `regexp` type.
 
-Shorthand declaration
+Short-hand declaration
 ----------------------------
 
-Shorthand declaration is a way to declare a variable in a condenced number of line.
+Short-hand declaration is a way to declare a variable in a condenced number of line.
 
 To create a variable, just add a key with it's name:
 
@@ -338,7 +338,7 @@ It's a best practice to description a variable. Just add comment in same line of
     my_variable: my_value  # This is a great variable
     ...
 
-But in shorthand notation, you can only define variable name, default value, multi and description.
+But in short-hand notation, you can only define variable name, default value, multi and description.
 
 .. attention:: Any other parameters will create extra variables or families
 

docs/tutorial/multiple.rst

@@ -220,6 +220,7 @@ Now we have this output:
 
 .. note:: Note that the value of a :term:`multi` variable which has no default value set and which is not :term:`mandatory`
    will be the empty list `[]`
+   The :term:`mandatory` properties does not means that the `null` value is acceptable (that is the `empty` properties).
 
 .. keypoints:: Key points