YAML-LD

This section is non-normative.

To ease writing and collaborating on [ JSON-LD11 ] documents, it is becoming common practice to serialize them as [ YAML ]. This requires a registered media type, not only to enable content negotiation of linked data documents in YAML, but also to define the expected behavior of applications that process these documents, including fragment identifiers and interoperability considerations.

This is because YAML is more flexible than [ JSON ]:

• YAML supports different encodings, including UTF-8, UTF-16, and UTF-32.
• YAML supports more native data types than JSON.
• The structure of a YAML document — that is, a YAML representation graph — is a rooted, directed graph that can have cycles.
• YAML is serialized as a YAML stream , which is a sequence of YAML documents . While a stream often contains one document, streams with multiple documents are used to aggregate multiple, related, documents into a single file or network stream.

The first goal of this specification is to allow a JSON-LD document to be processed and serialized into YAML, and then back into JSON-LD, without losing any semantic information.

This is always possible, because a YAML representation graph can always represent a tree, because JSON data types are a subset of YAML's, and because JSON encoding is UTF-8.

The subset of YAML-LD which supports serialisation of JSON-LD documents is defined as the YAML-LD JSON profile of YAML-LD.

Example: The JSON-LD document below

{
  "@context": "https://json-ld.org/contexts/person.jsonld",
  "name": "Joe Hacker",
  "homepage": "https://example.org/joe.hacker/",
  "image": "https://example.org/joe.hacker/image.png"
}

Can be serialized as YAML as follows. Note that entries starting with @ need to be enclosed in quotes (as shown in this example), because @ is a reserved character in YAML.

%YAML 1.2
---
'@context': https://json-ld.org/contexts/person.jsonld
name:     Joe Hacker
homepage: https://example.org/joe.hacker/
image:
https://example.org/joe.hacker/image.png

This document is based on YAML 1.2.2, but YAML-LD is not tied to a specific version of YAML. Implementers concerned about features related to a specific YAML version can specify it in documents using the %YAML directive (see 10. 6. Interoperability Considerations ).

This section is non-normative.

See Security considerations in JSON-LD 1.1 . Also, see the YAML media type registration.

This section is non-normative.

For general interoperability considerations on the serialization of JSON documents in [ YAML ], see YAML and the Interoperability consideration of application/yaml [ I-D.ietf-httpapi-yaml-mediatypes ].

The YAML-LD format and the media type registration are not restricted to a specific version of YAML, but implementers that want to use YAML-LD with YAML versions other than 1.2.2 need to be aware that the considerations and analysis provided here, including interoperability and security considerations, are based on the YAML 1.2.2 specification.

This section is non-normative.

# First comment
"@context": "http://schema.org"
# Second comment
givenName:
John

{  "@context": "http://schema.org",  "givenName": "John"
}

value: &value 100
valve1:
  temperature: &temp100C
    value: *value
    unit: degC
valve2:
temperature:
*temp100C

temperature = { "value": 100, "unit": "degC" }
document = {
  "value": 100,
  "valve1": { "temperature": temperature },
  "valve2": { "temperature": temperature }
}

This section is non-normative.

Here, we propose to YAML-LD users a bit of advice which, although optional, might suggest one or two useful thoughts.

YAML-LD is intended to simplify the authoring of Linked Data for a wide range of domain experts; its target audience is not comprised solely of IT professionals. [ YAML ] is chosen as a medium to minimize syntactic noise, and to keep the authored documents concise and clear. [ JSON-LD11 ] (and hence YAML-LD) Context comprises a special language of its own. A requirement to author such a context would make the domain expert's job much harder, which we, as system architects and developers, should try to avoid.

For instance, according to [ JSON-LD11-API ], the expand() method of a JSON-LD processor accepts an expandContext argument which can be used to provide a default system context.

The @ character is reserved in YAML, and thus requires quoting (or escaping), as in the following example:

"@context":
  - https://prefix.cc/context
  - ex: https://example.org/
    name:
      "@id": rdfs:label
      "@container": "@language"
"@id": ex:Ray
"@type": ex:Cat
name:
  en: Ray
  ua: Промiнчик
ru:
Лучик

The need to quote these keywords has to be learnt, and introduces one more little irregularity to the document author's life. Further, on most keyboard layouts, typing quotes will require Shift , which reduces typing speed, albeit slightly.

In order to avoid this, the context might introduce custom mappings for the necessary keywords. For instance, [ schema-org ] context redefines @id as just id — which seems to be much more convenient to type, and no more difficult to remember.

The convenience context contains an alias to every JSON-LD keyword which the JSON-LD 1.1 specification permits aliasing — which means all the keywords except @context . The reserved @ character is replaced by $ , which is not reserved and therefore does not require quoting. Consider Example 10 reformatted using the convenience context :

"@context":
  - https://prefix.cc/context
  - https://yaml-ld.dev/context
  - ex: https://example.org/
    name:
      $id: rdfs:label
      $container: $language
$id: ex:Ray
$type: ex:Cat
name:
  en: Ray
  ua: Промiнчик
ru:
Лучик

The applicability of this context depends on the domain and is left to the architect's best judgement.

This section is non-normative.

To take better advantage of the broader expressivity of YAML, this document also defines a means of extending the JSON-LD internal representation to allow a more complete expression of native data types within YAML-LD, and allows use of the complete JSON-LD 1.1 Processing Algorithms and API [ JSON-LD11-API ] Application Programming Interface to manipulate extended YAML-LD documents.

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

As [ YAML ] has well-defined representation requirements, all YAML-LD streams MUST form a well-formed stream and use alias node defined by a previous node with a corresponding anchor ; otherwise, a loading-document-failed error has been detected and processing is aborted.

The YAML-LD extended profile allows full use of anchor names and alias nodes subject to the requirements described above in this section.

If the extendedYAML API flag is true , the processing result will be in the extended internal representation .

When processing using the YAML-LD JSON profile , documents MUST NOT contain alias nodes ; otherwise, a profile-error error has been detected and processing is aborted.

%YAML 1.2
%TAG !xsd! http://www.w3.org/2001/XMLSchema%23
---
"@context":
  "@vocab": http://xmlns.com/foaf/0.1/
name: !xsd!string Gregg Kellogg
homepage: https://greggkellogg.net/
depiction: http://www.gravatar.com/avatar/42f948...
date:
!xsd!date
"2022-08-08"

!yaml-ld
$context: http://schema.org/
$type: Person

name
:
Pierre-Antoine
Champin

WebIDLpartial dictionary JsonLdOptions {
  boolean extendedYAML = false;
};

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