Introduction

YAML (YAML Ain't Markup Language) is a human-readable data serialization format commonly used for configuration files and data representation. It is known for its simplicity and readability, making it a preferred choice for settings and data structures. YAML's structure is based on indentation, allowing users to represent data hierarchies in an easily understandable manner.

Stencila provides support for YAML as a more human-readable, while still lossless, alternative to JSON for storing documents.

Usage

Use the .yaml file extension, or the --to yaml or --from yaml options, when converting to/from YAML e.g.

stencila convert doc.smd doc.yaml

Implementation

Stencila support lossless, bi-directional conversion between Stencila documents and YAML. The codec-yaml Rust crate implements from_yaml and to_yaml methods for all node types in Stencila Schema, powered by serde_yaml.

When the --standalone option is used (the default for encoding to files), two properties are added to the YAML encoding of root nodes to improve interoperability:

a $schema property which links to the JSON Schema for the node type
a @context property which links to the JSON-LD context for the Stencila Schema

For example,

$schema: https://stencila.org/Article.schema.json
"@context": https://stencila.org/context.jsonld
type: Article

Support

Stencila supports these operations for YAML:

decoding from a file
decoding from a string
encoding to a file
encoding to a string

Support and degree of loss by node type:

Node type	Encoding	Decoding
Works
Article	🟢 No loss	🟢 No loss
AudioObject	🟢 No loss	🟢 No loss
AuthorRole	🟢 No loss	🟢 No loss
Chat	🟢 No loss	🟢 No loss
ChatMessage	🟢 No loss	🟢 No loss
ChatMessageGroup	🟢 No loss	🟢 No loss
Claim	🟢 No loss	🟢 No loss
Collection	🟢 No loss	🟢 No loss
Comment	🟢 No loss	🟢 No loss
CreativeWork	🟢 No loss	🟢 No loss
Directory	🟢 No loss	🟢 No loss
Figure	🟢 No loss	🟢 No loss
File	🟢 No loss	🟢 No loss
ImageObject	🟢 No loss	🟢 No loss
MediaObject	🟢 No loss	🟢 No loss
Periodical	🟢 No loss	🟢 No loss
Prompt	🟢 No loss	🟢 No loss
PublicationIssue	🟢 No loss	🟢 No loss
PublicationVolume	🟢 No loss	🟢 No loss
Review	🟢 No loss	🟢 No loss
SoftwareApplication	🟢 No loss	🟢 No loss
SoftwareSourceCode	🟢 No loss	🟢 No loss
Table	🟢 No loss	🟢 No loss
TableCell	🟢 No loss	🟢 No loss
TableRow	🟢 No loss	🟢 No loss
VideoObject	🟢 No loss	🟢 No loss
Prose
Admonition	🟢 No loss	🟢 No loss
Annotation	🟢 No loss	🟢 No loss
Cite	🟢 No loss	🟢 No loss
CiteGroup	🟢 No loss	🟢 No loss
DefinedTerm	🟢 No loss	🟢 No loss
Emphasis	🟢 No loss	🟢 No loss
Heading	🟢 No loss	🟢 No loss
Link	🟢 No loss	🟢 No loss
List	🟢 No loss	🟢 No loss
ListItem	🟢 No loss	🟢 No loss
Note	🟢 No loss	🟢 No loss
Paragraph	🟢 No loss	🟢 No loss
QuoteBlock	🟢 No loss	🟢 No loss
QuoteInline	🟢 No loss	🟢 No loss
Section	🟢 No loss	🟢 No loss
Strikeout	🟢 No loss	🟢 No loss
Strong	🟢 No loss	🟢 No loss
Subscript	🟢 No loss	🟢 No loss
Superscript	🟢 No loss	🟢 No loss
Text	🟢 No loss	🟢 No loss
ThematicBreak	🟢 No loss	🟢 No loss
Underline	🟢 No loss	🟢 No loss
Math
MathBlock	🟢 No loss	🟢 No loss
MathInline	🟢 No loss	🟢 No loss
Code
CodeBlock	🟢 No loss	🟢 No loss
CodeChunk	🟢 No loss	🟢 No loss
CodeExpression	🟢 No loss	🟢 No loss
CodeInline	🟢 No loss	🟢 No loss
CompilationMessage	🟢 No loss	🟢 No loss
ExecutionMessage	🟢 No loss	🟢 No loss
Data
Array	🟢 No loss	🟢 No loss
ArrayHint	🟢 No loss	🟢 No loss
ArrayValidator	🟢 No loss	🟢 No loss
Boolean	🟢 No loss	🟢 No loss
BooleanValidator	🟢 No loss	🟢 No loss
ConstantValidator	🟢 No loss	🟢 No loss
Cord	🟢 No loss	🟢 No loss
Datatable	🟢 No loss	🟢 No loss
DatatableColumn	🟢 No loss	🟢 No loss
DatatableColumnHint	🟢 No loss	🟢 No loss
DatatableHint	🟢 No loss	🟢 No loss
Date	🟢 No loss	🟢 No loss
DateTime	🟢 No loss	🟢 No loss
DateTimeValidator	🟢 No loss	🟢 No loss
DateValidator	🟢 No loss	🟢 No loss
Duration	🟢 No loss	🟢 No loss
DurationValidator	🟢 No loss	🟢 No loss
EnumValidator	🟢 No loss	🟢 No loss
Integer	🟢 No loss	🟢 No loss
IntegerValidator	🟢 No loss	🟢 No loss
Null	🟢 No loss	🟢 No loss
Number	🟢 No loss	🟢 No loss
NumberValidator	🟢 No loss	🟢 No loss
Object	🟢 No loss	🟢 No loss
ObjectHint	🟢 No loss	🟢 No loss
String	🟢 No loss	🟢 No loss
StringHint	🟢 No loss	🟢 No loss
StringValidator	🟢 No loss	🟢 No loss
Time	🟢 No loss	🟢 No loss
TimeValidator	🟢 No loss	🟢 No loss
Timestamp	🟢 No loss	🟢 No loss
TimestampValidator	🟢 No loss	🟢 No loss
TupleValidator	🟢 No loss	🟢 No loss
Unknown	🟢 No loss	🟢 No loss
UnsignedInteger	🟢 No loss	🟢 No loss
Flow
Button	🟢 No loss	🟢 No loss
CallArgument	🟢 No loss	🟢 No loss
CallBlock	🟢 No loss	🟢 No loss
CodeLocation	🟢 No loss	🟢 No loss
CompilationDigest	🟢 No loss	🟢 No loss
ExecutionDependant	🟢 No loss	🟢 No loss
ExecutionDependency	🟢 No loss	🟢 No loss
ExecutionTag	🟢 No loss	🟢 No loss
ForBlock	🟢 No loss	🟢 No loss
Form	🟢 No loss	🟢 No loss
Function	🟢 No loss	🟢 No loss
IfBlock	🟢 No loss	🟢 No loss
IfBlockClause	🟢 No loss	🟢 No loss
IncludeBlock	🟢 No loss	🟢 No loss
Parameter	🟢 No loss	🟢 No loss
Variable	🟢 No loss	🟢 No loss
Walkthrough	🟢 No loss	🟢 No loss
WalkthroughStep	🟢 No loss	🟢 No loss
Style
StyledBlock	🟢 No loss	🟢 No loss
StyledInline	🟢 No loss	🟢 No loss
Edits
InstructionBlock	🟢 No loss	🟢 No loss
InstructionInline	🟢 No loss	🟢 No loss
InstructionMessage	🟢 No loss	🟢 No loss
PromptBlock	🟢 No loss	🟢 No loss
SuggestionBlock	🟢 No loss	🟢 No loss
SuggestionInline	🟢 No loss	🟢 No loss
Config
Config	🟢 No loss	🟢 No loss
Other
Brand	🟢 No loss	🟢 No loss
ContactPoint	🟢 No loss	🟢 No loss
Enumeration	🟢 No loss	🟢 No loss
Grant	🟢 No loss	🟢 No loss
ModelParameters	🟢 No loss	🟢 No loss
MonetaryGrant	🟢 No loss	🟢 No loss
Organization	🟢 No loss	🟢 No loss
Person	🟢 No loss	🟢 No loss
PostalAddress	🟢 No loss	🟢 No loss
Product	🟢 No loss	🟢 No loss
PropertyValue	🟢 No loss	🟢 No loss
ProvenanceCount	🟢 No loss	🟢 No loss
RawBlock	🟢 No loss	🟢 No loss
Thing	🟢 No loss	🟢 No loss

See the Rust crate codec-yaml for more details.