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.