From 8a734e99db4607c13ff1c759ecb27927c607ba11 Mon Sep 17 00:00:00 2001
From: Anatoly Scherbakov <altaisoft@gmail.com>
Date: Sun, 19 Mar 2023 01:04:21 +0400
Subject: [PATCH 1/4] #90 Compare JSON vs YAML

---
 spec/index.html | 115 +++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 98 insertions(+), 17 deletions(-)

diff --git a/spec/index.html b/spec/index.html
index dc799d5..c7b2422 100644
--- a/spec/index.html
+++ b/spec/index.html
@@ -6,14 +6,14 @@
 <script src="https://www.w3.org/Tools/respec/respec-w3c" class="remove" defer></script>
 <script src="../common/common.js" class="remove" defer></script>
 <script class='remove'>
-  // Use fragment identifer of test as name.
+  // Use fragment identifier of test as name.
   function data_test_display() {
       const test_references = document.querySelectorAll('details.respec-tests-details a');
       for( const a of test_references ) {
           const href = a.href;
           const test_reference = href.split('#')[1];
           a.textContent = test_reference;
-      }    
+      }
   }
 
   var respecConfig = {
@@ -533,21 +533,102 @@ <h2>Basic Concepts</h2>
       interoperability considerations.
     </p>
 
-    <p>
-      This is because YAML is more flexible than [[JSON]]:
-    </p>
+    <section id="json-vs-yaml">
+      <h3>JSON vs YAML comparison</h3>
 
-    <ul>
-      <li>YAML supports different encodings, including UTF-8, UTF-16, and UTF-32.</li>
-      <li>YAML supports more native data types than JSON.</li>
-      <li>The structure of a <a>YAML document</a> &mdash; that is, a <a>YAML representation graph</a> &mdash;
-      is a rooted, directed graph that can have cycles.</li>
-      <li>YAML is serialized as a <a>YAML stream</a>, which is a sequence of <a>YAML documents</a>.
-          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.
-      </li>
-    </ul>
+      <p>YAML is more flexible than JSON, as illustrated by comparison table below.</p>
+
+      <table class="simple">
+        <thead>
+        <tr>
+          <th>Features</th>
+          <th>[[JSON]]</th>
+          <th>[[YAML]]</th>
+        </tr>
+        </thead>
+        <tbody>
+        <tr>
+          <th colspan="3">Allowed encodings</th>
+        </tr>
+
+        <tr>
+          <th>UTF-8</th>
+          <td><a data-cite="JSON#section-8.1">✔️</a></td>
+          <td><a data-cite="YAML#52-character-encodings">✔️</a></td>
+        </tr>
+
+        <tr>
+          <th>UTF-16</th>
+          <td><a data-cite="JSON#section-8.1">❌</a></td>
+          <td><a data-cite="YAML#52-character-encodings">✔️</a></td>
+        </tr>
+
+        <tr>
+          <th>UTF-32</th>
+          <td><a data-cite="JSON#section-8.1">❌</a></td>
+          <td><a data-cite="YAML#52-character-encodings">✔️</a></td>
+        </tr>
+
+        <tr>
+          <th colspan="3">Native data types</th>
+        </tr>
+
+        <tr>
+          <th><code>{}</code> object</th>
+          <td><a data-cite="JSON#section-4">✔️</a></td>
+          <td><a data-cite="YAML#3211-nodes">✔️</a></td>
+        </tr>
+
+        <tr>
+          <th><code>[]</code> array</th>
+          <td><a data-cite="JSON#section-5">✔️</a></td>
+          <td><a data-cite="YAML#3211-nodes">✔️</a></td>
+        </tr>
+
+        <tr>
+          <th>string</th>
+          <td><a data-cite="JSON#section-7">✔️</a></td>
+          <td><a data-cite="YAML#3211-nodes">✔️</a></td>
+        </tr>
+
+        <tr>
+          <th>number</th>
+          <td><a data-cite="JSON#section-6">✔️</a></td>
+          <td>✔️<a data-cite="YAML#10213-integer">integer</a> <a data-cite="YAML#10214-floating-point">floating
+            point</a></td>
+        </tr>
+
+        <tr>
+          <th>bool</th>
+          <td><a data-cite="JSON#section-3">✔️</a></td>
+          <td><a data-cite="YAML#10212-boolean">✔️</a></td>
+        </tr>
+
+        <tr>
+          <th>null</th>
+          <td><a data-cite="JSON#section-3">✔️</a></td>
+          <td><a data-cite="YAML#10211-null">✔️</a></td>
+        </tr>
+
+        <tr>
+          <th>custom types</th>
+          <td>❌</td>
+          <td>✔️ via <a data-cite="YAML#tags">tags</a></td>
+        </tr>
+
+        <tr>
+          <th>Cycles</th>
+          <td>❌</td>
+          <td><a data-cite="YAML#321-representation-graph">✔️</a></td>
+        </tr>
+        <tr>
+          <th>Documents per file</th>
+          <td>1</td>
+          <td>⩾ 1 via <a>YAML stream</a></td>
+        </tr>
+        </tbody>
+      </table>
+    </section>
 
     <p>
       The first goal of this specification is to allow a <a>JSON-LD document</a> to be
@@ -1192,7 +1273,7 @@ <h2>Best Practices</h2>
       <h2>Extended YAML-LD Profile</h2>
 
       <p>
-        To take better advantage of the broader expressivity of YAML,
+        To take better advantage of the <a href="#json-vs-yaml">broader expressivity of YAML</a>,
         this document also defines a means of extending the
         <a>JSON-LD internal representation</a> to allow a more complete expression
         of native data types within YAML-LD, and allows use of the complete

From d7ccc8e4fab4a150737bedac911967b263307fd2 Mon Sep 17 00:00:00 2001
From: Anatoly Scherbakov <altaisoft@gmail.com>
Date: Tue, 21 Mar 2023 00:09:09 +0400
Subject: [PATCH 2/4] Add more YAML specific features

---
 spec/index.html | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/spec/index.html b/spec/index.html
index c7b2422..f967cb8 100644
--- a/spec/index.html
+++ b/spec/index.html
@@ -626,6 +626,18 @@ <h3>JSON vs YAML comparison</h3>
           <td>1</td>
           <td>⩾ 1 via <a>YAML stream</a></td>
         </tr>
+
+        <tr>
+          <th>Comments</th>
+          <td>❌</td>
+          <td><a data-cite="YAML#3233-comments">✔️</a></td>
+        </tr>
+
+        <tr>
+          <th>Anchors & aliases</th>
+          <td>❌</td>
+          <td><a data-cite="YAML#3222-anchors-and-aliases">✔️</a></td>
+        </tr>
         </tbody>
       </table>
     </section>

From 75198ce2d447d9fc7e6f5d496469e87c5fc59bb6 Mon Sep 17 00:00:00 2001
From: Anatoly Scherbakov <altaisoft@gmail.com>
Date: Fri, 21 Apr 2023 21:20:56 +0400
Subject: [PATCH 3/4] =?UTF-8?q?#90=20Punctuation=20=C2=A9=20@TallTed?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Ted Thibodeau Jr <tthibodeau@openlinksw.com>
---
 spec/index.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/spec/index.html b/spec/index.html
index f967cb8..b175529 100644
--- a/spec/index.html
+++ b/spec/index.html
@@ -594,7 +594,7 @@ <h3>JSON vs YAML comparison</h3>
         <tr>
           <th>number</th>
           <td><a data-cite="JSON#section-6">✔️</a></td>
-          <td>✔️<a data-cite="YAML#10213-integer">integer</a> <a data-cite="YAML#10214-floating-point">floating
+          <td>✔️<a data-cite="YAML#10213-integer">integer</a> <br> <a data-cite="YAML#10214-floating-point">floating
             point</a></td>
         </tr>
 

From 487f97af318090da1dda2af30d32875e656808a1 Mon Sep 17 00:00:00 2001
From: Anatoly Scherbakov <altaisoft@gmail.com>
Date: Fri, 21 Apr 2023 21:22:17 +0400
Subject: [PATCH 4/4] =?UTF-8?q?#90=20Icon=20=C2=A9=20@TallTed?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Ted Thibodeau Jr <tthibodeau@openlinksw.com>
---
 spec/index.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/spec/index.html b/spec/index.html
index b175529..58390db 100644
--- a/spec/index.html
+++ b/spec/index.html
@@ -560,7 +560,7 @@ <h3>JSON vs YAML comparison</h3>
         <tr>
           <th>UTF-16</th>
           <td><a data-cite="JSON#section-8.1">❌</a></td>
-          <td><a data-cite="YAML#52-character-encodings">✔️</a></td>
+          <td><a data-cite="YAML#52-character-encodings">✅</a></td>
         </tr>
 
         <tr>