Add OpenAPI/YAML Representation (#200)

* add openapi/yaml representation * add new file * Update example/yaml-json-schema.yaml Co-authored-by: Orie Steele <[email protected]> * pr comment * update authors of v2dm * update refs * update to yaml schema * Update index.html Co-authored-by: Andres Uribe <[email protected]> * Update index.html Co-authored-by: Ted Thibodeau Jr <[email protected]> --------- Co-authored-by: Orie Steele <[email protected]> Co-authored-by: Andres Uribe <[email protected]> Co-authored-by: Ted Thibodeau Jr <[email protected]>
w3c · Aug 17, 2023 · f8f798d · f8f798d
1 parent 2eda973
commit f8f798d
Show file tree

Hide file tree

Showing 3 changed files with 63 additions and 9 deletions.
diff --git a/common.js b/common.js
@@ -28,9 +28,11 @@ var vcwg = {
       title: "Verifiable Credentials Data Model v2.0",
       href: "https://www.w3.org/TR/vc-data-model-2.0/",
       authors: [
-        "Manu Sporny", "Dave Longley", "Grant Noble", "Dan Burnett",
-        "Ted Thibodeau", "Brent Zundel", "David Chadwick",
-        "Kyle Den Hartog"
+        "Manu Sporny", 
+        "Orie Steele",
+        "Michael B. Jones",
+        "Gabe Cohen",
+        "Oliver Terbu"
       ],
       status: "Working Draft",
       publisher: "W3C Verifiable Credentials Working Group"
@@ -65,9 +67,9 @@ var vcwg = {
       title: "JSON-LD 1.1: A JSON-based Serialization for Linked Data",
       publisher: "W3C"
     },
-    "VC-JWT": {
-      href: "https://www.w3.org/TR/vc-jwt/",
-      title: "Securing Verifiable Credentials using JSON Web Tokens",
+    "VC-JOSE-COSE": {
+      href: "https://www.w3.org/TR/vc-jose-cose/",
+      title: "Securing Verifiable Credentials using JOSE and COSE",
       authors: ["Orie Steele", "Michael Jones", "Michael Prorock"],
       publisher: "W3C"
     },
@@ -96,7 +98,7 @@ var vcwg = {
       publisher:  "IETF"
     },
     "OAS": {
-      title: "OpenAPI Specification",
+      title: "OpenAPI Specification Version 3.1.0",
       href: "https://swagger.io/specification/",
       authors: [
         "Darrel Miller",
@@ -107,6 +109,11 @@ var vcwg = {
         "Uri Sarid",
       ],
       publisher: "OpenAPI Initiative",
+    },
+    "YAML": {
+      href: "https://yaml.org/spec/1.2.2/",
+      title: "YAML Ain’t Markup Language (YAML™) version 1.2",
+      publisher:"YAML Language Development Team"
     }
   }
 };

diff --git a/example/yaml-json-schema.yaml b/example/yaml-json-schema.yaml
@@ -0,0 +1,35 @@
+---
+"$id": https://example.com/schemas/email.json
+"$schema": https://json-schema.org/draft/2020-12/schema
+name: Email Credential Schema
+description: Email Credential JSON Schema using YAML
+type: object
+properties:
+  credentialSubject:
+    type: object
+    properties:
+      emailAddress:
+        type: string
+        format: email
+    required:
+    - emailAddress
+example: |-
+  {
+    "$id": "https://example.com/schemas/email.json",
+    "$schema": "https://json-schema.org/draft/2019-09/schema",
+    "name": "EmailCredential",
+    "description": "Email Credential JSON Schema",
+    "type": "object",
+    "properties": {
+      "credentialSubject": {
+        "type": "object",
+        "properties": {
+          "emailAddress": {
+            "type": "string",
+            "format": "email"
+          }
+        },
+        "required": ["emailAddress"]
+      }
+    }
+  }
diff --git a/index.html b/index.html
@@ -494,8 +494,20 @@ <h4>description</h4>
           </section>
           <section class="normative">
             <h3>Representations of JSON Schema</h3>
-            <p class="issue" data-number="142">
-               Write section on using different representations of JSON Schema, such as YAML.
+            <p>
+               The standard representation of [[JSON-SCHEMA]] uses the [[RFC8259]] JSON data interchange
+               syntax</a> with <code>.json</code> as the file extension.
+            </p>
+            <p>
+               Implementers MAY use OpenAPI Specification's [[OAS]] [[YAML]] representation
+               of a [[JSON-SCHEMA]] with <code>.yaml</code> as the file extension. 
+
+               <p class="note">
+                  YAML representations of JSON Schemas can only be used with credential schemas whose type is <a href="#jsonschema">JsonSchema</a>.
+               </p>
+
+               An example [[JSON-SCHEMA]] using [[YAML]] is provided below.
+               <pre class="example" data-include="./example/yaml-json-schema.yaml" data-include-format="yaml"></pre>
             </p>
           </section>
       </section>