YAML-LD 1.0

Objective
This document defines YAML-LD, a set of conventions built on top of YAML, which outlines how to serialize Linked Data as YAML based on JSON-LD syntax, semantics, and APIs. The emergence of YAML as a more concise format for representing information previously serialized as JSON, including Linked Data, has led to the development of YAML-LD.

Methods
This document defines constraints on YAML so that any YAML-LD document can be represented in JSON-LD. This is necessary because YAML is more expressive than JSON, in terms of both available data types and document structure. This document also registers the application/ld+yaml media type.

Results
This document provides a clear description of how to serialize Linked Data in YAML. It also describes the basic concepts and core requirements for implementing YAML-LD, including a comparison of JSON versus YAML, the supported YAML features, and encoding considerations.

Limitations
The YAML feature set is richer than that of JSON, and a number of YAML features are not supported in this specification. However, ground is laid for future development of a version of YAML-LD which will support those features — via the Extended YAML-LD Profile.

Conclusions
YAML-LD offers an efficient way to encode Linked Data in a variety of programming languages which can use YAML.

An introductory YAML-LD example is presented below.

"@context":
  - https://json-ld.org/contexts/dollar-convenience.jsonld
  - "@base": https://w3c.github.io/yaml-ld/
    rdfs: http://www.w3.org/2000/01/rdf-schema#
    schema: https://schema.org/
    license:
      "@type": "@id"

$id: https://w3c.github.io/yaml-ld/
rdfs:label: YAML-LD
license: https://spdx.org/licenses/W3C.html
schema:hasPart:
  - rdfs:label: Abstract
  - rdfs:label: Status of This Document
  - rdfs:label: Introduction

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY, MUST, MUST NOT, RECOMMENDED, and SHOULD in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

A YAML-LD document complies with the YAML-LD Basic profile of this specification if it follows the normative statements from this specification and can be transformed into a [JSON-LD11] representation, then back to a conforming YAML-LD document, without loss of semantic information.

For convenience, normative statements for documents are often phrased as statements on the properties of the document.

The YamlLdErrorCode represents the collection of valid YAML-LD error codes, which extends the JsonLdErrorCode definitions.

WebIDLenum YamlLdErrorCode {
  "invalid-encoding",
  "mapping-key-error",
  "profile-error"
};

invalid-encoding

The character encoding of an input is invalid.

mapping-key-error

A YAML mapping key was found that was not a string.

profile-error

The parsed YAML document contains features incompatible with the specified profile.

YAML-LD content can be easily embedded in HTML [HTML] by placing it in a <script> element with the type attribute set to application/ld+yaml, as illustrated in an example below.

<script type="application/ld+yaml">
  "@context": https://json-ld.org/contexts/person.jsonld
  "@id": https://dbpedia.org/resource/John_Lennon
  name: John Lennon
  born: 1940-10-09
  spouse:
    - https://dbpedia.org/resource/Yoko_Ono
    - https://dbpedia.org/resource/Cynthia_Lennon
</script>

YAML syntax is indentation based. Therefore, when processing each <script> block with YAML-LD content, YAML-LD processor MUST preserve the content of the block for YAML parsing as-is, including whitespace characters.

If the YAML-LD <script> tag contains a YAML Stream with multiple YAML documents, each of these documents MUST be treated as if it was included in a separate <script> tag. See Streams for details.

Every YAML-LD file is a YAML-LD stream and might contain multiple YAML-LD documents, as shown in the example below.

"@base": https://schema.org
"@id": https://w3c.github.io/yaml-ld/
"@type": WebContent
name: YAML-LD
---
"@base": https://schema.org
"@id": https://www.w3.org/TR/json-ld11/
"@type": WebContent
name: JSON-LD

[JSON-LD11-API] defines the extractAllScripts flag, which allows to parse multiple <script> tags with YAML-LD content.

A conformant YAML-LD specification MUST take this flag into account while parsing a normal YAML-LD document.

• If the flag is true, the YAML stream is considered an array, and each document in it is an item in that array, even if there is only one document in the stream;
• If the flag is false, only the first document in the stream will be processed.