Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Branch: master
Fetching contributors…

Cannot retrieve contributors at this time

203 lines (176 sloc) 5.619 kB
<?xml version="1.0"?>
<!DOCTYPE article
PUBLIC "-//OASIS//DTD DocBook V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<article>
<articleinfo>
<title>
YAML Encoding Keys Language-Independent Type for
<trademark>YAML</trademark>&nbsp;Version&nbsp;1.1
</title>
<subtitle>
Working Draft 2005-01-18
</subtitle>
<authorgroup>
<author>
<firstname>Oren</firstname>
<surname>Ben-Kiki</surname>
<email>oren@ben-kiki.org</email>
</author>
<author>
<firstname>Clark</firstname>
<surname>Evans</surname>
<email>cce+yaml@clarkevans.com</email>
</author>
<author>
<firstname>Brian</firstname>
<surname>Ingerson</surname>
<email>ingy@ttul.org</email>
</author>
</authorgroup>
<copyright>
<year>2001-2005</year>
<holder>Oren Ben-Kiki<fo>,&nbsp;</fo></holder>
<holder>Clark Evans<fo>,&nbsp;</fo></holder>
<holder>Brian Ingerson</holder>
</copyright>
<legalnotice>
This document may be freely copied provided it is not modified.
</legalnotice>
<abstract>
<title>Status</title>
<para>
This specification is a draft reflecting consensus reached by members of
the <ulink
url="http://lists.sourceforge.net/lists/listinfo/yaml-core">yaml-core
mailing list</ulink>. Any questions regarding this draft should be
raised on this list.
</para>
</abstract>
</articleinfo>
<section>
<variablelist>
<varlistentry>
<term>
<para>
URI:
</para>
</term>
<listitem>
<para>
<userinput>tag:yaml.org,2002:yaml</userinput>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<para>
Shorthand:
</para>
</term>
<listitem>
<para>
<userinput>!!yaml</userinput>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<para>
Kind:
</para>
</term>
<listitem>
<para>
Scalar.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<para>
Canonical:
</para>
</term>
<listitem>
<para>
N/A (single format).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<para>
Regexp:
</para>
</term>
<listitem>
<para>
<userinput>!|&amp;|\*</userinput>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<para>
Definition:
</para>
</term>
<listitem>
<para>
Keys for encoding YAML in YAML.
</para>
<para>
YAML encoding keys are used to denote YAML structure information.
The in-memory representation of these keys must be different from
any value in any other type family. Specifically, these in-memory
values must not be implemented as strings. Normally, the encoding
keys should not be used in serialized YAML documents; the encoded
YAML node is serialized instead.
</para>
<para>
Encoding is useful when a YAML processor encounters a valid
YAML value of an unknown tag. For a schema-specific application,
this is not different from encountering any other valid YAML
document that does not satisfy the schema. Such an application may
safely use a processor that rejects any value of any unknown tag,
or discards the tag property with an appropriate warning and parses
the value as if the property was not present.
</para>
<para>
For a schema-independent application (for example, a hypothetical
YAML pretty print application), this is not an option. Processors
used by such applications should encode the value instead. This may
be done by wrapping the value in a mapping containing encoding
keys. The <quote><userinput>!</userinput></quote> key denotes the
unsupported tag. In some cases it may be necessary to encode
anchors and alias nodes as well. The
<quote><userinput>&amp;</userinput></quote> and
<quote><userinput>*</userinput></quote> keys are used for this
purpose.
</para>
<para>
Encoding should be reversed on output, allowing the
schema-independent application to safely round-trip any valid YAML
document. In-memory, the encoded data may be accessed and
manipulated in a standard way using the three basic data types
(mapping, sequence and scalar), allowing limited processing to be
applied to arbitrary YAML data.
</para>
</listitem>
</varlistentry>
</variablelist>
<example>
<title><userinput>!!yaml</userinput> Examples</title>
<programlisting>
# The following node should NOT be serialized this way.
encoded YAML node :
!!yaml '!' : '!type'
!!yaml '&amp;' : 12
!!value = : value
# The proper way to serialize the above node is as follows:
node : !type &amp;12 value
</programlisting>
</example>
</section>
</article>
Jump to Line
Something went wrong with that request. Please try again.