Serialization
Serialization defines the YAML representation shared by Workfiles and the other YAML document formats in this specification. It converts a YAML character stream into the mappings, sequences, and scalar values used by the Data Model. Serialization does not perform document-structure, catalog, scope, or execution validation.
YAML 1.2 Data Model
Section titled “YAML 1.2 Data Model”A Workfile is a YAML 1.2 document restricted by this section. Connector manifests, filter-package manifests, schema overlays, conformance claims, and other document formats defined as using the serialization rules use the same subset.
The supported representation graph contains only scalars, sequences, and mappings. It contains no aliases, tagged nodes, or graph cycles.
Mapping keys are strings, and sequence order is significant. Maps follow Map Order. Implementations MUST determine a scalar’s lexical spelling and presentation style before host-library type construction and MUST apply the closed Workfile resolution rules below themselves.
A host YAML library’s resolved boolean, number, timestamp, date, null, or other scalar type MUST NOT determine the Workfile value. In particular, the plain key on and the plain values yes, no, on, and off are strings, and a date-shaped plain scalar such as 2026-08-28 is a string.
A conforming implementation MUST accept UTF-8 YAML input. It MAY accept another encoding recognized by YAML 1.2, but alternate-encoding support is not a conformance requirement.
Restricted YAML Subset
Section titled “Restricted YAML Subset”Both block and flow collection styles are permitted. Comments are permitted.
Comments, indentation choices, quoting style, and line-ending representation do not alter the resulting data-model value except where YAML block-scalar rules make content significant.
Scalars
Section titled “Scalars”A non-plain scalar—single-quoted, double-quoted, literal-block, or folded-block—is a string. YAML escape and folding rules are applied before Workfile interpolation or expression parsing.
A plain scalar is resolved by the following closed rules:
| Spelling | Value |
|---|---|
empty, null, or ~ |
null |
true or false |
Corresponding bool. |
0 or -?[1-9][0-9]* |
int, if within its range. |
| Decimal or exponent form described below | Finite float. |
| Every other permitted plain scalar | string. |
A float form has an optional leading - and is either one or more digits, ., one or more digits, and an optional exponent; or one or more digits followed by an exponent. An exponent is e or E, an optional sign, and one or more digits.
Hexadecimal, octal, sexagesimal, comma-separated, leading-plus, .inf, and .nan forms are not numeric Workfile scalars. A scalar matching a Workfile numeric form but outside the corresponding Data Model domain is invalid rather than a string.
The lexical value is determined before a declared type is applied. A plain 123 is therefore an int, not the string "123".
In a position requiring string or an enum member, an author MUST quote a spelling that would otherwise resolve to another scalar type. Implementations MUST NOT coerce it based on the expected type.
A string scalar with no interpolation in a position requiring enum[...] is contextually typed and checked against that enum as defined under Static Typing and Assignability. Duration and timestamp syntax is interpreted only in a position that declares or expressly requires the corresponding type.
Such a value can be quoted or plain. A string-valued expression requires the duration or timestamp conversion filter to produce the corresponding runtime kind.
A type expression can likewise be plain or quoted when the serialization rules resolve it to a string. An interpolation is parsed only where the containing document format permits expressions.
Quoting carries interpolation text through YAML but does not disable interpolation. Mapping keys are never interpolation positions.
A mapping key is the string of its scalar’s decoded lexical spelling. Plain and quoted spellings produce the same key, and scalar resolution does not apply to keys.
Sequences
Section titled “Sequences”A sequence is a finite ordered list. Block and flow sequence styles produce the same value.
An empty sequence is permitted wherever the containing document rule permits a list. Sequence members can be any node in this subset and need not share a runtime type unless the containing position declares an element type.
YAML sequence syntax does not imply a tuple, set, stream, or unordered collection.
Mappings
Section titled “Mappings”A mapping is a finite collection of string-keyed entries. Every key MUST be a scalar; sequences and mappings MUST NOT be used as keys.
After YAML decoding, keys MUST be unique by code-point equality. A duplicate key is invalid even when both entries would have equal values, and an implementation MUST NOT keep only the first or last occurrence.
Block and flow mapping styles produce the same entries.
The key << is prohibited in every mapping, including a mapping treated as user data, whether or not a YAML implementation would assign it merge semantics.
Prohibited Features
Section titled “Prohibited Features”The following YAML features are excluded from the YAML subset, with rejection requirements attached to the individual entries:
- anchors and aliases;
- explicit tags, including application-specific tags;
- a stream containing more than one document;
- complex mapping keys;
- merge-key processing; and
- a representation graph that cannot be expressed solely as the scalar, sequence, and mapping values above.
YAML directives MUST NOT change the version, schema, encoding rules, or tag vocabulary specified here. An implementation MAY accept a %YAML 1.2 directive, but MUST reject an incompatible version directive and every %TAG directive.
The optional --- and ... document markers do not create an additional document and are permitted.
Implementation note. A parser should detect anchors, aliases, explicit tags, << keys, and additional documents at an event, composed-node, or equivalent syntax-tree layer before construction can resolve or discard those features.
This note does not require a particular YAML library or parser interface.
Document Processing and Emission
Section titled “Document Processing and Emission”A YAML stream is processed in this order: YAML syntax and the restricted feature set; scalar resolution into the data model; the applicable document’s structural rules; resolution-dependent static validation; and, for execution, runtime evaluation. Acceptance at one layer does not imply acceptance at a later layer.
Each standard YAML document format MUST have a mapping as its root unless that format expressly says otherwise. An empty stream, a scalar root, or a sequence root is therefore not a Workfile or manifest.
An implementation that emits a standard document as YAML MUST emit one document in this subset whose parsed data model is identical to the value being serialized. It can change comments, layout, collection style, and quoting style as those do not contribute to the parsed value.
Emitted maps follow Map Order. An implementation MAY additionally accept or emit another encoding of the same abstract document format.
An implementation supporting an alternate encoding MUST NOT require that encoding instead of accepting the YAML form required by this specification. The Standard defines one full representation for each construct and declaration, plus only the explicitly defined alternate forms for that construct or declaration.
Only a compact form expressly defined by the applicable section is permitted; omission in a compact form means the defaults stated for the full form. Implementations MUST NOT accept aliases, undocumented shorthands, singular-for-list substitutions, or host-language representations as equivalent standard syntax.
Published machine-readable schemas are structural validation aids. They do not replace the prose requirements, cannot establish resolution- or scope-dependent validity, and are defective wherever they disagree with this specification.
Duplicate and Unknown Keys
Section titled “Duplicate and Unknown Keys”Duplicate mapping keys MUST be rejected during parsing or structural validation before their values are interpreted. The same requirement applies at every nesting depth, including maps that represent data.
A standard-defined structural map is closed unless its defining section says otherwise. A key not declared for that map is invalid.
This includes unknown top-level keys, construct keys, modifiers, field-declaration keys, manifest keys, and action arguments not declared by the resolved manifest. The wf. operation namespace is reserved to this specification.
An unknown wf. operation MUST be rejected even if an implementation offers a similarly named extension. Implementations MUST NOT reinterpret or silently ignore an unknown standard operation or modifier.
Extension keys and their distinction from user-data keys are defined under Extensions and Forward Compatibility.