rougail/docs/structured_data/structured_data.rst

The structure file
=======================

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.

File naming convention
--------------------------

.. _filenamingconvention:

The structure files in a given folder
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

For the sake of clarity, we put the structured data in separate files.
It's a good way to organize your rougail structures this way,
in the real world we need separate files for different topics.

For example some files like this:

A file named :file:`firefox/00-proxy.yml` structure file and file named :file:`firefox/10-manual.yml`

::

    .
    └── firefox
        ├── 00-proxy.yml
        └── 10-manual.yml

.. note:: We of course could have put everything in one file.
          Again, it is better to separate the structures in different files 
          for reasons of ordering and clarity.

Ordering your structure files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The order in which files are loaded is important in Rougail. 
In a given folder, files are loaded in alphabetical order.

Furthermore, for better readability of the order in which files are 
loaded into a folder, we have adopted a convention. 
To facilitate classification, we have defined a standard notation for structure file names:

::

    XX-<name>.yml

Where `XX` is a two digits integer followed by an hyphen, and `<name>` is a name that describes 
the structure that is in this file. We advise you to adopt this convention as well.

File naming convention
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

There is no restriction to the `<name>` name part of file name. But it is preferable to only use
lowercase ASCII letters, numbers and the `"_"` (undescore) character. 

.. FIXME: et le moins "-" aussi non ? 

.. _namespace:

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

.. glossary:: 

   namespace

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

It enables us to:

- avoid naming conflicts
- permit 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.

.. _defaultnamespace:

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 <namespace>` parameter of the :ref:`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 :ref:`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 :term:`structure files <structure file>` contain information that will be used by the consistency handling system for structure validation. 
This is what we call :term:`structured data` writen in :term:`Rougail format`.

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

   The Rougail process from structure files to :term:`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 :term:`Tiramisu` consistency 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

       The Rougail format (or :term:`structured data`) is a DSL (Domain-Specific Language) designed for describing variables and their 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.
:term:`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 declared 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.

Versioned format
----------------

The format can evolve. This means that parameters can be added, removed, or modified.
When writing structured data, you must always specify the format version.
You must also ensure that your Rougail version is compatible with your format version.