From 940d3959adf05b09c621179f4d11f101f7e17174 Mon Sep 17 00:00:00 2001
From: Roberto Polli <robipolli@gmail.com>
Date: Fri, 1 Jul 2022 00:41:05 +0200
Subject: [PATCH] Preliminary rules.

---
 spec/index.html | 147 +++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 145 insertions(+), 2 deletions(-)

diff --git a/spec/index.html b/spec/index.html
index 178c361..052decc 100644
--- a/spec/index.html
+++ b/spec/index.html
@@ -243,7 +243,7 @@ <h2>Introduction</h2>
       <p>
         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-yaml-mediatypes]]),
         this document identifies constraints on YAML documents
         such that they can be used to represent JSON-LD documents.
       </p>
@@ -283,9 +283,152 @@ <h2>Introduction</h2>
   <section id="basic-concepts" class="informative">
     <h2>Basic Concepts</h2>
 
-    <p>FIXME.</p>
+    <p>
+      To ease writing and collaborating on JSON-LD documents, it is a common practice
+      to serialize them as YAML.
+      This requires not only to register a media type 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 consideration.
+
+      This is because YAML is more flexible than JSON:
+
+      * it supports different encodings, including UTF-8, UTF-16 and UTF-32;
+      * it supports more data types than JSON;
+      * the structure of its documents, that is named YAML representation graph,
+        is a tree that can have cycles.
+    </p>
+
+    <p>
+      The first goal of this specification is to allow to process a JSON-LD document
+      and serialize it in YAML, and then back to JSON-LD without losing any information.
+
+      This is always possible, because a YAML representation graph can always represent
+      a non-cyclic tree, because JSON data types are a subset of YAML's, and because
+      JSON encoding is UTF-8.
+    </p>
+
+    <p>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 - since `@`
+    is a reserved character in YAML, entries containing it 
+    needs to be enclosed in double quotes.
+
+    ```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
+    ```
+
+
+    </p>
   </section>
+  <section id="specifications" class="normative">
+    <h2>Specifications</h2>
+
+    <p>
+      A YAML-LD document is a [[YAML]] document that can be interpreted as linked data.
+    </p>
+    <p>
+      It MUST be encoded in UTF-8, to improve interoperability with [[JSON]]. 
+    </p>
+    <p>
+      YAML-LD documents MAY contain comments,
+      that MAY be removed when interpreting the document
+      as JSON-LD.
+      See Interoperability considerations of [[I-D.ietf-yaml-mediatypes]] for more details.
+    </p>
+    <p>
+      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 not be persisted when interpreting the document as JSON-LD.
+
+    </p>
+    <p> 
+      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.
+    </p>
+    <p>
+      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"
+            }
+          }
+        ]
+      }
+
+      
+      ```
+    </p>
+  </section>
   <section id="sec" class="informative">
     <h2>Security Considerations</h2>