Editing YAML (section)

==Design==
===Syntax===

A cheat sheet and full specification are available at the official site.<ref>{{cite web |url=https://yaml.org/refcard.html |title=YAML{{nbsp}}1.1 Reference Card |website=YAML.org |access-date=2019-05-29 |archive-date=2019-04-14 |archive-url=https://web.archive.org/web/20190414205255/https://yaml.org/refcard.html |url-status=live }}</ref> The following is a synopsis of the basic elements.

YAML accepts the entire Unicode character set, except for some [[control character]]s, and may be encoded in any one of [[UTF-8]], [[UTF-16]] or [[UTF-32]]. (Though UTF-32 is not mandatory, it is required for a parser to have [[JSON]] compatibility.)<ref>{{cite web|url=https://yaml.org/spec/1.2/spec.html#id2771184|title=YAML Ain't Markup Language (YAML) Version 1.2|website=YAML.org|access-date=2019-05-29|archive-date=2019-01-24|archive-url=https://web.archive.org/web/20190124222648/https://yaml.org/spec/1.2/spec.html#id2771184|url-status=live}}</ref>

* [[Whitespace (computer science)|Whitespace]] [[Indent style|indentation]] is used for denoting structure; however, [[tab character]]s are not allowed as part of that indentation.<ref name="YAML v1.2.2">{{cite web|url=https://yaml.org/spec/1.2.2/#indentation-spaces|title=YAML specification v1.2.2 Section 6.1. Indentation Spaces|access-date=2023-03-12|archive-date=2023-03-12|archive-url=https://web.archive.org/web/20230312144139/https://yaml.org/spec/1.2.2/#indentation-spaces|url-status=live}}</ref>
* [[Comment (computer programming)|Comments]] begin with the [[number sign]] ({{code|#}}), can start anywhere on a line and continue until the end of the line. Comments must be separated from other tokens by whitespace characters.<ref>{{cite web|url=https://yaml.org/spec/1.2/spec.html#id2780069|title=YAML Ain't Markup Language (YAML) Version 1.2|website=YAML.org|access-date=2019-05-29|archive-date=2019-01-24|archive-url=https://web.archive.org/web/20190124222648/https://yaml.org/spec/1.2/spec.html#id2780069|url-status=live}}</ref> If {{code|#}} characters appear inside of a string, then they are number sign ({{code|#}}) literals.
* List members are denoted by a leading [[Hyphen-minus|hyphen]] ({{code|-}}) with one member per line.
** A list can also be specified by enclosing text in [[square brackets]] ({{code|[...]}}) with each entry separated by a [[Comma (punctuation)|comma]].
* An [[associative array]] entry is represented using [[colon (punctuation)|colon]] [[Space (punctuation)|space]] in the form ''key: value'' with one entry per line. YAML requires the colon be followed by a space so that url-style strings like {{code|http://www.wikipedia.org}} can be represented without needing to be enclosed in quotes.
** A [[question mark]] can be used in front of a key, in the form "?key: value" to allow the key to contain leading dashes, square brackets, etc., without quotes.
** An associative array can also be specified by text enclosed in [[curly braces]] ({{code|{...} }}), with keys separated from values by colon and the entries separated by commas (spaces are not required to retain compatibility with JSON).
* [[String (computer science)|String]]s (one type of scalar in YAML) are ordinarily unquoted, but may be enclosed in [[double quote|double-quotes]] ({{code|"}}), or [[single quote|single-quotes]] ({{code|'}}).
** Within double-quotes, special characters may be represented with [[C (programming language)|C-style]] escape sequences starting with a [[backslash]] ({{code|\}}). According to the documentation the only octal escape supported is {{code|\0}}.
** Within single quotes the only supported escape sequence is a doubled single quote ({{code|''}}) denoting the single quote itself as in {{code|'don''t'}}.
* Block scalars are delimited with [[Indent style|indentation]] with optional modifiers to preserve (<code>|</code>) or fold ({{code|>}}) newlines.
* Multiple documents within a single stream are separated by three [[hyphens]] ({{code|---}}).
** Three [[Full stop|periods]] ({{code|...}}) optionally end a document within a stream.
* Repeated nodes are initially denoted by an [[ampersand]] ({{code|&}}) and thereafter referenced with an [[asterisk]] ({{code|*}}).
* Nodes may be labeled with a type or tag using a double [[exclamation mark]] ({{code|!!}}) followed by a string, which can be expanded into a URI.
* YAML documents in a stream may be preceded by 'directives' composed of a [[percent sign]] ({{code|%}}) followed by a name and space-delimited parameters. Two directives are defined in YAML 1.1:
** The %YAML directive is used for identifying the version of YAML in a given document.
** The %TAG directive is used as a shortcut for URI prefixes. These shortcuts may then be used in node type tags.

===Basic components===

Conventional block format uses a hyphen+space to begin a new item in list.
<syntaxhighlight lang="yaml">
--- # Favorite movies
- Casablanca
- North by Northwest
- The Man Who Wasn't There
</syntaxhighlight>

Optional inline format is delimited by comma+space and enclosed in brackets (similar to [[JavaScript Object Notation|JSON]]).<ref>{{cite web |url=http://www.jigocloud.com/en/blog/yaml-is-json |title=Cloud Based Management apps |website=JigoCloud.com |access-date=2016-09-28 |archive-url=https://web.archive.org/web/20160917202144/http://www.jigocloud.com/en/blog/yaml-is-json |archive-date=2016-09-17 |url-status=dead }}</ref>
<syntaxhighlight lang="yaml">
--- # Shopping list
[milk, pumpkin pie, eggs, juice]
</syntaxhighlight>

Keys are separated from values by a colon+space. Indented blocks, common in YAML data files, use indentation and new lines to separate the key/value pairs. Inline blocks, common in YAML data streams, use comma+space to separate the key/value pairs between braces.
<syntaxhighlight lang="yaml">
--- # Indented Block
  name: John Smith
  age: 33
--- # Inline Block
{name: John Smith, age: 33}
</syntaxhighlight>

Strings do not require quotation marks. There are two ways to write multi-line strings, one preserving newlines (using the <code>|</code> character) and one that folds the newlines (using the {{code|>}} character), both followed by a newline character.

<syntaxhighlight lang="yaml">
data: |
   There once was a tall man from Ealing
   Who got on a bus to Darjeeling
       It said on the door
       "Please don't sit on the floor"
   So he carefully sat on the ceiling
</syntaxhighlight>

By default, the leading indentation (of the first line) and trailing whitespace are stripped, though other behavior can be explicitly specified.

<syntaxhighlight lang="yaml">
data: >
   Wrapped text
   will be folded
   into a single
   paragraph

   Blank lines denote
   paragraph breaks
</syntaxhighlight>
Folded text converts newlines to spaces and removes leading whitespace.

<syntaxhighlight lang="yaml">
--- # The Smiths
- {name: John Smith, age: 33}
- name: Mary Smith
  age: 27
- [name, age]: [Rae Smith, 4]   # sequences as keys are supported
--- # People, by gender
men: [John Smith, Bill Jones]
women:
  - Mary Smith
  - Susan Williams
</syntaxhighlight>

Objects and lists are important components in yaml and can be mixed. The first example is a list of key-value objects, all people from the Smith family. The second lists them by gender; it is a key-value object containing two lists.

===Advanced components===
Two features that distinguish YAML from the capabilities of other data-serialization languages are structures<ref name=yaml_structures>{{cite web|title=YAML 1.2 specification of Structures|url=https://yaml.org/spec/1.2/spec.html#id2760395|website=YAML.org|access-date=2019-05-29|archive-date=2019-01-24|archive-url=https://web.archive.org/web/20190124222648/https://yaml.org/spec/1.2/spec.html#id2760395|url-status=live}}</ref> and data typing.

YAML structures enable storage of multiple documents within a single file, usage of references for repeated nodes, and usage of arbitrary nodes as keys.<ref name="yaml_structures"/>

For clarity, compactness, and avoiding data entry errors, YAML provides node anchors (using {{code|&}}) and references (using {{code|*}}). References to the anchor work for all data types (see the ship-to reference in the example below).

Below is an example of a queue in an instrument sequencer in which two steps are referenced without being fully described.

<syntaxhighlight lang="yaml">
--- # Sequencer protocols for Laser eye surgery
- step:  &id001                  # defines anchor label &id001
    instrument:      Lasik 2000
    pulseEnergy:     5.4
    pulseDuration:   12
    repetition:      1000
    spotSize:        1mm

- step: &id002
    instrument:      Lasik 2000
    pulseEnergy:     5.0
    pulseDuration:   10
    repetition:      500
    spotSize:        2mm
- Instrument1: *id001   # refers to the first step (with anchor &id001)
- Instrument2: *id002   # refers to the second step
</syntaxhighlight>

Explicit data typing is seldom seen in the majority of YAML documents since YAML autodetects simple types. Data types can be divided into three categories: core, defined, and user-defined. Core are ones expected to exist in any parser (e.g. floats, ints, strings, lists, maps, ...). Many more advanced data types, such as binary data, are defined in the YAML specification but not supported in all implementations. Finally YAML defines a way to extend the data type definitions locally to accommodate user-defined classes, structures or primitives (e.g. quad-precision floats).

YAML autodetects the datatype of the entity, but sometimes one wants to cast the datatype explicitly. The most common situation is where a single-word string that looks like a number, Boolean or tag requires disambiguation by surrounding it with quotes or using an explicit datatype tag.

<syntaxhighlight lang="yaml">
---
a: 123                     # an integer
b: "123"                   # a string, disambiguated by quotes
c: 123.0                   # a float
d: !!float 123             # also a float via explicit data type prefixed by (!!)
e: !!str 123               # a string, disambiguated by explicit type
f: !!str Yes               # a string via explicit type
g: Yes                     # a Boolean True (yaml1.1), string "Yes" (yaml1.2)
h: Yes we have No bananas  # a string, "Yes" and "No" disambiguated by context.
</syntaxhighlight>

Not every implementation of YAML has every specification-defined data type. These built-in types use a double-exclamation [[Sigil (computer programming)|sigil]] prefix ({{code|!!}}). Particularly interesting ones not shown here are sets, ordered maps, timestamps, and hexadecimal. Here is an example of [[base64]]-encoded binary data.

<syntaxhighlight lang="yaml">
---
picture: !!binary |
  R0lGODdhDQAIAIAAAAAAANn
  Z2SwAAAAADQAIAAACF4SDGQ
  ar3xxbJ9p0qa7R0YxwzaFME
  1IAADs=
</syntaxhighlight>

Many implementations of YAML can support user-defined data types for object serialization. Local data types are not universal data types but are defined in the application using the YAML parser library. Local data types use a single exclamation mark ({{code|!}}).

===Example===

Data-structure hierarchy is maintained by outline indentation.

<syntaxhighlight lang="yaml">
---
receipt:     Oz-Ware Purchase Invoice
date:        2012-08-06
customer:
    first_name:   Dorothy
    family_name:  Gale

items:
    - part_no:   A4786
      descrip:   Water Bucket (Filled)
      price:     1.47
      quantity:  4

    - part_no:   E1628
      descrip:   High Heeled "Ruby" Slippers
      size:      8
      price:     133.7
      quantity:  1

bill-to:  &id001
    street: |
            123 Tornado Alley
            Suite 16
    city:   East Centerville
    state:  KS

ship-to:  *id001

specialDelivery:  >
    Follow the Yellow Brick
    Road to the Emerald City.
    Pay no attention to the
    man behind the curtain.
...
</syntaxhighlight>

Notice that strings do not require enclosure in quotation marks. The specific number of spaces in the indentation is unimportant as long as parallel elements have the same left justification and the hierarchically nested elements are indented further. This sample document defines an associative array with 7 top level keys: one of the keys, "items", contains a 2-element list, each element of which is itself an associative array with differing keys. Relational data and redundancy removal are displayed: the "ship-to" associative array content is copied from the "bill-to" associative array's content as indicated by the anchor ({{code|&}}) and reference ({{code|*}}) labels. Optional blank lines can be added for readability. Multiple documents can exist in a single file/stream and are separated by {{code|---}}. An optional {{code|...}} can be used at the end of a file (useful for signaling an end in streamed communications without closing the pipe).