Skip to main content

YAML Character Streams

In YAML, you come across various character streams

  • Directives
  • Document Boundary Markers
  • Documents
  • Complete Stream

Let's see in details.

Directives

Directives are basic instructions used in the YAML processor. Directives are presentation details such as comments that are not reflected in the serialization tree.

In YAML, there is no way to define private directives.

Reserved Directives

Reserved directives are initialized with three dashes (---), as shown in the following example.

The reserved directives are converted to a specific JSON value.

%YAML 1.1
--- !!str
"foo"

YAML Directive

YAML Directives are default directives.

When converted to JSON, the retrieved value includes the forward slash character in the preceding and terminating characters.

%YAML 1.1
---
!!str "foo"

Document Boundary Markers

YAML uses Document Boundary Markers to allow more than one document to be contained in one stream.

These markers are specially used to convey the structure of YAML document.

note

A line beginning with --- is used to start a new document.

%YAML 1.1
---
!!str "foo"
%YAML 1.1
---
!!str "bar"
%YAML 1.1
---
!!str "baz"

Documents

YAML document is considered as a single native data structure presented as a single root node.

The presentation details in YAML document such as directives, comments, indentation and styles are not considered as contents included in them.

There are two types of documents used in YAML.

Explicit Documents

An Exmplicit Document begins with the document start marker followed by the presentation of the root node.

---

some: yaml

...

It includes an explicit start and end markers which is --- and ... in given example.

After converting the YAML format to JSON, you get the output shown below:

{
"some": "yaml"
}

Implicit Documents

Implicit Document does not begin with a document start marker.

fruits:
- Apple
- Orange
- Pineapple
- Pear

The JSON output of the given YAML is as follows:

{
"fruits": [
"Apple",
"Orange",
"Pineapple",
"Pear"
]
}

Complete Stream

YAML includes a sequence of bytes called as character stream.

The stream begins with a prefix containing a byte order denoting a character encoding.

The complete stream begins with a prefix containing a character encoding, followed by comments.

An example of complete stream (character stream) is shown below:

%YAML 1.1
---
!!str "Text content\n"