[PATCH 1/1] docs: add note on YAML support and its limitations

[Felix Moessbauer]

As kas internally uses PyYAML to parse YAML documents, only version 1.1
of the spec is supported. Further, the parser does not correctly handle
non string keys of mappings (they are parsed as-is instead of being
converted to strings on parsing), violating Section 8.2.1 of the YAML
1.1 spec.

We document these limitations in the project configuration along with
workarounds.

Reported-by: Cedric Hombourger <cedric.h...@siemens.com>
Signed-off-by: Felix Moessbauer <felix.mo...@siemens.com>
---
docs/userguide/project-configuration.rst | 11 +++++++++--
1 file changed, 9 insertions(+), 2 deletions(-)

diff --git a/docs/userguide/project-configuration.rst b/docs/userguide/project-configuration.rst
index d17acc925..b7137ad13 100644
--- a/docs/userguide/project-configuration.rst
+++ b/docs/userguide/project-configuration.rst
@@ -3,8 +3,8 @@
Project Configuration
=====================

-Currently, JSON and YAML are supported as the base file formats. Since YAML is
-arguably easier to read, this documentation focuses on the YAML format.
+Currently, JSON and YAML 1.1 are supported as the base file formats. Since YAML
+is arguably easier to read, this documentation focuses on the YAML format.

.. code-block:: yaml

@@ -65,6 +65,13 @@ In given examples we assume that your configuration file is part of a
append entries in files that include this configuration by naming an entry
the same (overwriting) or using an unused name (appending).

+.. note::
+ kas internally uses ``PyYAML`` to parse YAML documents, inheriting its
+ limitations. Notably, ``PyYAML`` only supports YAML 1.1 and does not
+ correctly handle non-string keys in mappings. To avoid this issue, we
+ recommend quoting keys of other types, such as octal numbers (``0001``),
+ integers (``42``), booleans (``false``) and special values (``no``).
+
Including in-tree configuration files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

--
2.49.0

[Jan Kiszka]

Thanks, applied.

Jan

--
Siemens AG, Foundational Technologies
Linux Expert Center