YAML: Difference between revisions

From NovaOrdis Knowledge Base
Jump to navigation Jump to search
 
(102 intermediate revisions by the same user not shown)
Line 4: Line 4:
* http://yaml.org
* http://yaml.org
* http://docs.ansible.com/ansible/YAMLSyntax.html
* http://docs.ansible.com/ansible/YAMLSyntax.html
* Using YAML for Java Application Configuration https://dzone.com/articles/using-yaml-java-application
* Specification https://yaml.org/spec/
=Internal=
* [[Serialization]]
* [[JSON]]


=Overview=
=Overview=
Line 9: Line 15:
YAML is a human-readable data serialization format. YAML syntax was designed to easily map on scalars, list and associative arrays. It is well suited for hierarchical data representation. It does not use enclosures such as quotation marks, brackets, braces and open/close tags, which can be hard fro the human eye to balance in nested hierarchies. Data structure hierarchy is maintained by outline indentation. The specific number of spaces in the indentation is not important as long as parallel elements have the same left justification, and the hierarchically nested elements are indented further.
YAML is a human-readable data serialization format. YAML syntax was designed to easily map on scalars, list and associative arrays. It is well suited for hierarchical data representation. It does not use enclosures such as quotation marks, brackets, braces and open/close tags, which can be hard fro the human eye to balance in nested hierarchies. Data structure hierarchy is maintained by outline indentation. The specific number of spaces in the indentation is not important as long as parallel elements have the same left justification, and the hierarchically nested elements are indented further.


Strings do not require enclosure in quotations.
Strings [[#String|do not require enclosure in quotations]].


The format has support for references, where sections in the document can be referenced, thus eliminating redundancy.
The format has support for references, where sections in the document can be referenced, thus eliminating redundancy.


Multiple documents can exist in a single file/stream and they are separated by "---".  
[[#Embedding_Multiple_Documents_in_One_File|Multiple documents]] can exist in a single file/stream and they are separated by "---".
 
[[#YAML_is_a_Superset_of_JSON|YAML is a superset of JSON]].
 
=Comments=
 
# This is a comment
=Style=
There are two styles: flow and block. In the "flow" style, successive YAML elements are placed on the same line, directly next to each other. This style is different from the "block style", where separate YAML elements are arranged into separate blocks defined by the same indentation.
 
=<span id='Data_Types'></span>Scalars=
 
a: 10
 
YAML auto-detects the data type. A good rule when writing YAML is to quote strings and allow implicit type conversion for everything else.
 
==Devoid of Value==
 
The <tt>null</tt> word is used to indicate a lack of value. This is typically converted into any native null-like value (e.g., null in Java). Note that a null is different from an empty string and that a mapping entry with some key and a null value is valid and different from not having that key in the mapping.


An optional "..." can be used at then of the file - useful for signaling an end in streamed communication without closing the pipe.
b: null


=List=
==Core Data Types==


List elements are designated by hyphen + space:
Strings, ints, floats, lists and maps.


<pre>
<pre>
- Audi
a: 123                      # an integer
- Mercedes
b: "123"                    # a string, disambiguated by quotes
- BMW
c: 123.0                    # a float
d: !!float 123              # a 'casted' float
e: !!str 123                # a 'casted' string
</pre>
</pre>


==Optional In-Line List Format==
===<span id='Boolean_Support'></span>Booleans===
 
<tt>true</tt> and <tt>false</tt> must not be enclosed in quotes to be recognized as booleans.
 
{{Warn|N, n, Y, y are automatically identified as boolean scalars, '''unless enclosed in quotes'''. If you intend to pass the character N as a string value, specify 'N' and not N.}}
 
Boolean scalar support:
 
a: true
a: Y
a: Yes
a: ON
b: false
b: n
b: N
 
c: "true" # string not boolean
 
===Integer===
 
If a integral value is specified as an unquoted bare word, it is treated as a numeric type:
 
count: 1
 
The same quoted value is treated as [[#String|string]]:
 
count: "1" # string not int
 
count: '1' # string not int
 
====Leading-Zero Integer====
 
If using a leading zero (for example <code>09</code>) in a field without quoting the value in single quotes, the value may be interpreted incorrectly by the YAML parser. If the value is a valid octal, it is converted to an integer. If not, is converted to a float.
 
===Float===
 
If a float value is specified as an unquoted bare word, it is treated as a numeric type:
 
size: 32.1
 
The same quoted value is treated as [[#String|string]].
 
size: "32.1" # string not float
 
size: '32.1' # string not float
 
===String===
 
{{Internal|Strings_in_YAML#Overview|Strings in YAML}}
 
==Forced Type Inference==
 
Particular type inference can be forced with the <tt>!!''type''</tt> syntax:
 
age !!str 21 # will be a string, equivalent with "21"
port: !!int 80 # will be an integer, equivalent with bare, unquoted 80
 
==Defined Data Types==
 
==User-Defined Data Types==
 
=Collections=
 
There are two types of collections: [[#List|lists (or sequences)]] and [[#Associative_Array|associative arrays (or maps)]].
 
==<span id='List'><span>List (or Sequence)==
 
List elements are designated by hyphen + space, and have the same offset:
 
- Audi
- Mercedes
- BMW
 
A list may contain a combination of "simple" elements and "complex" elements:
 
- simple
- complex:
    key1: val1
    key2: val2
 
===Optional In-Line List Format===


List elements are enclosed in brackets, and the list elements are separated by comma + space.
List elements are enclosed in brackets, and the list elements are separated by comma + space.


<pre>
cars: ['Audi', 'BMW', 'Chevrolet']
cars: ['Audi', 'BMW', 'Chevrolet']
</pre>


=Associative Array=
==<span id='Associative_Array'></span>Associative Array (or Map)==


Keys are separated from values by a colon + space.  
Keys are separated from values by a colon + space.  


<pre>
  name: Audi
    name: Audi
  color: black
    color: black
  capacity: 5
    capacity: 5
</pre>


==Optional In-Line Associative Array Format==
===Optional In-Line Associative Array Format===


Associative array element are enclosed in braces, and they key: value pairs are separated by comma + space.
Associative array element are enclosed in braces, and they key: value pairs are separated by comma + space.


<pre>
car: {brand: Audi, color: black, type: sedan}
car: {brand: Audi, color: black, type: sedan}
 
</pre>
=Composite Collections=
Collections can be combined:
 
==List of Associative Arrays==
 
- country: AU
  price: 6990000
- country: AT
  price: 4990000
- country: BE
  price: 4990000
 
The elements of an (associative array) list entry have the same indentation relative to each other, including the first one that follows the "-".
 
==Associative Array of Associative Arrays==
 
<font color=darkgray>TODO, test:</font>
 
command:
  command-a:
    option-1: value-1
    option-2: value-2
  command-b:
    option-1: value-1
    option-2: value-2
=<span id='Multi-line_Support'></span>Multi-Line String Support=
 
{{Internal|Strings in YAML|Strings in YAML}}
 
=Embedding Multiple Documents in One File=
 
It is possible to place more than one YAML documents into a single file. This is done by prefixing a new document with '---' and ending the document with '...'
<syntaxhighlight lang='yaml'>
---
document: 1
...
---
document: 2
...
</syntaxhighlight>
 
In many cases, either '---' or '...' may be omitted. The optional "..." is useful for signaling an end in streamed communication without closing the pipe.
 
<syntaxhighlight lang='yaml'>
---
document: 1
---
document: 2
</syntaxhighlight>
 
=YAML is a Superset of JSON=
 
Because YAML is a superset of JSON, any valid JSON document should be valid YAML. A YAML parser should understand JSON. See http://yaml.org/spec/1.2/spec.html#id2759572


=List of Associative Arrays=
JSON can be mixed into YAML, for the benefit of readability:


<pre>
<syntaxhighlight lang='yaml'>
- country: AU
coffees: [ "Latte", "Cappuccino", "Espresso" ]
  price: 6990000
</syntaxhighlight>
- country: AT
  price: 4990000
- country: BE
  price: 4990000
</pre>


=Associative Array of Associative Arrays=
is equivalent with:
<syntaxhighlight lang='yaml'>
coffees:
- Latte
- Cappuccino
- Espresso
</syntaxhighlight>


<font color=red>TODO, test:</font>
=Conversion between YAML and JSON=
{{Internal|Conversion between YAML and JSON|Conversion between YAML and JSON}}


<pre>
=<span id='Anchors'></span>Anchors, Aliases and Overrides=
command:
{{External|https://yaml.org/spec/1.2.2/#3222-anchors-and-aliases}}
  command-a:
{{External|https://support.atlassian.com/bitbucket-cloud/docs/yaml-anchors/}}
    option-1: value-1
{{External|https://helm.sh/docs/chart_template_guide/#yaml-anchors}}
    option-2: value-2
  command-b:
    option-1: value-1
    option-2: value-2
</pre>


=String=
YAML anchors and aliases cannot contain the <code>[</code>, <code>]</code>, <code>{</code>, <code>}</code>, and <code>,</code> characters.


Strings do not require quotation.
==Anchor==
The anchor is introduced with an <code>&</code> (ampersand) and lets you mark a YAML node (object) with the purpose of referring it later in the same document. The anchor name can then be invoked with an [[#Alias|alias]]. Note that <code>&</code> must '''precede''' the node:


Multi-line strings can be written using the '|' character followed by a new line. Trailing white space is stripped.
<syntaxhighlight lang='yaml'>
suffix: &default_suffix 'py'
</syntaxhighlight>


<pre>
This notation marks the string 'py' with the anchor <code>default_suffix</code>.
data: |
  This is a
  multi-line
  text section
</pre>


The '>' character followed by a new line folds all the new lines, after removing trailing white space.
It is acceptable to use the same name for the key and the anchor name:
<syntaxhighlight lang='yaml'>
suffix: &suffix 'py'
</syntaxhighlight>


<pre>
==Alias==
data: >
The value of a node that was previously marked with an [[#Anchor|anchor]] by using <code>&</code> can be inserted in the document by using the syntax <code>*<anchor_name></code> an arbitrary number of times. This syntax is called an alias. The alias refers to the most recent preceding node having the same anchor. It is an error for an alias node to use an anchor that does not previously occur in the document. Note that an alias node must not specify any properties or content, as these were already specified at the first occurrence of the node.
  This is another
  multi-line
  text section
</pre>


=Data Types=
Do NOT introduce spaces between <code>*</code> and anchor name, the YAML parser will fail.


YAML auto-detects the datatype
For example:


==Core Data Types==
<syntaxhighlight lang='yaml'>
suffix: &default_suffix 'py'
suffixes:
- 'java'
- 'sh'
- *default_suffix
</syntaxhighlight>


Strings, ints, floats, lists and maps.
is equivalent with:
<syntaxhighlight lang='yaml'>
suffix: 'py'
suffixes:
- 'java'
- 'sh'
- 'py'
</syntaxhighlight>


<pre>
==Override==
a: 123                      # an integer
<code><<:</code>
b: "123"                    # a string, disambiguated by quotes
c: 123.0                    # a float
d: !!float 123              # a 'casted' float
e: !!str 123                # a 'casted' string
</pre>


==Defined Data Types==
=YAML support in Java=


==User-Defined Data Types==
<blockquote style="background-color: #f9f9f9; border: solid thin lightgrey;">
: [[YAML_conversion_to_JSON_with_Jackson|Jackson]]
:[[snakeyaml]]
:[[YamlBeans]]
</blockquote>

Latest revision as of 20:07, 4 October 2023

External

Internal

Overview

YAML is a human-readable data serialization format. YAML syntax was designed to easily map on scalars, list and associative arrays. It is well suited for hierarchical data representation. It does not use enclosures such as quotation marks, brackets, braces and open/close tags, which can be hard fro the human eye to balance in nested hierarchies. Data structure hierarchy is maintained by outline indentation. The specific number of spaces in the indentation is not important as long as parallel elements have the same left justification, and the hierarchically nested elements are indented further.

Strings do not require enclosure in quotations.

The format has support for references, where sections in the document can be referenced, thus eliminating redundancy.

Multiple documents can exist in a single file/stream and they are separated by "---".

YAML is a superset of JSON.

Comments

# This is a comment

Style

There are two styles: flow and block. In the "flow" style, successive YAML elements are placed on the same line, directly next to each other. This style is different from the "block style", where separate YAML elements are arranged into separate blocks defined by the same indentation.

Scalars

a: 10

YAML auto-detects the data type. A good rule when writing YAML is to quote strings and allow implicit type conversion for everything else.

Devoid of Value

The null word is used to indicate a lack of value. This is typically converted into any native null-like value (e.g., null in Java). Note that a null is different from an empty string and that a mapping entry with some key and a null value is valid and different from not having that key in the mapping.

b: null

Core Data Types

Strings, ints, floats, lists and maps.

a: 123                      # an integer
b: "123"                    # a string, disambiguated by quotes
c: 123.0                    # a float
d: !!float 123              # a 'casted' float
e: !!str 123                # a 'casted' string

Booleans

true and false must not be enclosed in quotes to be recognized as booleans.


N, n, Y, y are automatically identified as boolean scalars, unless enclosed in quotes. If you intend to pass the character N as a string value, specify 'N' and not N.

Boolean scalar support:

a: true
a: Y
a: Yes
a: ON
b: false
b: n
b: N
c: "true" # string not boolean

Integer

If a integral value is specified as an unquoted bare word, it is treated as a numeric type:

count: 1

The same quoted value is treated as string:

count: "1" # string not int
count: '1' # string not int

Leading-Zero Integer

If using a leading zero (for example 09) in a field without quoting the value in single quotes, the value may be interpreted incorrectly by the YAML parser. If the value is a valid octal, it is converted to an integer. If not, is converted to a float.

Float

If a float value is specified as an unquoted bare word, it is treated as a numeric type:

size: 32.1

The same quoted value is treated as string.

size: "32.1" # string not float
size: '32.1' # string not float

String

Strings in YAML

Forced Type Inference

Particular type inference can be forced with the !!type syntax:

age !!str 21 # will be a string, equivalent with "21"
port: !!int 80 # will be an integer, equivalent with bare, unquoted 80

Defined Data Types

User-Defined Data Types

Collections

There are two types of collections: lists (or sequences) and associative arrays (or maps).

List (or Sequence)

List elements are designated by hyphen + space, and have the same offset:

- Audi
- Mercedes
- BMW

A list may contain a combination of "simple" elements and "complex" elements:

- simple
- complex:
    key1: val1
    key2: val2

Optional In-Line List Format

List elements are enclosed in brackets, and the list elements are separated by comma + space.

cars: ['Audi', 'BMW', 'Chevrolet']

Associative Array (or Map)

Keys are separated from values by a colon + space.

 name: Audi
 color: black
 capacity: 5

Optional In-Line Associative Array Format

Associative array element are enclosed in braces, and they key: value pairs are separated by comma + space.

car: {brand: Audi, color: black, type: sedan}

Composite Collections

Collections can be combined:

List of Associative Arrays

- country: AU
  price: 6990000
- country: AT
  price: 4990000
- country: BE
  price: 4990000

The elements of an (associative array) list entry have the same indentation relative to each other, including the first one that follows the "-".

Associative Array of Associative Arrays

TODO, test:

command:
  command-a:
    option-1: value-1
    option-2: value-2
  command-b:
    option-1: value-1
    option-2: value-2

Multi-Line String Support

Strings in YAML

Embedding Multiple Documents in One File

It is possible to place more than one YAML documents into a single file. This is done by prefixing a new document with '---' and ending the document with '...'

---
document: 1
...
---
document: 2
...

In many cases, either '---' or '...' may be omitted. The optional "..." is useful for signaling an end in streamed communication without closing the pipe.

---
document: 1
---
document: 2

YAML is a Superset of JSON

Because YAML is a superset of JSON, any valid JSON document should be valid YAML. A YAML parser should understand JSON. See http://yaml.org/spec/1.2/spec.html#id2759572

JSON can be mixed into YAML, for the benefit of readability:

coffees: [ "Latte", "Cappuccino", "Espresso" ]

is equivalent with:

coffees: 
- Latte
- Cappuccino
- Espresso

Conversion between YAML and JSON

Conversion between YAML and JSON

Anchors, Aliases and Overrides

https://yaml.org/spec/1.2.2/#3222-anchors-and-aliases
https://support.atlassian.com/bitbucket-cloud/docs/yaml-anchors/
https://helm.sh/docs/chart_template_guide/#yaml-anchors

YAML anchors and aliases cannot contain the [, ], {, }, and , characters.

Anchor

The anchor is introduced with an & (ampersand) and lets you mark a YAML node (object) with the purpose of referring it later in the same document. The anchor name can then be invoked with an alias. Note that & must precede the node:

suffix: &default_suffix 'py'

This notation marks the string 'py' with the anchor default_suffix.

It is acceptable to use the same name for the key and the anchor name:

suffix: &suffix 'py'

Alias

The value of a node that was previously marked with an anchor by using & can be inserted in the document by using the syntax *<anchor_name> an arbitrary number of times. This syntax is called an alias. The alias refers to the most recent preceding node having the same anchor. It is an error for an alias node to use an anchor that does not previously occur in the document. Note that an alias node must not specify any properties or content, as these were already specified at the first occurrence of the node.

Do NOT introduce spaces between * and anchor name, the YAML parser will fail.

For example:

suffix: &default_suffix 'py'
suffixes:
 - 'java'
 - 'sh'
 - *default_suffix

is equivalent with:

suffix: 'py'
suffixes:
 - 'java'
 - 'sh'
 - 'py'

Override

<<:

YAML support in Java

Jackson
snakeyaml
YamlBeans