rougail/docs/structured_data.rst

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

Definition
------------

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

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

A basic structure file is composed of:

- a YAML 1.2 standard header
- a version attribute

.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_000/firefox/00-proxy.yml
   :language: yaml
   :caption: An empty Rougail structure file.
   :name: RougailStructureFirstVariableDescription

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

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

   The Rougail process from structure files to Tiramisu valition handler object

The structured data
---------------------

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.

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

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.

If you want to see the contents of a structure file, you can have a look at the :ref:`tutorial with a real world sample. <tutorial>`