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": "http://example.org/context.jsonld",
  "@graph": [
    {"@id": "http://example.org/1", "title": "Example 1"},
    {"@id": "http://example.org/2", "title": "Example 2"},
    {"@id": "http://example.org/3", "title": "Example 3"}
  ]
}

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': http://example.org/context.jsonld
'@graph':
  - '@id': http://example.org/1
    title: Example 1
  - '@id': http://example.org/2
    title: Example 2
  - '@id': http://example.org/3
    title: Example 3

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 7. Interoperability Considerations).

{
  "@context": {
    "$always": "@always",
    "$base": "@base",
    "$container": "@container",
    "$direction": "@direction",
    "$embed": "@embed",
    "$explicit": "@explicit",
    "$graph": "@graph",
    "$id": "@id",
    "$import": "@import",
    "$included": "@included",
    "$index": "@index",
    "$json": "@json",
    "$language": "@language",
    "$list": "@list",
    "$nest": "@nest",
    "$never": "@never",
    "$none": "@none",
    "$null": "@null",
    "$omitDefault": "@omitDefault",
    "$once": "@once",
    "$prefix": "@prefix",
    "$propagate": "@propagate",
    "$protected": "@protected",
    "$requireAll": "@requireAll",
    "$reverse": "@reverse",
    "$set": "@set",
    "$type": "@type",
    "$value": "@value",
    "$version": "@version",
    "$vocab": "@vocab"
  }
}

%YAML 1.2
---
'@context':
- http://example.org/context.jsonld
- https://www.w3.org/ns/yaml-ld/v1
$graph:
  - $id: http://example.org/1
    title: Example 1
  - $id: http://example.org/2
    title: Example 2
  - $id: http://example.org/3
    title: Example 3

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.

Consider Example 12 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.

See 3.1 Convenience Context for more information.