rougail/docs/structured_data.rst

The structure file and data
============================

What contains exactly a :term:`structure file`?
-------------------------------------------------

.. glossary::

   structure file

       A structure file in the Rougail meaning is a YAML file that describes variables
       and their dependencies.
       There can be a lot of structure files located in many different folders.

       Rougail reads all the structure files and loads them into a single object
       that represents the whole :term:`context`.

A :term:`structure file` is a YAML file whose structure is described in this documentation page.

A structure file contains a set of variables, usable in your application, for example in a template
to generate configuration files.

:term:`Families <family>` and :term:`variables <variable>` can be defined in several structure files. These structure files are then aggregated.

Separation of structures into namespaces
----------------------------------------

A namespace is a way to organize and group related variables under a unique name.

It:

- to avoid naming conflicts
- permet logical grouping: related variables can be grouped together
- scope control: namespaces limit the visibility of variable to the namespace itself

By default there is no namespace.

The default namespace
~~~~~~~~~~~~~~~~~~~~~

The families and variables contained in these structure files are ordered, by default, in the `rougail` namespace. It is possible to change the name of this namespace with the :term:`variable namespace <variable_namespace>` parameter of the :doc:`configuration <configuration>`.

This namespace (the default namespace) is a bit special, it can access variables in another namespace.

The extra structure files
~~~~~~~~~~~~~~~~~~~~~~~~~~~

An extra is a different namespace. The idea is to be able to classify the variables by theme.

Extra namespaces must be declared :doc:`when configuring Rougail <configuration>`.

In this namespace we cannot access variables from another `extra` namespace. 
On the other hand, it is possible to access the variable of the default namespace.

The header of a structure file
-----------------------------------

A basic structure file is composed of:

- a YAML 1.2 standard header
- a version attribute

.. code-block:: yaml

    %YAML 1.2
    ---
    version: 1.1
    ...

The structure file processing
----------------------------------

The structured files contain information that will be used by the consistency handling system for structure validation. 
This is what we call structured data write in Rougail format.

.. figure:: images/schema.png
   :alt: The Rougail process
   :align: center

   The Rougail process from structure files to Tiramisu valition handler object

A variable-first DSL
-----------------------

All of the declaring variables and writing consistency is as simple as writing YAML.

We can declare variables and describe the relationships between variables in a declarative style (that is, in a YAML file).

Once the structure files are loaded by Rougail, the Tiramisu configuration management tool can check the consistency of the variables between them.

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