From 1d2ffe574a105e4ae3f74555190eacb0148142de Mon Sep 17 00:00:00 2001 From: Roberto Polli Date: Fri, 1 Jul 2022 00:41:05 +0200 Subject: [PATCH 1/8] Preliminary rules. * Basic concepts and Core requirements * MUST UTF-8 * comments are white spaces * anchored nodes are considered static * FAQ Co-authored-by: Gregg Kellogg Co-authored-by: Ted Thibodeau Jr --- spec/index.html | 242 +++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 240 insertions(+), 2 deletions(-) diff --git a/spec/index.html b/spec/index.html index 178c361..8cc4dd4 100644 --- a/spec/index.html +++ b/spec/index.html @@ -243,7 +243,7 @@

Introduction

Since YAML is more expressive than JSON, both in the available data types and in the document structure - (see I-D.ietf-yaml-mediatypes), + (see [[I-D.ietf-httpapi-yaml-mediatypes]]), this document identifies constraints on YAML documents such that they can be used to represent JSON-LD documents.

@@ -283,9 +283,156 @@

Introduction

Basic Concepts

-

FIXME.

+

+ To ease writing and collaborating on JSON-LD documents, it is a 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 even to define the expected behavior of + applications that processes 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 data types than JSON.
    • +
  • the structure of a YAML document — that is, a named YAML representation graph — + is a rooted, directed graph that can have cycles.
    • + +

    + 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 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. +

    + +

+
+

Core Requirements

+

+ A YAML-LD document is a [[YAML]] document that can be interpreted as Linked Data [[LINKED-DATA]]. +

+

+ It MUST be encoded in UTF-8, to ensure interoperability with [[JSON]]. +

+

+ Comments in YAML-LD documents + are treated as white space + This behavior is consistent with other + Linked Data serializations like [[TURTLE]]. + See Interoperability considerations of [[I-D.ietf-httpapi-yaml-mediatypes]] + for more details. +

+

+ Since named anchors are a serialization detail, + such names + MUST NOT be used to convey relevant information, + MAY be altered when processing the document, + and MAY be dropped when interpreting the document as JSON-LD. +

+

+ A YAML-LD document MAY contain named anchors and alias nodes, + but its representation graph MUST NOT contain cycles. + When interpreting the document as JSON-LD, + alias nodes MUST be resolved by value to their target nodes. +

+

+ Example: The following YAML-LD document + contains alias nodes for the `{"@id": "country:ITA"}` object: + + ```yaml + %YAML 1.2 + --- + "@context": + "@vocab": "http://schema.org/" + "countries": "http://publication.europa.eu/resource/authority/country/" + "@graph": + - &ITA + "@id": countries:ITA + - "@id": http://people.example/Homer + name: Homer Simpson + nationality: *ITA + - "@id": http://people.example/Lisa + name: Lisa Simpson + nationality: *ITA + ``` + + While the representation graph (and eventually the in-memory representation + of the data structure, e.g., a Python dictionary or a Java hashmap) will still + contain references between nodes, the JSON-LD serialization will not. + + ```json + { + "@context": { + "@vocab": "http://schema.org/", + "countries": "http://publication.europa.eu/resource/authority/country/" + }, + "@graph": [ + { + "@id": "countries:ITA" + }, + { + "@id": "http://people.example/Homer", + "full_name": "Homer Simpson", + "country": { + "@id": "countries:ITA" + } + }, + { + "@id": "http://people.example/Lisa", + "full_name": "Lisa Simpson", + "country": { + "@id": "countries:ITA" + } + } + ] + } + ``` +

+

Security Considerations

@@ -423,5 +570,96 @@

Examples

+
+

REMOVE THIS SECTION BEFORE PUBLICATION.

+ +

FAQ

+ + #### Why does YAML-LD not preserve comments? +

+ [[JSON]] (and hence [[JSON-LD]]) does not support comments, + and other Linked Data serialization formats + that support comments (such as [[TURTLE]]) + do not provide a means to preserve them + when processing and serializing the document + in other formats. + The proposed behavior is thus consistent with + other implementations. + + While YAML-LD could define a specific predicate for comments, + that is insufficient because, for example, + the order of keywords is not preserved in JSON, so the + comments could be displaced. + This specification does not provide a means for preserving + YAML comments after a JSON serialization. + + ```yaml + # First comment + "@context": "http://schema.org" + + # Second comment + givenName: John + ``` + + transforming the above entry into a JSON-LD document + results in: + + ```json + { + "@context": "http://schema.org", + "givenName": "John" + } + ``` + + + #### Why does YAML-LD not extend the JSON-LD data model ? +

+ [[JSON]] only represents simple trees while [[YAML]] can support + rooted, directed graphs with references and cycles. + + The above structures cannot be preserved when serializing + to JSON-LD and - with respect to cycles - the serialization + will fail. + + Programming languages such as Java and Python already support + YAML representation graphs, but these implementations may behave + differently. + In the following example, `&value` references the value + of the keyword `value`. + + ```yaml + value: &value 100 + valve1: + temperature: &temp100C + value: *value + unit: degC + valve2: + temperature: *temp100C + ``` + + Processing this entry in Python, I get the following + structure that preserve the references to + mutable objects (e.g., the `temperature` dict) + but not to scalars (e.g., the `value` keyword). + + ```python + temperature = { "value": 100, "unit": "degC" } + document = { + "value": 100, + "valve1": { "temperature": temperature }, + "valve2": { "temperature": temperature } + } + ``` + + Since all these implementations pre-date this + specification, some more interoperable choices include the following: + + * to forbid cycles in YAML-LD documents + * to consider all references in YAML-LD as static, + i.e., a shorthand way to repeat specific patterns + +

+
+ From 3b4dae0a45cb53c990c9946805c868cacc00fcd8 Mon Sep 17 00:00:00 2001 From: Gregg Kellogg Date: Tue, 5 Jul 2022 09:50:22 -0700 Subject: [PATCH 2/8] Update spec/index.html Co-authored-by: Ted Thibodeau Jr --- spec/index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/index.html b/spec/index.html index 8cc4dd4..80426d9 100644 --- a/spec/index.html +++ b/spec/index.html @@ -601,7 +601,7 @@

FAQ

givenName: John ``` - transforming the above entry into a JSON-LD document + Transforming the above entry into a JSON-LD document results in: ```json From 068269aedf53195f92182906a9c42e8c5cea0ff8 Mon Sep 17 00:00:00 2001 From: Gregg Kellogg Date: Tue, 5 Jul 2022 09:51:15 -0700 Subject: [PATCH 3/8] Update spec/index.html Co-authored-by: Ted Thibodeau Jr --- spec/index.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/index.html b/spec/index.html index 80426d9..4d74625 100644 --- a/spec/index.html +++ b/spec/index.html @@ -287,8 +287,8 @@

Basic Concepts

To ease writing and collaborating on JSON-LD documents, it is a 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 even to define the expected behavior of - applications that processes these documents, including fragment identifiers and + 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.

From 20a0eb8bca7eaae09889c07cd5ba86e74c2581e9 Mon Sep 17 00:00:00 2001 From: Gregg Kellogg Date: Tue, 5 Jul 2022 09:51:41 -0700 Subject: [PATCH 4/8] Update spec/index.html Co-authored-by: Ted Thibodeau Jr --- spec/index.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/index.html b/spec/index.html index 4d74625..54db7bf 100644 --- a/spec/index.html +++ b/spec/index.html @@ -654,8 +654,8 @@

FAQ

Since all these implementations pre-date this specification, some more interoperable choices include the following: - * to forbid cycles in YAML-LD documents - * to consider all references in YAML-LD as static, + * forbidding cycles in YAML-LD documents + * considering all references in YAML-LD as static, i.e., a shorthand way to repeat specific patterns

From c1adb33c065d37963da4a4abe49b5df934126797 Mon Sep 17 00:00:00 2001 From: Roberto Polli Date: Tue, 5 Jul 2022 17:43:47 +0200 Subject: [PATCH 5/8] Fix: #46. YAML files are actually streams. --- spec/index.html | 28 +++++++++++++++++++--------- 1 file changed, 19 insertions(+), 9 deletions(-) diff --git a/spec/index.html b/spec/index.html index 54db7bf..427747c 100644 --- a/spec/index.html +++ b/spec/index.html @@ -221,7 +221,7 @@ to represent information serialized as JSON, including Linked Data. This document defines how to serialize linked data - in YAML documents. + in YAML. Moreover, it registers the application/ld+yaml media type.

@@ -244,15 +244,12 @@

Introduction

Since YAML is more expressive than JSON, both in the available data types and in the document structure (see [[I-D.ietf-httpapi-yaml-mediatypes]]), - this document identifies constraints on YAML documents - such that they can be used to represent JSON-LD documents. + this document identifies constraints on YAML + such that it can be used to represent JSON-LD documents.

-

A YAML-LD document complies with this specification if ...

-

Define YAML-LD document somewhere.

-

This specification makes use of the following namespace prefixes:

@@ -301,6 +298,11 @@

Basic Concepts

  • YAML supports more data types than JSON.
  • the structure of a YAML document — that is, a named YAML representation graph — is a rooted, directed graph that can have cycles.
    • +
  • YAML has the concept of stream, which is a sequence of documents. + While a stream usually 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 @@ -353,14 +355,22 @@

    Basic Concepts

    Core Requirements

    - A YAML-LD document is a [[YAML]] document that can be interpreted as Linked Data [[LINKED-DATA]]. + A YAML-LD stream is a YAML stream of YAML-LD documents. + Note that each document in a stream is independent + from the others: + each one has its own context, YAML directives, + named anchors and so on. +

    +

    + A YAML-LD document is a [[YAML]] document + that can be interpreted as Linked Data [[LINKED-DATA]].

    It MUST be encoded in UTF-8, to ensure interoperability with [[JSON]].

    Comments in YAML-LD documents - are treated as white space + are treated as white space. This behavior is consistent with other Linked Data serializations like [[TURTLE]]. See Interoperability considerations of [[I-D.ietf-httpapi-yaml-mediatypes]] @@ -381,7 +391,7 @@

    Core Requirements

    Example: The following YAML-LD document - contains alias nodes for the `{"@id": "country:ITA"}` object: + contains alias nodes for the `{"@id": "countries:ITA"}` object: ```yaml %YAML 1.2 From 6adfd73a15c4e62bd4d21aec1a4bf1ea8020dd91 Mon Sep 17 00:00:00 2001 From: Roberto Polli Date: Tue, 5 Jul 2022 21:11:31 +0200 Subject: [PATCH 6/8] Update spec/index.html Co-authored-by: Gregg Kellogg --- spec/index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/index.html b/spec/index.html index 427747c..b685ff3 100644 --- a/spec/index.html +++ b/spec/index.html @@ -587,7 +587,7 @@

    FAQ

    #### Why does YAML-LD not preserve comments?

    - [[JSON]] (and hence [[JSON-LD]]) does not support comments, + [[JSON]] (and hence [[JSON-LD11]]) does not support comments, and other Linked Data serialization formats that support comments (such as [[TURTLE]]) do not provide a means to preserve them From b27637bd6f5ac67ff5e3366520eac8f5df97976c Mon Sep 17 00:00:00 2001 From: Roberto Polli Date: Tue, 5 Jul 2022 21:11:53 +0200 Subject: [PATCH 7/8] Update spec/index.html Co-authored-by: Gregg Kellogg --- spec/index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/index.html b/spec/index.html index b685ff3..04995c3 100644 --- a/spec/index.html +++ b/spec/index.html @@ -295,7 +295,7 @@

    Basic Concepts

    • YAML supports different encodings, including UTF-8, UTF-16, and UTF-32.
      • -
    • YAML supports more data types than JSON.
      • +
    • YAML supports more native data types than JSON.
    • the structure of a YAML document — that is, a named YAML representation graph — is a rooted, directed graph that can have cycles.
    • YAML has the concept of stream, which is a sequence of documents. From b73e25069c50370e134cd32087a40dc49910cad7 Mon Sep 17 00:00:00 2001 From: Roberto Polli Date: Wed, 6 Jul 2022 18:16:33 +0200 Subject: [PATCH 8/8] Update spec/index.html Co-authored-by: Ted Thibodeau Jr --- spec/index.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/index.html b/spec/index.html index 04995c3..f92f06c 100644 --- a/spec/index.html +++ b/spec/index.html @@ -357,9 +357,9 @@

      Core Requirements

      A YAML-LD stream is a YAML stream of YAML-LD documents. Note that each document in a stream is independent - from the others: + from the others; each one has its own context, YAML directives, - named anchors and so on. + named anchors, and so on.

      A YAML-LD document is a [[YAML]] document