The structure file and data

What contains exactly a structure file?

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

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

Families and variables can be defined in several structure files. These structure files are then aggregated.

File naming convention

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 firefox/00-proxy.yml structure file and file named 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.

Separation of structures into namespaces

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.

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 variable namespace parameter of the 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 when configuring Rougail.

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

%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 writen in Rougail format.

The Rougail process

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 consistency management tool can check the consistency of the variables between them.

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

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.