From 48097532d26031f44636e7d9feb9e58d79897b62 Mon Sep 17 00:00:00 2001 From: Gabe Choen Date: Fri, 17 Sep 2021 10:53:48 -0700 Subject: [PATCH 1/7] draft 2 --- spec/index.bs | 82 ++-- spec/index.html | 1039 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 1078 insertions(+), 43 deletions(-) create mode 100644 spec/index.html diff --git a/spec/index.bs b/spec/index.bs index 1625097..00714e2 100644 --- a/spec/index.bs +++ b/spec/index.bs @@ -11,13 +11,9 @@ ED: https://w3c-ccg.github.io/vc-json-schemas/ Shortname: vcjsonschemaspec Level: 1 -Editor: Gabe Cohen, [Workday](https://credentials.workday.com), gabe.cohen@workday.com +Editor: Gabe Cohen, w3cid gabe.cohen@hey.com Editor: Orie Steele, w3cid 109171, [Transmute](https://www.transmute.industries/), orie@transmute.industries -!Contributors: Bjorn Hamel (Workday) -!Contributors: Rory Martin (Workday) -!Contributors: Joe Genereux (Workday) -!Contributors: Jonathan Reynolds (Workday) group: ccg Issue Tracking: GitHub https://github.com/w3c-ccg/vc-json-schemas/issues !Tests: vc json schema spec tests (ongoing work) @@ -87,26 +83,26 @@ figure.table .overlarge { # Introduction # {#intro} -This specification provides a mechanism for the use of verifiable credentials in a highly scalable, secure, and verifiable way. A large part of the integrity of a verifiable credential is how to structure the credential so that all three parties (issuer, holder, verifier) may have a singular mechanism of trust into what they are using. We call that document a [=Credential Schema=]. +This specification provides a mechanism for the use of verifiable credentials in a highly scalable, secure, and verifiable way. A large part of the integrity of a verifiable credential is how to structure the credential so that all three parties —- issuer, holder, verifier -- may have a singular mechanism of trust into what they are using. We call that document a [=Credential Schema=]. -This specification provides a standardized way of creating [=Credential Schema=]s to be used in credentialing platforms, how to version them, and how to read them. +This specification provides a standardized way of creating [=Credential Schema=]s to be used in credentialing platforms, how to version them, and how to read them. Credential Schemas may apply to any portion of a Verifiable Credential. Multiple JSON Schemas may back a single Verifiable Credential, e.g. a schema for the `credentialSubject` and another for other credential properties. # Terminology # {#terminology} : id -:: A globally unique identifier to locate the schema on a distributed ledger. Each credential schema has its own unique identifier, and each version of a credential schema is required to have its own unique identifier.

This identifier is a [Generic DID Parameter Name](https://w3c.github.io/did-core/#did-syntax) based upon the author of the schema. For example, if the author had a did like 
did:work:abcdefghi
a possible schema ID the author created would have an identifier such as: 
did:work:abcdefghi;id=17de181feb67447da4e78259d92d0240;version=1.0
+:: A locally unique identifier to locate the schema on a given data storage medium (e.g. a database, ledger, distributed file store). Each credential schema has its own unique identifier, and each version of a schema is required to have its own unique identifier.

This identifier is a [Uniform Resource Identifier](https://www.rfc-editor.org/rfc/rfc3986) that _may_ contain informatoin pertaining to the author and version of the schema. For example, if the author had a DID like 
did:key:abcdefghi
a possible schema ID the author created would have an identifier such as: 
did:key:abcdefghi;id=17de181feb67447da4e78259d92d0240;version=1.0
. : Credential Schema :: The data template for a credential. Refers to the entirety of a [=Credential Schema=], including both the [=Metadata=] and [=JSON Schema=]. The term may refer to a document either with, or without a [=proof=]. 
 {
-  "type": "https://w3c-ccg.github.io/vc-json-schemas/schema/1.0/schema.json",
-  "modelVersion": "1.0",
-  "id": "did:work:MDP8AsFhHzhwUvGNuYkX7T;id=06e126d1-fa44-4882-a243-1e326fbe21db;version=1.0",
+  "type": "https://w3c-ccg.github.io/vc-json-schemas/schema/2.0/schema.json",
+  "version": "2.0",
+  "id": "did:key:MDP8AsFhHzhwUvGNuYkX7T;id=06e126d1-fa44-4882-a243-1e326fbe21db;version=1.0",
   "name": "Email",
-  "author": "did:work:MDP8AsFhHzhwUvGNuYkX7T",
-  "authored": "2018-01-01T00:00:00+00:00"
+  "author": "did:key:MDP8AsFhHzhwUvGNuYkX7T",
+  "authored": "2021-01-01T00:00:00+00:00"
 }
@@ -135,7 +131,7 @@ This specification provides a standardized way of creating [=Credential Schema=] : type :: It is important in software systems for machines to understand the context of what a document is. In credential schemas this is declared in the type field. This field resolves to a JSON schema with details about the schema metadata that applies to the schema. A piece of [=Metadata=]. -: modelVersion +: version :: After a machine has parsed the type property it should know that the document it is reading is a [=Credential Schema=]. The next field is the version, which denotes what version of the schema metadata this is. A piece of [=Metadata=]. : schemaVersion @@ -215,7 +211,7 @@ With adherance to the specification, the following guarantees can be made about ### Versioning ### {#versioning} -Schemas are versioned in two ways: [=modelVersion=] and [=schemaVersion=] properties. Versioning provides benefits for schema authors, issuers, and verifiers to make sense of their data. +Schemas are versioned in two ways: [=version=] and [=schemaVersion=] properties. Versioning provides benefits for schema authors, issuers, and verifiers to make sense of their data. Authors and Issuers care about versioning to track advancements and changes over time both for formatting changes (e.g. supporting [[JSON_SCHEMA]] Draft 7 as opposed to Draft 6) as well as fields as a schema converges to its most currently usable form (e.g. adding a new required field). Holders care about versioning to know where and how their credential can be used. Similarly, Verifiers care about versioning to know which data, or model versions they should accept in their systems. @@ -232,7 +228,7 @@ This section provides the [[JSON_SCHEMA]] definition for [=Credential Schema=] a "type": { "type": "string" }, - "modelVersion": { + "version": { "type": "string" }, "name": { @@ -313,7 +309,7 @@ This section provides the [[JSON_SCHEMA]] definition for [=Credential Schema=] a }, "required": [ "type", - "modelVersion", + "version", "name", "author", "authored", @@ -327,10 +323,10 @@ This section provides the [[JSON_SCHEMA]] definition for [=Credential Schema=] a 
 {
   "type": "https://w3c-ccg.github.io/vc-json-schemas/schema/1.0/schema.json",
-  "modelVersion": "1.0",
-  "id": "did:work:MDP8AsFhHzhwUvGNuYkX7T;id=06e126d1-fa44-4882-a243-1e326fbe21db;version=1.0",
+  "version": "1.0",
+  "id": "did:key:MDP8AsFhHzhwUvGNuYkX7T;id=06e126d1-fa44-4882-a243-1e326fbe21db;version=1.0",
   "name": "EmailCredentialSchema",
-  "author": "did:work:MDP8AsFhHzhwUvGNuYkX7T",
+  "author": "did:key:MDP8AsFhHzhwUvGNuYkX7T",
   "authored": "2018-01-01T00:00:00+00:00",
   "schema": {
     "$schema": "http://json-schema.org/draft-07/schema#",
@@ -347,7 +343,7 @@ This section provides the [[JSON_SCHEMA]] definition for [=Credential Schema=] a
   },
   "proof": {
       "created": "2019-09-27T06:26:11Z",
-      "creator": "did:work:MDP8AsFhHzhwUvGNuYkX7T#key-1",
+      "creator": "did:key:MDP8AsFhHzhwUvGNuYkX7T#key-1",
       "nonce": "0efba23d-2987-4441-998e-23a9d9af79f0",
       "signatureValue": "2A7ZF9f9TWMdtgn57Y6dP6RQGs52xg2QdjUESZUuf4J9BUnwwWFNL8vFshQAEQF6ZFBXjYLYNU4hzXNKc3R6y6re",
       "type": "Ed25519VerificationKey2018"
@@ -361,7 +357,7 @@ The properties, in order, before the JSON Schema document, embedded into the [=J
 
 1. [=type=]
 
-1. [=modelVersion=]
+1. [=version=]
 
 1. [=id=]
 
@@ -399,7 +395,7 @@ Under construction.
 
 # Versioning Guidelines # {#versioning_guidelines}
 
-This section applies to both [=schemaVersion=] and [=modelVersion=] properties of the metadata.
+This section applies to both [=schemaVersion=] and [=version=] properties of the metadata.
 
 Versioning is defined as MODEL.REVISION where MODEL is a breaking change and REVISION is non-breaking. The version is contained within the schema identifier.
 
@@ -416,10 +412,10 @@ The addition or removal of an optional field is what constitutes a REV
 
 {
  "type": "https://w3c-ccg.github.io/vc-json-schemas/schema/1.0/schema.json",
- "modelVersion": "1.0",
- "id": "did:work:MDP8AsFhHzhwUvGNuYkX7T;id=06e126d1-fa44-4882-a243-1e326fbe21db;version=1.0",
+ "version": "1.0",
+ "id": "did:key:MDP8AsFhHzhwUvGNuYkX7T;id=06e126d1-fa44-4882-a243-1e326fbe21db;version=1.0",
  "name": "EmailCredentialSchema",
- "author": "did:work:MDP8AsFhHzhwUvGNuYkX7T",
+ "author": "did:key:MDP8AsFhHzhwUvGNuYkX7T",
  "authored": "2018-01-01T00:00:00+00:00",
  "schema": {
    "$schema": "http://json-schema.org/draft-07/schema#",
@@ -442,10 +438,10 @@ In this example we once again reference the email schema, but this time we add a
 
 {
  "type": "https://w3c-ccg.github.io/vc-json-schemas/schema/1.0/schema.json",
- "modelVersion": "1.0",
- "id": "did:work:MDP8AsFhHzhwUvGNuYkX7T;id=06e126d1-fa44-4882-a243-1e326fbe21db;version=1.1",
+ "version": "1.0",
+ "id": "did:key:MDP8AsFhHzhwUvGNuYkX7T;id=06e126d1-fa44-4882-a243-1e326fbe21db;version=1.1",
  "name": "EmailCredentialSchema",
- "author": "did:work:abc123",
+ "author": "did:key:abc123",
  "authored": "2018-01-01T00:00:00+00:00",
  "schema": {
    "$schema": "http://json-schema.org/draft-07/schema#",
@@ -476,10 +472,10 @@ An example of this rule is when the additionalProperties field's value ch
 
 {
  "type": "https://w3c-ccg.github.io/vc-json-schemas/schema/1.0/schema.json",
- "modelVersion": "1.0",
- "id": "did:work:MDP8AsFhHzhwUvGNuYkX7T;id=06e126d1-fa44-4882-a243-1e326fbe21db;version=1.1",
+ "version": "1.0",
+ "id": "did:key:MDP8AsFhHzhwUvGNuYkX7T;id=06e126d1-fa44-4882-a243-1e326fbe21db;version=1.1",
  "name": "EmailCredentialSchema",
- "author": "did:work:MDP8AsFhHzhwUvGNuYkX7T",
+ "author": "did:key:MDP8AsFhHzhwUvGNuYkX7T",
  "authored": "2018-01-01T00:00:00+00:00",
  "schema": {
    "$schema": "http://json-schema.org/draft-07/schema#",
@@ -506,10 +502,10 @@ This time our credentialing requirements for email have changed and email addres
 
 {
  "type": "https://w3c-ccg.github.io/vc-json-schemas/schema/1.0/schema.json",
- "modelVersion": "1.0",
- "id": "did:work:MDP8AsFhHzhwUvGNuYkX7T;id=06e126d1-fa44-4882-a243-1e326fbe21db;version=2.0",
+ "version": "1.0",
+ "id": "did:key:MDP8AsFhHzhwUvGNuYkX7T;id=06e126d1-fa44-4882-a243-1e326fbe21db;version=2.0",
  "name": "EmailCredentialSchema",
- "author": "did:work:MDP8AsFhHzhwUvGNuYkX7T",
+ "author": "did:key:MDP8AsFhHzhwUvGNuYkX7T",
  "authored": "2018-01-01T00:00:00+00:00",
  "schema": {
    "$schema": "http://json-schema.org/draft-07/schema#",
@@ -536,7 +532,7 @@ This time our credentialing requirements for email have changed and email addres
 
 # Extensibility # {#extensibility}
 
-By introducing a [=modelVersion=] field we allow the [=credential schema=] to become extensible. Properties such as derivedFrom could reference a schema that a new schema is built on top of. Similarly, platform-utility features such as searchability could be provided by adding a tags array that contains categorization and classification information for a [=schema=].
+By introducing a [=version=] field we allow the [=credential schema=] to become extensible. Properties such as derivedFrom could reference a schema that a new schema is built on top of. Similarly, platform-utility features such as searchability could be provided by adding a tags array that contains categorization and classification information for a [=schema=].
 
 These are just a few examples that illustrate the flexibility of the proposed model. It can be extended to support a wide variety of use-cases and make the burden on issuance and verification simpler by facilitating the development of higher-level tooling.
 
@@ -549,15 +545,15 @@ We define an Email schema as the basis for a credential.
 
 {
   "type": "https://w3c-ccg.github.io/vc-json-schemas/schema/1.0/schema.json",
-  "modelVersion": "1.0",
-  "id": "did:work:MDP8AsFhHzhwUvGNuYkX7T;id=06e126d1-fa44-4882-a243-1e326fbe21db;version=1.0",
+  "version": "1.0",
+  "id": "did:key:MDP8AsFhHzhwUvGNuYkX7T;id=06e126d1-fa44-4882-a243-1e326fbe21db;version=1.0",
   "name": "Email",
-  "author": "did:work:MDP8AsFhHzhwUvGNuYkX7T",
+  "author": "did:key:MDP8AsFhHzhwUvGNuYkX7T",
   "authored": "2018-01-01T00:00:00+00:00"
 }
 

 
-The example references a [=Credential Schema=] with the [=Credential Schema=] identifier did:work:MDP8AsFhHzhwUvGNuYkX7T;id=06e126d1-fa44-4882-a243-1e326fbe21db;version=1.0 inside of a Verifiable Credential following the [[VC_DATA_MODEL]]. The example is adapted from Example 18 in the specification.
+The example references a [=Credential Schema=] with the [=Credential Schema=] identifier did:key:MDP8AsFhHzhwUvGNuYkX7T;id=06e126d1-fa44-4882-a243-1e326fbe21db;version=1.0 inside of a Verifiable Credential following the [[VC_DATA_MODEL]]. The example is adapted from Example 18 in the specification.
 
 
 {
@@ -570,11 +566,11 @@ The example references a [=Credential Schema=] with the [=Credential Schema=] id
   "issuer": "https://example.com/issuers/565049",
   "issuanceDate": "2010-01-01T19:73:24Z",
   "credentialSchema": {
-    "id": "did:work:MDP8AsFhHzhwUvGNuYkX7T;id=06e126d1-fa44-4882-a243-1e326fbe21db;version=1.0",
+    "id": "did:key:MDP8AsFhHzhwUvGNuYkX7T;id=06e126d1-fa44-4882-a243-1e326fbe21db;version=1.0",
     "type": "JsonSchemaValidator2018"
   },
   "credentialSubject": {
-    "id": "did:work:MDP8AsFhHzhwUvGNuYkX7T",
+    "id": "did:key:MDP8AsFhHzhwUvGNuYkX7T",
     "emailAddress": "first.last@example.com"
     }
   },
@@ -588,7 +584,7 @@ The ID of the [=Credential Schema=] is visible in the credentialSchema se
 
 Within a credentialing ecosystem, relying heavily upon [[JSON Schema]] makes data shapes for credentials consistent, and could enable an ecosystem with many similar schemas with slight changes (naming, capitalization). Without proper oversight or authoritative schemas to limit duplication or misuse, utilization of [[JSON_SCHEMA]] could lead to a poor user experience. At a higher, platform level tooling can be provided to minimize confusion and promote reuse.
 
-Within the broader Credentialing Ecosystem, interoperability could be more difficult if the wider community adopts [[JSON-LD]] without advocating for pairing with [[JSON_SCHEMA]] based schemas or credentials. This issue can mainly be side-stepped with the metadata we include –– the Credential Schema –– since this model is flexible to change. A new [=modelVersion=] could be introduced that supports [[JSON-LD]] and removes support for [[JSON_SCHEMA]]. A drawback here is the requirement that all schemas have this piece of metadata, which itself is versioned and evolvable.
+Within the broader Credentialing Ecosystem, interoperability could be more difficult if the wider community adopts [[JSON-LD]] without advocating for pairing with [[JSON_SCHEMA]] based schemas or credentials. This issue can mainly be side-stepped with the metadata we include –– the Credential Schema –– since this model is flexible to change. A new [=version=] could be introduced that supports [[JSON-LD]] and removes support for [[JSON_SCHEMA]]. A drawback here is the requirement that all schemas have this piece of metadata, which itself is versioned and evolvable.
 
 A flip side to drawbacks of the usage of [[JSON_SCHEMA]] is that there is a plethora of documentation, libraries, and usage of [[JSON Schema]] across programming languages and the web.
 
diff --git a/spec/index.html b/spec/index.html
new file mode 100644
index 0000000..80e4bef
--- /dev/null
+++ b/spec/index.html
@@ -0,0 +1,1039 @@
+
+ 
+  
+  
+  Verifiable Credentials JSON Schema Specification
+  
+  
+  
+  
+
+
+
+
+
+
+
+  
+ 
+  

+   
 

+   
Verifiable Credentials JSON Schema Specification

+   
Draft Community Group Report, 

+   
+   

+   
Copyright © 2021 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and permissive document license rules apply. 

+   

+  

+  

+   
Abstract

+   
The [VC_DATA_MODEL] specifies the models used for Verifiable Credentials and
+
+  Verifiable Presentations, and explains the relationships between three parties: issuer, holder, and verifier. A critical piece of infrastructure out of the
+  scope of those specifications is the Credential Schema. This specification provides
+  a mechanism to express a Credential Schema and the protocols for evolving the schema.

+  

+  
Status of this document

+  

+   

+  

+  

+  
+  

+   
1. Introduction

+    This specification provides a mechanism for the use of verifiable credentials in a highly scalable, secure, and verifiable way. A large part of the integrity of a verifiable credential is how to structure the credential so that all three parties —- issuer, holder, verifier -- may have a singular mechanism of trust into what they are using. We call that document a Credential Schema. 
+   
This specification provides a standardized way of creating Credential Schemas to be used in credentialing platforms, how to version them, and how to read them. Credential Schemas may apply to any portion of a Verifiable Credential. Multiple JSON Schemas may back a single Verifiable Credential, e.g. a schema for the credentialSubject and another for other credential properties.

+   
2. Terminology

+   

+    
id
+    

+     
A locally unique identifier to locate the schema on a given data storage medium (e.g. a database, ledger, distributed file store). Each credential schema has its own unique identifier, and each version of a schema is required to have its own unique identifier. 
 
 This identifier is a Uniform Resource Identifier that _may_ contain informatoin pertaining to the author and version of the schema. For example, if the author had a DID like 

+
did:key:abcdefghi

+      a possible schema ID the author created would have an identifier such as: 
+
did:key:abcdefghi;id=17de181feb67447da4e78259d92d0240;version=1.0

+     .
+     

+    
Credential Schema
+    

+     
The data template for a credential. Refers to the entirety of a Credential Schema, including both the Metadata and JSON Schema. The term may refer to a document either with, or without a proof.

+   

+
{
+  "type": "https://w3c-ccg.github.io/vc-json-schemas/schema/2.0/schema.json",
+  "version": "2.0",
+  "id": "did:key:MDP8AsFhHzhwUvGNuYkX7T;id=06e126d1-fa44-4882-a243-1e326fbe21db;version=1.0",
+  "name": "Email",
+  "author": "did:key:MDP8AsFhHzhwUvGNuYkX7T",
+  "authored": "2021-01-01T00:00:00+00:00"
+}
+

+   

+    
Metadata
+    

+     
Top-level information on a Credential Schema. Pieces of data wrapping the JSON Schema to provide further context about the schema.

+   

+
{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "description": "Email",
+  "type": "object",
+  "properties": {
+    "emailAddress": {
+      "type": "string",
+      "format": "email"
+    }
+  },
+  "required": ["emailAddress"],
+  "additionalProperties": false
+}
+

+   

+    
proof
+    

+     
A digital signature over the Credential Schema for the sake of claiming authorship. A piece of Metadata.

+    
type
+    

+     
It is important in software systems for machines to understand the context of what a document is. In credential schemas this is declared in the type field. This field resolves to a JSON schema with details about the schema metadata that applies to the schema. A piece of Metadata.

+    
version
+    

+     
After a machine has parsed the type property it should know that the document it is reading is a Credential Schema. The next field is the version, which denotes what version of the schema metadata this is. A piece of Metadata.

+    
schemaVersion
+    

+     
A version that applies to both the JSON Schema and Metadata. A piece of Metadata.

+    
name
+    

+     
A human-readable name for the schema. A piece of Metadata.

+    
author
+    

+     
[DID] of the identity which authored the credential schema. A piece of Metadata.

+    
authored
+    

+     
[RFC-3339] date on which the schema was created. A piece of Metadata.

+    
JSON Schema
+    

+     
schema

+    
schema
+    

+     
This is where the Credential Schema data fields are defined as a valid [JSON_SCHEMA]. A piece of Metadata.

+   

+
{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "description": "Email",
+    "type": "object",
+    "properties": {
+        "emailAddress": {
+            "type": "string",
+            "format": "email"
+        }
+    },
+    "required": ["emailAddress"],
+    "additionalProperties": false
+}
+

+   

+    
Verifiable Credential
+    

+     
See [VC_DATA_MODEL]

+   

+   
3. Standards & Compliance

+   
The [VC_DATA_MODEL] specifies the models used for Verifiable Credentials and Verifiable Presentations, and while this spec attempts to align closely to the W3C model, it should NOT be assumed this specification is fully compliant at the time of this writing. Ultimately, we would like to comply with the W3C specification; however, due to the fact that the W3C specification is under active development and is subject to change, we have diverged from that model with several "forks" that are fully outlined in this specification.

+   
4. Formatting

+   
The [VC_DATA_MODEL] provides its examples in the JSON Linked Data interchange format. The specification allows for other formats, such as standard JSON with JSON Schema but provides only limited examples. In the credentialSchema section, JSON-SCHEMA-2018 validation is explicitly called out. This specification does not use [JSON-LD]. If it becomes evident that it would be useful to include [JSON-LD] or another format that decision would be made in a revisal draft at a later date.

+   
The Verifiable Credentials data model relies heavily upon standard JSON with validation provided by [JSON_SCHEMA] Draft 7. The data model embeds [JSON_SCHEMA] documents inside a larger document that contains useful metadata about a given credential schema.

+   
5. Specification

+   
5.1. Overview

+   
The Credential Schema is a document that is used to guarantee the structure, and by extension the semantics, of the set of claims comprising a Verifiable Credential. A shared Credential Schema allows all parties to reference data in a known way.

+   
A schema can be viewed from four perspectives: the author, issuer, verifier and holder.

+   
Author: An author creates a schema as a blueprint for a verifiable credential, specifying the shape and format of the data in such a credential.

+   
Issuer: Issuers utilize schemas to provide structure and meaning to the data they issue as verifiable credentials. By using schemas, issuers contribute to a credentialing ecosystem, and promote the use and adoption of data standards.

+   
Verifier: A verifier requesting data needs to do so with knowledge of the credential shapes. Credential Schemas allow a Verifier to ask for data knowing that an issuer has issued in an understood way and that a holder’s wallet can find data matching that requested.

+   
Holder: Holders, or those who are the subject of credential issuance, can make sense of the data they own -- values -- by viewing it against a schema -- keys. When data is requested from them by referencing a Credential Schema, this known structure allows the holder’s wallet to return the data specifically requested by the verifier.

+   
5.1.1. Guarantees

+   
With adherance to the specification, the following guarantees can be made about a schema:

+   
    
+    
  • 
+     
    A schema is versionable and new versions can evolve it over time
    
+    
  • 
+     
    A schema is available for any issuer to use and any verifier, or other platform member to read
    
+    
  • 
+     
    A schema always guarantees the structure of a credential. The described structure can be used by the Verifier to understand what data the Holder holds. There is no requirement for the Verifier to validate sent data against the schema since this sent data may only be partial, for example in event of a proof request only requiring a single field from a credential with multiple fields defined in the schema.
    
+   

+   
5.1.2. Storage

+   
Credential Schemas are created and made available as immutable objects on a distributed ledger. Among other benefits, this makes tie-in easier with [DID] authors.

+   
5.1.3. Versioning

+   
Schemas are versioned in two ways: version and schemaVersion properties. Versioning provides benefits for schema authors, issuers, and verifiers to make sense of their data.

+   
Authors and Issuers care about versioning to track advancements and changes over time both for formatting changes (e.g. supporting [JSON_SCHEMA] Draft 7 as opposed to Draft 6) as well as fields as a schema converges to its most currently usable form (e.g. adding a new required field). Holders care about versioning to know where and how their credential can be used. Similarly, Verifiers care about versioning to know which data, or model versions they should accept in their systems.

+   
5.2. Credential Schema Definition

+   
This section provides the [JSON_SCHEMA] definition for Credential Schema along with an example of a Credential Schema for an Email Verifiable Credential.

+   
JSON Schema

+
{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "type": {
+      "type": "string"
+    },
+    "version": {
+      "type": "string"
+    },
+    "name": {
+      "type": "string"
+    },
+    "author": {
+      "type": "string"
+    },
+    "authored": {
+      "type": "string"
+    },
+    "schema": {
+      "type": "object",
+      "properties": {
+        "$schema": {
+          "type": "string"
+        },
+        "description": {
+          "type": "string"
+        },
+        "name": {
+          "type": "string"
+        },
+        "type": {
+          "type": "string"
+        },
+        "properties": {
+          "type": "object"
+        },
+        "required": {
+          "type": "array",
+          "items": [
+            {
+              "type": "string"
+            }
+          ]
+        },
+        "additionalProperties": {
+          "type": "boolean"
+        }
+      },
+      "required": [
+        "$schema",
+        "description",
+        "type",
+        "properties",
+        "required",
+        "additionalProperties"
+      ]
+    },
+    "proof": {
+      "type": "object",
+      "properties": {
+        "created": {
+          "type": "string"
+        },
+        "creator": {
+          "type": "string"
+        },
+        "nonce": {
+          "type": "string"
+        },
+        "signatureValue": {
+          "type": "string"
+        },
+        "type": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "created",
+        "creator",
+        "nonce",
+        "signatureValue",
+        "type"
+      ]
+    }
+  },
+  "required": [
+    "type",
+    "version",
+    "name",
+    "author",
+    "authored",
+    "schema",
+    "proof"
+  ]
+}
+

+   
Example

+
{
+  "type": "https://w3c-ccg.github.io/vc-json-schemas/schema/1.0/schema.json",
+  "version": "1.0",
+  "id": "did:key:MDP8AsFhHzhwUvGNuYkX7T;id=06e126d1-fa44-4882-a243-1e326fbe21db;version=1.0",
+  "name": "EmailCredentialSchema",
+  "author": "did:key:MDP8AsFhHzhwUvGNuYkX7T",
+  "authored": "2018-01-01T00:00:00+00:00",
+  "schema": {
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "description": "Email",
+    "type": "object",
+    "properties": {
+      "emailAddress": {
+        "type": "string",
+        "format": "email"
+      }
+    },
+    "required": ["emailAddress"],
+    "additionalProperties": false
+  },
+  "proof": {
+      "created": "2019-09-27T06:26:11Z",
+      "creator": "did:key:MDP8AsFhHzhwUvGNuYkX7T#key-1",
+      "nonce": "0efba23d-2987-4441-998e-23a9d9af79f0",
+      "signatureValue": "2A7ZF9f9TWMdtgn57Y6dP6RQGs52xg2QdjUESZUuf4J9BUnwwWFNL8vFshQAEQF6ZFBXjYLYNU4hzXNKc3R6y6re",
+      "type": "Ed25519VerificationKey2018"
+  }
+}
+

+   
5.2.1. Metadata

+   
The properties, in order, before the JSON Schema document, embedded into the JSON Schema are as follows:

+   
    
+    
  1. 
+     
    type
    
+    
  2. 
+     
    version
    
+    
  3. 
+     
    id
    
+    
  4. 
+     
    schemaVersion
    
+    
  5. 
+     
    name
    
+    
  6. 
+     
    author
    
+    
  7. 
+     
    authored
    
+   

+   
5.2.2. Schema

+   
This is where the Credential Schema data fields are defined as a valid JSON Schema document.

+
{
+ "$schema": "http://json-schema.org/draft-07/schema#",
+ "description": "Email",
+ "type": "object",
+ "properties": {
+   "emailAddress": {
+       "type": "string",
+       "format": "email"
+   }
+ },
+ "required": ["emailAddress"],
+ "additionalProperties": false
+}
+

+   
5.2.3. Proof

+   
Under construction.

+   
6. Versioning Guidelines

+   
This section applies to both schemaVersion and version properties of the metadata.

+   
Versioning is defined as MODEL.REVISION where MODEL is a breaking change and REVISION is non-breaking. The version is contained within the schema identifier.

+   
With schemas we are concerned with a new schema and backwards compatibility of existing data on an older schema.

+   
MODEL Updating this number tells the end user that this version breaks the schema for ANY interaction with an older schema. For verification if a holder presents a credential built from a schema of version 1.0 and the platform is only looking for > 2.0, it is not able to parse ANY information.

+   
REVISION Updating this number tells the end user that this version may prevent interactions with parts of the schema. For verification if a holder presents a credential built from a schema of version 1.0 and the platform is looking for > 1.5, there are likely to be SOME fields incompatible with the expected credential.

+   
6.1. Revision

+   
The addition or removal of an optional field is what constitutes a REVISION. Adding or removing an optional field does not break historical data in a schema and in the claims exchange protocol fields that are returned negative in the optional field can be ignored as they are optional by default.

+
{
+ "type": "https://w3c-ccg.github.io/vc-json-schemas/schema/1.0/schema.json",
+ "version": "1.0",
+ "id": "did:key:MDP8AsFhHzhwUvGNuYkX7T;id=06e126d1-fa44-4882-a243-1e326fbe21db;version=1.0",
+ "name": "EmailCredentialSchema",
+ "author": "did:key:MDP8AsFhHzhwUvGNuYkX7T",
+ "authored": "2018-01-01T00:00:00+00:00",
+ "schema": {
+   "$schema": "http://json-schema.org/draft-07/schema#",
+   "description": "Email",
+   "type": "object",
+   "properties": {
+      "emailAddress": {
+      "type": "string",
+      "format": "email"
+    }
+   },
+   "required": ["emailAddress"],
+   "additionalProperties": false
+ }
+}
+

+   
In this example we once again reference the email schema, but this time we add an optional field backupEmailAddress. Notice how this would not break the claims exchange because the field is optional.

+
{
+ "type": "https://w3c-ccg.github.io/vc-json-schemas/schema/1.0/schema.json",
+ "version": "1.0",
+ "id": "did:key:MDP8AsFhHzhwUvGNuYkX7T;id=06e126d1-fa44-4882-a243-1e326fbe21db;version=1.1",
+ "name": "EmailCredentialSchema",
+ "author": "did:key:abc123",
+ "authored": "2018-01-01T00:00:00+00:00",
+ "schema": {
+   "$schema": "http://json-schema.org/draft-07/schema#",
+   "description": "Email",
+   "type": "object",
+   "properties": {
+    "emailAddress": {
+      "type": "string",
+      "format": "email"
+    },
+    "backupEmailAddress": {
+      "type": "string",
+      "format": "email"
+    }
+   },
+   "required": ["emailAddress"],
+   "additionalProperties": false
+ }
+}
+

+   
6.2. Model

+   
When a schema breaks historical data we call it a model change. This is the major differentiating point between other schema versioning protocols which allow for some breaking changes because as we learned in the problem section, even breaking one area can lead to very difficult issues for verifiers through the credential exchange protocol. The most common case of a MODEL change is the addition or subtraction of a required field. It is also important to note that for the change of a key name on a required field constitutes a MODEL change. Why? Because technically that introduces a breaking change and adds a required field.

+   
An example of this rule is when the additionalProperties field’s value changes. Changing additionalProperties from false to true OR from true to false constitutes a breaking change, necessitating a MODEL increment.

+
{
+ "type": "https://w3c-ccg.github.io/vc-json-schemas/schema/1.0/schema.json",
+ "version": "1.0",
+ "id": "did:key:MDP8AsFhHzhwUvGNuYkX7T;id=06e126d1-fa44-4882-a243-1e326fbe21db;version=1.1",
+ "name": "EmailCredentialSchema",
+ "author": "did:key:MDP8AsFhHzhwUvGNuYkX7T",
+ "authored": "2018-01-01T00:00:00+00:00",
+ "schema": {
+   "$schema": "http://json-schema.org/draft-07/schema#",
+   "description": "Email",
+   "type": "object",
+   "properties": {
+    "emailAddress": {
+      "type": "string",
+      "format": "email"
+    },
+    "backupEmailAddress": {
+      "type": "string",
+      "format": "email"
+    }
+   },
+   "required": ["emailAddress"],
+   "additionalProperties": false
+ }
+}
+

+   
This time our credentialing requirements for email have changed and email address is no longer enough information on a credential, and we need to attach a name for verification as well to our schema. This is a required field, so we know it is a MODEL change.

+
{
+ "type": "https://w3c-ccg.github.io/vc-json-schemas/schema/1.0/schema.json",
+ "version": "1.0",
+ "id": "did:key:MDP8AsFhHzhwUvGNuYkX7T;id=06e126d1-fa44-4882-a243-1e326fbe21db;version=2.0",
+ "name": "EmailCredentialSchema",
+ "author": "did:key:MDP8AsFhHzhwUvGNuYkX7T",
+ "authored": "2018-01-01T00:00:00+00:00",
+ "schema": {
+   "$schema": "http://json-schema.org/draft-07/schema#",
+   "description": "Email",
+   "type": "object",
+   "properties": {
+    "emailAddress": {
+      "type": "string",
+      "format": "email"
+    },
+    "firstName": {
+      "type": "string"
+    },
+    "backupEmailAddress": {
+      "type": "string",
+      "format": "email"
+    }
+   },
+   "required": ["emailAddress", "firstName"],
+   "additionalProperties": false
+ }
+}
+

+   
7. Extensibility

+   
By introducing a version field we allow the credential schema to become extensible. Properties such as derivedFrom could reference a schema that a new schema is built on top of. Similarly, platform-utility features such as searchability could be provided by adding a tags array that contains categorization and classification information for a schema.

+   
These are just a few examples that illustrate the flexibility of the proposed model. It can be extended to support a wide variety of use-cases and make the burden on issuance and verification simpler by facilitating the development of higher-level tooling.

+   
8. Examples

+   
8.1. Verifiable Credentials

+   
We define an Email schema as the basis for a credential.

+
{
+  "type": "https://w3c-ccg.github.io/vc-json-schemas/schema/1.0/schema.json",
+  "version": "1.0",
+  "id": "did:key:MDP8AsFhHzhwUvGNuYkX7T;id=06e126d1-fa44-4882-a243-1e326fbe21db;version=1.0",
+  "name": "Email",
+  "author": "did:key:MDP8AsFhHzhwUvGNuYkX7T",
+  "authored": "2018-01-01T00:00:00+00:00"
+}
+

+   
The example references a Credential Schema with the Credential Schema identifier did:key:MDP8AsFhHzhwUvGNuYkX7T;id=06e126d1-fa44-4882-a243-1e326fbe21db;version=1.0 inside of a Verifiable Credential following the [VC_DATA_MODEL]. The example is adapted from Example 18 in the specification.

+
{
+  "@context": [
+    "https://www.w3.org/2018/credentials/v1",
+    "https://www.w3.org/2018/credentials/examples/v1"
+  ],
+  "id": "http://example.edu/credentials/1872",
+  "type": ["VerifiableCredential", "EmailCredential"],
+  "issuer": "https://example.com/issuers/565049",
+  "issuanceDate": "2010-01-01T19:73:24Z",
+  "credentialSchema": {
+    "id": "did:key:MDP8AsFhHzhwUvGNuYkX7T;id=06e126d1-fa44-4882-a243-1e326fbe21db;version=1.0",
+    "type": "JsonSchemaValidator2018"
+  },
+  "credentialSubject": {
+    "id": "did:key:MDP8AsFhHzhwUvGNuYkX7T",
+    "emailAddress": "first.last@example.com"
+    }
+  },
+  "proof": { ... }
+}
+

+   
The ID of the Credential Schema is visible in the credentialSchema section of the credential, and describes the shape of the email schema. The type of JsonSchemaValidator2018 refers to a [JSON-LD] type providing information on how the data in the credentialSubject should be validated against the provided schema.

+   
9. Drawbacks

+   
Within a credentialing ecosystem, relying heavily upon [[JSON Schema]] makes data shapes for credentials consistent, and could enable an ecosystem with many similar schemas with slight changes (naming, capitalization). Without proper oversight or authoritative schemas to limit duplication or misuse, utilization of [JSON_SCHEMA] could lead to a poor user experience. At a higher, platform level tooling can be provided to minimize confusion and promote reuse.

+   
Within the broader Credentialing Ecosystem, interoperability could be more difficult if the wider community adopts [JSON-LD] without advocating for pairing with [JSON_SCHEMA] based schemas or credentials. This issue can mainly be side-stepped with the metadata we include –– the Credential Schema –– since this model is flexible to change. A new version could be introduced that supports [JSON-LD] and removes support for [JSON_SCHEMA]. A drawback here is the requirement that all schemas have this piece of metadata, which itself is versioned and evolvable.

+   
A flip side to drawbacks of the usage of [JSON_SCHEMA] is that there is a plethora of documentation, libraries, and usage of [[JSON Schema]] across programming languages and the web.

+   
10. Alternatives

+   
[JSON-LD] is the most prominent alternative, though it has been suggested that both [[JSON Schema]] and [JSON-LD] can work symbiotically in the credentialing ecosystem.

+   
11. Security & Privacy Considerations

+   
Privacy & security considerations mainly revolve around Personally Identifiable Information (PII) leaks in schemas. Any field which a user could enter data is a potential area for personally identifiable information. When implementing systems that support the storage and querying of schemas relevant data privacy laws and regulations must be taken into account.

+   
12. Interoperability

+   
The primary concern of this specification is to facilitate an ecosystem in which Verifiable Credentials can be issued and used. To be interoperable, additional schema types may need to be supported. Given the investment into a robust versioning strategy of our Credential Schema Metadata interoperability with the current design is less of a concern.

+   
A goal of publishing this document is to promote others to adopt our schema philosophy. It also opens the door for providing feedback and collaborative contribution to developing primitives that would lead to a successful verifiable ecosystem.

+  

+
+  
Index

+  
Terms defined by this specification

+  
+  
References

+  
Informative References

+  

+   
[DID]
+   
Decentralized Identifiers (DIDs) v1.0. URL: https://w3c.github.io/did-core/
+   
[JSON-LD]
+   
JSON-LD 1.1: A JSON-based Serialization for Linked Data. URL: https://w3c.github.io/json-ld-syntax/
+   
[JSON_SCHEMA]
+   
JSON Schema Draft 7. URL: https://json-schema.org/
+   
[RFC-3339]
+   
Date and Time on the Internet: Timestamps. URL: https://tools.ietf.org/html/rfc3339
+   
[VC_DATA_MODEL]
+   
Verifiable Credentials Data Model 1.0. URL: https://www.w3.org/TR/vc-data-model/
+  

+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+
\ No newline at end of file

From c4a066280089cf454c9fa5e9e4fc86fae6c2c052 Mon Sep 17 00:00:00 2001
From: Gabe Choen 
Date: Fri, 17 Sep 2021 11:54:13 -0700
Subject: [PATCH 2/7] draft 2

---
 spec/index.bs   |  58 +++++++++++++------------
 spec/index.html | 113 ++++++++++++++++++++++--------------------------
 2 files changed, 83 insertions(+), 88 deletions(-)

diff --git a/spec/index.bs b/spec/index.bs
index 00714e2..157852f 100644
--- a/spec/index.bs
+++ b/spec/index.bs
@@ -11,7 +11,7 @@ ED: https://w3c-ccg.github.io/vc-json-schemas/
 Shortname: vcjsonschemaspec
 Level: 1
 
-Editor: Gabe Cohen, w3cid  gabe.cohen@hey.com
+Editor: Gabe Cohen, w3cid 116851, gabe.cohen@hey.com
 Editor: Orie Steele, w3cid 109171, [Transmute](https://www.transmute.industries/), orie@transmute.industries
 
 group: ccg
@@ -83,14 +83,14 @@ figure.table .overlarge {
 
 
 # Introduction # {#intro}
-This specification provides a mechanism for the use of verifiable credentials in a highly scalable, secure, and verifiable way. A large part of the integrity of a verifiable credential is how to structure the credential so that all three parties —- issuer, holder, verifier -- may have a singular mechanism of trust into what they are using. We call that document a [=Credential Schema=].
+This specification provides a mechanism for the use of verifiable credentials in a highly scalable, secure, and verifiable way. A large part of the integrity of a verifiable credential is how to structure the credential so that all three parties — issuer, holder, verifier — may have a singular mechanism of trust into what they are using. We call that document a [=Credential Schema=].
 
-This specification provides a standardized way of creating [=Credential Schema=]s to be used in credentialing platforms, how to version them, and how to read them. Credential Schemas may apply to any portion of a Verifiable Credential. Multiple JSON Schemas may back a single Verifiable Credential, e.g. a schema for the `credentialSubject` and another for other credential properties.
+This specification provides a standardized way of creating [=Credential Schemas=] to be used in credentialing platforms, how to version them, and how to read them. Credential Schemas may apply to any portion of a Verifiable Credential. Multiple JSON Schemas may back a single Verifiable Credential, e.g. a schema for the `credentialSubject` and another for other credential properties.
 
 # Terminology # {#terminology}
 
 : id
-:: A locally unique identifier to locate the schema on a given data storage medium (e.g. a database, ledger, distributed file store). Each credential schema has its own unique identifier, and each version of a schema is required to have its own unique identifier. 
 
 This identifier is a [Uniform Resource Identifier](https://www.rfc-editor.org/rfc/rfc3986) that _may_ contain informatoin pertaining to the author and version of the schema. For example, if the author had a DID like 
did:key:abcdefghi
 a possible schema ID the author created would have an identifier such as: 
did:key:abcdefghi;id=17de181feb67447da4e78259d92d0240;version=1.0
.
+:: A locally unique identifier to locate the schema on a given data storage medium (e.g. a database, ledger, distributed file store). Each credential schema has its own unique identifier, and each version of a schema is required to have its own unique identifier. 
 
 This identifier is a [Uniform Resource Identifier](https://www.rfc-editor.org/rfc/rfc3986) that may contain informatoin pertaining to the author and version of the schema. For example, if the author had a DID like 
did:key:abcdefghi
 a possible schema ID the author created would have an identifier such as: 
did:key:abcdefghi;id=17de181feb67447da4e78259d92d0240;version=1.0
.
 
 : Credential Schema
 :: The data template for a credential. Refers to the entirety of a [=Credential Schema=], including both the [=Metadata=] and [=JSON Schema=]. The term may refer to a document either with, or without a [=proof=].
@@ -132,10 +132,7 @@ This specification provides a standardized way of creating [=Credential Schema=]
 :: It is important in software systems for machines to understand the context of what a document is. In credential schemas this is declared in the type field. This field resolves to a JSON schema with details about the schema metadata that applies to the schema. A piece of [=Metadata=].
 
 : version
-:: After a machine has parsed the type property it should know that the document it is reading is a [=Credential Schema=]. The next field is the version, which denotes what version of the schema metadata this is. A piece of [=Metadata=].
-
-: schemaVersion
-:: A version that applies to both the [=JSON Schema=] and [=Metadata=]. A piece of [=Metadata=].
+:: Denotes the revision of a given Credential Schema.
 
 : name
 :: A human-readable name for the schema. A piece of [=Metadata=].
@@ -177,9 +174,9 @@ The [[VC_DATA_MODEL]] specifies the models used for Verifiable Credentials and V
 
 # Formatting # {#formatting}
 
-The [[VC_DATA_MODEL]] provides its examples in the JSON Linked Data interchange format. The specification allows for other formats, such as standard JSON with JSON Schema but provides only limited examples. In the [credentialSchema section](https://www.w3.org/TR/vc-data-model/#data-schemas), JSON-SCHEMA-2018 validation is explicitly called out. This specification does not use [[JSON-LD]]. If it becomes evident that it would be useful to include [[JSON-LD]] or another format that decision would be made in a revisal draft at a later date.
+The [[VC_DATA_MODEL]] provides examples in the JSON Linked Data interchange format. The specification allows for other formats, such as standard JSON with JSON Schema but provides limited examples. In the [credentialSchema section](https://www.w3.org/TR/vc-data-model/#data-schemas), JSON-SCHEMA-2018 validation is noted explicitly. This specification does not use [[JSON-LD]]. If it becomes evident that it would be useful to include [[JSON-LD]] or another format that decision would be made in a revisal draft at a later date.
 
-The Verifiable Credentials data model relies heavily upon standard JSON with validation provided by [[JSON_SCHEMA]] Draft 7. The data model embeds [[JSON_SCHEMA]] documents inside a larger document that contains useful metadata about a given credential schema.
+The Verifiable Credentials data model relies heavily upon standard JSON with validation provided by [[JSON_SCHEMA]]. The data model embeds [[JSON_SCHEMA]] documents inside a larger document that contains useful metadata about a given credential schema.
 
 # Specification # {#specification}
 
@@ -193,27 +190,27 @@ A schema can be viewed from four perspectives: the author, issuer, verifier and
 
 Issuer: Issuers utilize schemas to provide structure and meaning to the data they issue as verifiable credentials. By using schemas, issuers contribute to a credentialing ecosystem, and promote the use and adoption of data standards.
 
-Verifier: A verifier requesting data needs to do so with knowledge of the credential shapes. Credential Schemas allow a Verifier to ask for data knowing that an issuer has issued in an understood way and that a holder's wallet can find data matching that requested.
+Verifier: A verifier requesting data needs to do so with knowledge of the credential shapes. Credential Schemas allow a Verifier to request data knowing that an issuer has generated a Credential in a well-known format, and that a holder can accurately respond to such a request.
 
-Holder: Holders, or those who are the subject of credential issuance, can make sense of the data they own -- values -- by viewing it against a schema -- keys. When data is requested from them by referencing a [=Credential Schema=], this known structure allows the holder's wallet to return the data specifically requested by the verifier.
+Holder: Holders, or those who are the subject of credential issuance, can make sense of the data they own – values – by viewing it against a schema—keys. When data is requested from them by referencing a [=Credential Schema=], this known structure allows the holder to return the data specifically requested by the verifier.
 
 ### Guarantees ### {#guarantees}
 
 With adherance to the specification, the following guarantees can be made about a schema:
 
-- A schema is versionable and new versions can evolve it over time
-- A schema is available for any issuer to use and any verifier, or other platform member to read
-- A schema always guarantees the structure of a credential. The described structure can be used by the Verifier to understand what data the Holder holds. There is no requirement for the Verifier to validate sent data against the schema since this sent data may only be partial, for example in event of a proof request only requiring a single field from a credential with multiple fields defined in the schema.
+- A schema is versionable and new versions can evolve it over time.
+- A schema is available for any issuer to use and any verifier, or other platform member to read.
+- A schema always guarantees the structure of a credential. The described structure can be used by the Verifier to understand what data the Holder holds. There is no requirement for the Verifier to validate sent data against the schema since this sent data may only be partial, for example in event of a Presentation Request only requiring a singular field from a credential though there may be multiple fields defined in the schema.
 
 ### Storage ### {#storage}
 
-[=Credential Schema=]s are created and made available as immutable objects on a distributed ledger. Among other benefits, this makes tie-in easier with [[DID]] authors.
+[=Credential Schemas=] are created and made available as immutable objects on any number of storage mediums such as a distributed ledger, traditional database, or decentralized file storage. The same schema may be replicated across multiple file stores with the same identifier. Immutability is key to enable consistent sources of truth for credential issuance. Schemas can evolve by creating new versions.
 
 ### Versioning ### {#versioning}
 
-Schemas are versioned in two ways: [=version=] and [=schemaVersion=] properties. Versioning provides benefits for schema authors, issuers, and verifiers to make sense of their data.
+Schemas are versioned via a [=version=] property. The [=version=] denotes the revision of this specification the schema corresponds to.
 
-Authors and Issuers care about versioning to track advancements and changes over time both for formatting changes (e.g. supporting [[JSON_SCHEMA]] Draft 7 as opposed to Draft 6) as well as fields as a schema converges to its most currently usable form (e.g. adding a new required field). Holders care about versioning to know where and how their credential can be used. Similarly, Verifiers care about versioning to know which data, or model versions they should accept in their systems.
+Authors and Issuers care about versioning to track advancements and changes over time both for formatting changes (e.g. supporting [[JSON_SCHEMA]] [draft-bhutton-json-schema-00](https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-00) as opposed to [Draft 7](https://datatracker.ietf.org/doc/html/draft-handrews-json-schema-01)) as well as fields as a schema converges to its most currently usable form (e.g. adding a new required field). Holders care about versioning to know where and how their credential can be used. Similarly, Verifiers care about versioning to know which data, or schema versions they should accept in their systems.
 
 ## Credential Schema Definition ## {#credential_schema_definition}
 
@@ -361,8 +358,6 @@ The properties, in order, before the JSON Schema document, embedded into the [=J
 
 1. [=id=]
 
-1. [=schemaVersion=]
-
 1. [=name=]
 
 1. [=author=]
@@ -391,11 +386,15 @@ This is where the [=Credential Schema=] data fields are defined as a valid [=JSO
 
 ### Proof ### {#credential_schema_definition_proof}
 
-Under construction.
+Any [=Credential Schema=] may be authenticated using [[Linked_Data_Proofs]].
+
+
+  Example and more detail needed.
+

 
 # Versioning Guidelines # {#versioning_guidelines}
 
-This section applies to both [=schemaVersion=] and [=version=] properties of the metadata.
+This section applies to [=version=] properties of the metadata.
 
 Versioning is defined as MODEL.REVISION where MODEL is a breaking change and REVISION is non-breaking. The version is contained within the schema identifier.
 
@@ -582,15 +581,15 @@ The ID of the [=Credential Schema=] is visible in the credentialSchema se
 
 # Drawbacks # {#drawbacks}
 
-Within a credentialing ecosystem, relying heavily upon [[JSON Schema]] makes data shapes for credentials consistent, and could enable an ecosystem with many similar schemas with slight changes (naming, capitalization). Without proper oversight or authoritative schemas to limit duplication or misuse, utilization of [[JSON_SCHEMA]] could lead to a poor user experience. At a higher, platform level tooling can be provided to minimize confusion and promote reuse.
+Within a credentialing ecosystem, relying heavily upon [[JSON_SCHEMA]] makes data shapes for credentials consistent, and could enable an ecosystem with many similar schemas with slight changes (naming, capitalization). Without proper oversight or authoritative schemas to limit duplication or misuse, utilization of [[JSON_SCHEMA]] could lead to a poor user experience. At a higher, platform level tooling can be provided to minimize confusion and promote reuse.
 
 Within the broader Credentialing Ecosystem, interoperability could be more difficult if the wider community adopts [[JSON-LD]] without advocating for pairing with [[JSON_SCHEMA]] based schemas or credentials. This issue can mainly be side-stepped with the metadata we include –– the Credential Schema –– since this model is flexible to change. A new [=version=] could be introduced that supports [[JSON-LD]] and removes support for [[JSON_SCHEMA]]. A drawback here is the requirement that all schemas have this piece of metadata, which itself is versioned and evolvable.
 
-A flip side to drawbacks of the usage of [[JSON_SCHEMA]] is that there is a plethora of documentation, libraries, and usage of [[JSON Schema]] across programming languages and the web.
+A flip side to drawbacks of the usage of [[JSON_SCHEMA]] is that there is a plethora of documentation, libraries, and usage of [[JSON_SCHEMA]] across programming languages and the web.
 
 # Alternatives # {#alternatives}
 
-[[JSON-LD]] is the most prominent alternative, though it has been suggested that both [[JSON Schema]] and [[JSON-LD]] can work symbiotically in the credentialing ecosystem.
+[[JSON-LD]] is the most prominent alternative, though it has been suggested that both [[JSON_SCHEMA]] and [[JSON-LD]] can work symbiotically in the credentialing ecosystem.
 
 # Security & Privacy Considerations # {#security_and_privacy_considerations}
 
@@ -615,8 +614,8 @@ A goal of publishing this document is to promote others to adopt our schema phil
     "publisher": "IETF"
   },
   "JSON_SCHEMA": {
-    "href": "https://json-schema.org/",
-    "title": "JSON Schema Draft 7",
+    "href": "https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-00",
+    "title": "JSON Schema Bhutton Draft 00",
     "publisher": "json-schema-org"
   },
   "DID": {
@@ -628,6 +627,11 @@ A goal of publishing this document is to promote others to adopt our schema phil
     "href": "https://w3c.github.io/json-ld-syntax/",
     "title": "JSON-LD 1.1: A JSON-based Serialization for Linked Data",
     "publisher": "W3C"
+  },
+  "LINKED_DATA_PROOFS": {
+    "href": "https://w3c-ccg.github.io/ld-proofs/",
+    "title": "Linked Data Proofs 1.0",
+    "publisher": "W3C"
   }
 }
 

diff --git a/spec/index.html b/spec/index.html
index 80e4bef..3a394d3 100644
--- a/spec/index.html
+++ b/spec/index.html
@@ -6,7 +6,7 @@
   
   
   
-  
+  
 
+
+# Introduction # {#intro}
+This specification provides a mechanism for the use of verifiable credentials in a highly scalable, secure, and verifiable way. A large part of the integrity of a verifiable credential is how to structure the credential so that all three parties (issuer, holder, verifier) may have a singular mechanism of trust into what they are using. We call that document a [=Credential Schema=].
+
+This specification provides a standardized way of creating [=Credential Schema=]s to be used in credentialing platforms, how to version them, and how to read them.
+
+# Terminology # {#terminology}
+
+: id
+:: A globally unique identifier to locate the schema on a distributed ledger. Each credential schema has its own unique identifier, and each version of a credential schema is required to have its own unique identifier. 
 
 This identifier is a [Generic DID Parameter Name](https://w3c.github.io/did-core/#did-syntax) based upon the author of the schema. For example, if the author had a did like 
did:work:abcdefghi
 a possible schema ID the author created would have an identifier such as: 
did:work:abcdefghi;id=17de181feb67447da4e78259d92d0240;version=1.0

+
+: Credential Schema
+:: The data template for a credential. Refers to the entirety of a [=Credential Schema=], including both the [=Metadata=] and [=JSON Schema=]. The term may refer to a document either with, or without a [=proof=].
+
+
+{
+  "type": "https://w3c-ccg.github.io/vc-json-schemas/schema/1.0/schema.json",
+  "modelVersion": "1.0",
+  "id": "did:work:MDP8AsFhHzhwUvGNuYkX7T;id=06e126d1-fa44-4882-a243-1e326fbe21db;version=1.0",
+  "name": "Email",
+  "author": "did:work:MDP8AsFhHzhwUvGNuYkX7T",
+  "authored": "2018-01-01T00:00:00+00:00"
+}
+

+
+: Metadata
+:: Top-level information on a [=Credential Schema=]. Pieces of data wrapping the [=JSON Schema=] to provide further context about the schema.
+
+
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "description": "Email",
+  "type": "object",
+  "properties": {
+    "emailAddress": {
+      "type": "string",
+      "format": "email"
+    }
+  },
+  "required": ["emailAddress"],
+  "additionalProperties": false
+}
+

+
+: proof
+:: A digital signature over the [=Credential Schema=] for the sake of claiming authorship. A piece of [=Metadata=].
+
+: type
+:: It is important in software systems for machines to understand the context of what a document is. In credential schemas this is declared in the type field. This field resolves to a JSON schema with details about the schema metadata that applies to the schema. A piece of [=Metadata=].
+
+: modelVersion
+:: After a machine has parsed the type property it should know that the document it is reading is a [=Credential Schema=]. The next field is the version, which denotes what version of the schema metadata this is. A piece of [=Metadata=].
+
+: schemaVersion
+:: A version that applies to both the [=JSON Schema=] and [=Metadata=]. A piece of [=Metadata=].
+
+: name
+:: A human-readable name for the schema. A piece of [=Metadata=].
+
+: author
+:: [[DID]] of the identity which authored the credential schema. A piece of [=Metadata=].
+
+: authored
+:: [[RFC-3339]] date on which the schema was created. A piece of [=Metadata=].
+
+: JSON Schema
+:: [=schema=]
+
+: schema
+:: This is where the Credential Schema data fields are defined as a valid [[JSON_SCHEMA]]. A piece of [=Metadata=].
+
+
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "description": "Email",
+    "type": "object",
+    "properties": {
+        "emailAddress": {
+            "type": "string",
+            "format": "email"
+        }
+    },
+    "required": ["emailAddress"],
+    "additionalProperties": false
+}
+

+
+: Verifiable Credential
+:: See [[VC_DATA_MODEL]]
+
+# Standards & Compliance # {#standards_compliance}
+
+The [[VC_DATA_MODEL]] specifies the models used for Verifiable Credentials and Verifiable Presentations, and while this spec attempts to align closely to the W3C model, it should NOT be assumed this specification is fully compliant at the time of this writing. Ultimately, we would like to comply with the W3C specification; however, due to the fact that the W3C specification is under active development and is subject to change, we have diverged from that model with several "forks" that are fully outlined in this specification.
+
+# Formatting # {#formatting}
+
+The [[VC_DATA_MODEL]] provides its examples in the JSON Linked Data interchange format. The specification allows for other formats, such as standard JSON with JSON Schema but provides only limited examples. In the [credentialSchema section](https://www.w3.org/TR/vc-data-model/#data-schemas), JSON-SCHEMA-2018 validation is explicitly called out. This specification does not use [[JSON-LD]]. If it becomes evident that it would be useful to include [[JSON-LD]] or another format that decision would be made in a revisal draft at a later date.
+
+The Verifiable Credentials data model relies heavily upon standard JSON with validation provided by [[JSON_SCHEMA]] Draft 7. The data model embeds [[JSON_SCHEMA]] documents inside a larger document that contains useful metadata about a given credential schema.
+
+# Specification # {#specification}
+
+## Overview ## {#overview}
+
+The Credential Schema is a document that is used to guarantee the structure, and by extension the semantics, of the set of claims comprising a Verifiable Credential. A shared Credential Schema allows all parties to reference data in a known way.
+
+A schema can be viewed from four perspectives: the author, issuer, verifier and holder.
+
+Author: An author creates a schema as a blueprint for a verifiable credential, specifying the shape and format of the data in such a credential.
+
+Issuer: Issuers utilize schemas to provide structure and meaning to the data they issue as verifiable credentials. By using schemas, issuers contribute to a credentialing ecosystem, and promote the use and adoption of data standards.
+
+Verifier: A verifier requesting data needs to do so with knowledge of the credential shapes. Credential Schemas allow a Verifier to ask for data knowing that an issuer has issued in an understood way and that a holder's wallet can find data matching that requested.
+
+Holder: Holders, or those who are the subject of credential issuance, can make sense of the data they own -- values -- by viewing it against a schema -- keys. When data is requested from them by referencing a [=Credential Schema=], this known structure allows the holder's wallet to return the data specifically requested by the verifier.
+
+### Guarantees ### {#guarantees}
+
+With adherance to the specification, the following guarantees can be made about a schema:
+
+- A schema is versionable and new versions can evolve it over time
+- A schema is available for any issuer to use and any verifier, or other platform member to read
+- A schema always guarantees the structure of a credential. The described structure can be used by the Verifier to understand what data the Holder holds. There is no requirement for the Verifier to validate sent data against the schema since this sent data may only be partial, for example in event of a proof request only requiring a single field from a credential with multiple fields defined in the schema.
+
+### Storage ### {#storage}
+
+[=Credential Schema=]s are created and made available as immutable objects on a distributed ledger. Among other benefits, this makes tie-in easier with [[DID]] authors.
+
+### Versioning ### {#versioning}
+
+Schemas are versioned in two ways: [=modelVersion=] and [=schemaVersion=] properties. Versioning provides benefits for schema authors, issuers, and verifiers to make sense of their data.
+
+Authors and Issuers care about versioning to track advancements and changes over time both for formatting changes (e.g. supporting [[JSON_SCHEMA]] Draft 7 as opposed to Draft 6) as well as fields as a schema converges to its most currently usable form (e.g. adding a new required field). Holders care about versioning to know where and how their credential can be used. Similarly, Verifiers care about versioning to know which data, or model versions they should accept in their systems.
+
+## Credential Schema Definition ## {#credential_schema_definition}
+
+This section provides the [[JSON_SCHEMA]] definition for [=Credential Schema=] along with an example of a [=Credential Schema=] for an Email [=Verifiable Credential=].
+
+JSON Schema
+
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "type": {
+      "type": "string"
+    },
+    "modelVersion": {
+      "type": "string"
+    },
+    "name": {
+      "type": "string"
+    },
+    "author": {
+      "type": "string"
+    },
+    "authored": {
+      "type": "string"
+    },
+    "schema": {
+      "type": "object",
+      "properties": {
+        "$schema": {
+          "type": "string"
+        },
+        "description": {
+          "type": "string"
+        },
+        "name": {
+          "type": "string"
+        },
+        "type": {
+          "type": "string"
+        },
+        "properties": {
+          "type": "object"
+        },
+        "required": {
+          "type": "array",
+          "items": [
+            {
+              "type": "string"
+            }
+          ]
+        },
+        "additionalProperties": {
+          "type": "boolean"
+        }
+      },
+      "required": [
+        "$schema",
+        "description",
+        "type",
+        "properties",
+        "required",
+        "additionalProperties"
+      ]
+    },
+    "proof": {
+      "type": "object",
+      "properties": {
+        "created": {
+          "type": "string"
+        },
+        "creator": {
+          "type": "string"
+        },
+        "nonce": {
+          "type": "string"
+        },
+        "signatureValue": {
+          "type": "string"
+        },
+        "type": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "created",
+        "creator",
+        "nonce",
+        "signatureValue",
+        "type"
+      ]
+    }
+  },
+  "required": [
+    "type",
+    "modelVersion",
+    "name",
+    "author",
+    "authored",
+    "schema",
+    "proof"
+  ]
+}
+

+
+Example
+
+{
+  "type": "https://w3c-ccg.github.io/vc-json-schemas/schema/1.0/schema.json",
+  "modelVersion": "1.0",
+  "id": "did:work:MDP8AsFhHzhwUvGNuYkX7T;id=06e126d1-fa44-4882-a243-1e326fbe21db;version=1.0",
+  "name": "EmailCredentialSchema",
+  "author": "did:work:MDP8AsFhHzhwUvGNuYkX7T",
+  "authored": "2018-01-01T00:00:00+00:00",
+  "schema": {
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "description": "Email",
+    "type": "object",
+    "properties": {
+      "emailAddress": {
+        "type": "string",
+        "format": "email"
+      }
+    },
+    "required": ["emailAddress"],
+    "additionalProperties": false
+  },
+  "proof": {
+      "created": "2019-09-27T06:26:11Z",
+      "creator": "did:work:MDP8AsFhHzhwUvGNuYkX7T#key-1",
+      "nonce": "0efba23d-2987-4441-998e-23a9d9af79f0",
+      "signatureValue": "2A7ZF9f9TWMdtgn57Y6dP6RQGs52xg2QdjUESZUuf4J9BUnwwWFNL8vFshQAEQF6ZFBXjYLYNU4hzXNKc3R6y6re",
+      "type": "Ed25519VerificationKey2018"
+  }
+}
+

+
+### Metadata ### {#credential_schema_definition_metadata}
+
+The properties, in order, before the JSON Schema document, embedded into the [=JSON Schema=] are as follows:
+
+1. [=type=]
+
+1. [=modelVersion=]
+
+1. [=id=]
+
+1. [=schemaVersion=]
+
+1. [=name=]
+
+1. [=author=]
+
+1. [=authored=]
+
+### Schema ### {#credential_schema_definition_schema}
+
+This is where the [=Credential Schema=] data fields are defined as a valid [=JSON Schema=] document.
+
+
+{
+ "$schema": "http://json-schema.org/draft-07/schema#",
+ "description": "Email",
+ "type": "object",
+ "properties": {
+   "emailAddress": {
+       "type": "string",
+       "format": "email"
+   }
+ },
+ "required": ["emailAddress"],
+ "additionalProperties": false
+}
+

+
+### Proof ### {#credential_schema_definition_proof}
+
+Under construction.
+
+# Versioning Guidelines # {#versioning_guidelines}
+
+This section applies to both [=schemaVersion=] and [=modelVersion=] properties of the metadata.
+
+Versioning is defined as MODEL.REVISION where MODEL is a breaking change and REVISION is non-breaking. The version is contained within the schema identifier.
+
+With schemas we are concerned with a new schema and backwards compatibility of existing data on an older schema.
+
+MODEL Updating this number tells the end user that this version breaks the schema for ANY interaction with an older schema. For verification if a holder presents a credential built from a schema of version 1.0 and the platform is only looking for > 2.0, it is not able to parse ANY information.
+
+REVISION Updating this number tells the end user that this version may prevent interactions with parts of the schema. For verification if a holder presents a credential built from a schema of version 1.0 and the platform is looking for > 1.5, there are likely to be SOME fields incompatible with the expected credential.
+
+## Revision ## {#revision}
+
+The addition or removal of an optional field is what constitutes a REVISION. Adding or removing an optional field does not break historical data in a schema and in the claims exchange protocol fields that are returned negative in the optional field can be ignored as they are optional by default.
+
+
+{
+ "type": "https://w3c-ccg.github.io/vc-json-schemas/schema/1.0/schema.json",
+ "modelVersion": "1.0",
+ "id": "did:work:MDP8AsFhHzhwUvGNuYkX7T;id=06e126d1-fa44-4882-a243-1e326fbe21db;version=1.0",
+ "name": "EmailCredentialSchema",
+ "author": "did:work:MDP8AsFhHzhwUvGNuYkX7T",
+ "authored": "2018-01-01T00:00:00+00:00",
+ "schema": {
+   "$schema": "http://json-schema.org/draft-07/schema#",
+   "description": "Email",
+   "type": "object",
+   "properties": {
+      "emailAddress": {
+      "type": "string",
+      "format": "email"
+    }
+   },
+   "required": ["emailAddress"],
+   "additionalProperties": false
+ }
+}
+

+
+In this example we once again reference the email schema, but this time we add an optional field backupEmailAddress. Notice how this would not break the claims exchange because the field is optional.
+
+
+{
+ "type": "https://w3c-ccg.github.io/vc-json-schemas/schema/1.0/schema.json",
+ "modelVersion": "1.0",
+ "id": "did:work:MDP8AsFhHzhwUvGNuYkX7T;id=06e126d1-fa44-4882-a243-1e326fbe21db;version=1.1",
+ "name": "EmailCredentialSchema",
+ "author": "did:work:abc123",
+ "authored": "2018-01-01T00:00:00+00:00",
+ "schema": {
+   "$schema": "http://json-schema.org/draft-07/schema#",
+   "description": "Email",
+   "type": "object",
+   "properties": {
+    "emailAddress": {
+      "type": "string",
+      "format": "email"
+    },
+    "backupEmailAddress": {
+      "type": "string",
+      "format": "email"
+    }
+   },
+   "required": ["emailAddress"],
+   "additionalProperties": false
+ }
+}
+

+
+## Model ## {#model}
+
+When a schema breaks historical data we call it a model change. This is the major differentiating point between other schema versioning protocols which allow for some breaking changes because as we learned in the problem section, even breaking one area can lead to very difficult issues for verifiers through the credential exchange protocol. The most common case of a MODEL change is the addition or subtraction of a required field. It is also important to note that for the change of a key name on a required field constitutes a MODEL change. Why? Because technically that introduces a breaking change and adds a required field.
+
+An example of this rule is when the additionalProperties field's value changes. Changing additionalProperties from false to true OR from true to false constitutes a breaking change, necessitating a MODEL increment.
+
+
+{
+ "type": "https://w3c-ccg.github.io/vc-json-schemas/schema/1.0/schema.json",
+ "modelVersion": "1.0",
+ "id": "did:work:MDP8AsFhHzhwUvGNuYkX7T;id=06e126d1-fa44-4882-a243-1e326fbe21db;version=1.1",
+ "name": "EmailCredentialSchema",
+ "author": "did:work:MDP8AsFhHzhwUvGNuYkX7T",
+ "authored": "2018-01-01T00:00:00+00:00",
+ "schema": {
+   "$schema": "http://json-schema.org/draft-07/schema#",
+   "description": "Email",
+   "type": "object",
+   "properties": {
+    "emailAddress": {
+      "type": "string",
+      "format": "email"
+    },
+    "backupEmailAddress": {
+      "type": "string",
+      "format": "email"
+    }
+   },
+   "required": ["emailAddress"],
+   "additionalProperties": false
+ }
+}
+

+
+This time our credentialing requirements for email have changed and email address is no longer enough information on a credential, and we need to attach a name for verification as well to our schema. This is a required field, so we know it is a MODEL change.
+
+
+{
+ "type": "https://w3c-ccg.github.io/vc-json-schemas/schema/1.0/schema.json",
+ "modelVersion": "1.0",
+ "id": "did:work:MDP8AsFhHzhwUvGNuYkX7T;id=06e126d1-fa44-4882-a243-1e326fbe21db;version=2.0",
+ "name": "EmailCredentialSchema",
+ "author": "did:work:MDP8AsFhHzhwUvGNuYkX7T",
+ "authored": "2018-01-01T00:00:00+00:00",
+ "schema": {
+   "$schema": "http://json-schema.org/draft-07/schema#",
+   "description": "Email",
+   "type": "object",
+   "properties": {
+    "emailAddress": {
+      "type": "string",
+      "format": "email"
+    },
+    "firstName": {
+      "type": "string"
+    },
+    "backupEmailAddress": {
+      "type": "string",
+      "format": "email"
+    }
+   },
+   "required": ["emailAddress", "firstName"],
+   "additionalProperties": false
+ }
+}
+

+
+# Extensibility # {#extensibility}
+
+By introducing a [=modelVersion=] field we allow the [=credential schema=] to become extensible. Properties such as derivedFrom could reference a schema that a new schema is built on top of. Similarly, platform-utility features such as searchability could be provided by adding a tags array that contains categorization and classification information for a [=schema=].
+
+These are just a few examples that illustrate the flexibility of the proposed model. It can be extended to support a wide variety of use-cases and make the burden on issuance and verification simpler by facilitating the development of higher-level tooling.
+
+# Examples # {#examples}
+
+## Verifiable Credentials ## {#vc_example}
+
+We define an Email schema as the basis for a credential.
+
+
+{
+  "type": "https://w3c-ccg.github.io/vc-json-schemas/schema/1.0/schema.json",
+  "modelVersion": "1.0",
+  "id": "did:work:MDP8AsFhHzhwUvGNuYkX7T;id=06e126d1-fa44-4882-a243-1e326fbe21db;version=1.0",
+  "name": "Email",
+  "author": "did:work:MDP8AsFhHzhwUvGNuYkX7T",
+  "authored": "2018-01-01T00:00:00+00:00"
+}
+

+
+The example references a [=Credential Schema=] with the [=Credential Schema=] identifier did:work:MDP8AsFhHzhwUvGNuYkX7T;id=06e126d1-fa44-4882-a243-1e326fbe21db;version=1.0 inside of a Verifiable Credential following the [[VC_DATA_MODEL]]. The example is adapted from Example 18 in the specification.
+
+
+{
+  "@context": [
+    "https://www.w3.org/2018/credentials/v1",
+    "https://www.w3.org/2018/credentials/examples/v1"
+  ],
+  "id": "http://example.edu/credentials/1872",
+  "type": ["VerifiableCredential", "EmailCredential"],
+  "issuer": "https://example.com/issuers/565049",
+  "issuanceDate": "2010-01-01T19:73:24Z",
+  "credentialSchema": {
+    "id": "did:work:MDP8AsFhHzhwUvGNuYkX7T;id=06e126d1-fa44-4882-a243-1e326fbe21db;version=1.0",
+    "type": "JsonSchemaValidator2018"
+  },
+  "credentialSubject": {
+    "id": "did:work:MDP8AsFhHzhwUvGNuYkX7T",
+    "emailAddress": "first.last@example.com"
+    }
+  },
+  "proof": { ... }
+}
+

+
+The ID of the [=Credential Schema=] is visible in the credentialSchema section of the credential, and describes the shape of the email schema. The type of JsonSchemaValidator2018 refers to a [[JSON-LD]] type providing information on how the data in the credentialSubject should be validated against the provided schema.
+
+# Drawbacks # {#drawbacks}
+
+Within a credentialing ecosystem, relying heavily upon [[JSON Schema]] makes data shapes for credentials consistent, and could enable an ecosystem with many similar schemas with slight changes (naming, capitalization). Without proper oversight or authoritative schemas to limit duplication or misuse, utilization of [[JSON_SCHEMA]] could lead to a poor user experience. At a higher, platform level tooling can be provided to minimize confusion and promote reuse.
+
+Within the broader Credentialing Ecosystem, interoperability could be more difficult if the wider community adopts [[JSON-LD]] without advocating for pairing with [[JSON_SCHEMA]] based schemas or credentials. This issue can mainly be side-stepped with the metadata we include –– the Credential Schema –– since this model is flexible to change. A new [=modelVersion=] could be introduced that supports [[JSON-LD]] and removes support for [[JSON_SCHEMA]]. A drawback here is the requirement that all schemas have this piece of metadata, which itself is versioned and evolvable.
+
+A flip side to drawbacks of the usage of [[JSON_SCHEMA]] is that there is a plethora of documentation, libraries, and usage of [[JSON Schema]] across programming languages and the web.
+
+# Alternatives # {#alternatives}
+
+[[JSON-LD]] is the most prominent alternative, though it has been suggested that both [[JSON Schema]] and [[JSON-LD]] can work symbiotically in the credentialing ecosystem.
+
+# Security & Privacy Considerations # {#security_and_privacy_considerations}
+
+Privacy & security considerations mainly revolve around Personally Identifiable Information (PII) leaks in schemas. Any field which a user could enter data is a potential area for personally identifiable information. When implementing systems that support the storage and querying of schemas relevant data privacy laws and regulations must be taken into account.
+
+# Interoperability # {#interoperability}
+
+The primary concern of this specification is to facilitate an ecosystem in which [=Verifiable Credential=]s can be issued and used. To be interoperable, additional schema types may need to be supported. Given the investment into a robust versioning strategy of our [Credential Schema Metadata](#metadata) interoperability with the current design is less of a concern.
+
+A goal of publishing this document is to promote others to adopt our schema philosophy. It also opens the door for providing feedback and collaborative contribution to developing primitives that would lead to a successful verifiable ecosystem.
+
+
+{
+  "VC_DATA_MODEL": {
+    "href": "https://www.w3.org/TR/vc-data-model/",
+    "title": "Verifiable Credentials Data Model 1.0",
+    "publisher": "W3C"
+  },
+  "RFC-3339": {
+    "href": "https://tools.ietf.org/html/rfc3339",
+    "title": "Date and Time on the Internet: Timestamps",
+    "publisher": "IETF"
+  },
+  "JSON_SCHEMA": {
+    "href": "https://json-schema.org/",
+    "title": "JSON Schema Draft 7",
+    "publisher": "json-schema-org"
+  },
+  "DID": {
+    "href": "https://w3c.github.io/did-core/",
+    "title": "Decentralized Identifiers (DIDs) v1.0",
+    "publisher": "W3C"
+  },
+  "JSON-LD": {
+    "href": "https://w3c.github.io/json-ld-syntax/",
+    "title": "JSON-LD 1.1: A JSON-based Serialization for Linked Data",
+    "publisher": "W3C"
+  }
+}
+

\ No newline at end of file
diff --git a/spec/index.html b/v2/docs/index.html
similarity index 100%
rename from spec/index.html
rename to v2/docs/index.html
diff --git a/spec/index.bs b/v2/spec/index.bs
similarity index 100%
rename from spec/index.bs
rename to v2/spec/index.bs
diff --git a/v2/spec/index.html b/v2/spec/index.html
new file mode 100644
index 0000000..985a474
--- /dev/null
+++ b/v2/spec/index.html
@@ -0,0 +1,1060 @@
+
+ 
+  
+  
+  Verifiable Credentials JSON Schema Specification
+  
+  
+  
+  
+
+
+
+
+
+
+
+  
+ 
+  

+   
 

+   
Verifiable Credentials JSON Schema Specification

+   
Draft Community Group Report, 

+   
+   

+   
Copyright © 2021 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and permissive document license rules apply. 

+   

+  

+  

+   
Abstract

+   
The [VC_DATA_MODEL] specifies the models used for Verifiable Credentials and
+
+  Verifiable Presentations, and explains the relationships between three parties: issuer, holder, and verifier. A critical piece of infrastructure out of the
+  scope of those specifications is the Credential Schema. This specification provides
+  a mechanism to express a Credential Schema and the protocols for evolving the schema.

+  

+  
Status of this document

+  

+   

+  

+  

+  
+  

+   
1. Introduction

+    This specification provides a mechanism for the use of verifiable credentials in a highly scalable, secure, and verifiable way. A large part of the integrity of a verifiable credential is how to structure the credential so that all three parties — issuer, holder, verifier — may have a singular mechanism of trust into what they are using. We call that document a Credential Schema. 
+   
This specification provides a standardized way of creating Credential Schemas to be used in credentialing platforms, how to version them, and how to read them. Credential Schemas may apply to any portion of a Verifiable Credential. Multiple JSON Schemas may back a single Verifiable Credential, e.g. a schema for the credentialSubject and another for other credential properties.

+   
2. Terminology

+   

+    
id
+    

+     
A locally unique identifier to locate the schema on a given data storage medium (e.g. a database, ledger, distributed file store). Each credential schema has its own unique identifier, and each version of a schema is required to have its own unique identifier. 
 
 This identifier is a Uniform Resource Identifier that may contain information pertaining to the author and version of the schema. For example, if the author had a DID like 

+
did:example:abcdefghi

+      a possible schema ID the author created would have an identifier such as: 
+
did:example:abcdefghi;id=17de181feb67447da4e78259d92d0240;version=1.0

+     

+   

+   
Version and authorship may be useful to include in a schema identifier as they provide crucial information about the schema without forcing a lookup. Resovling the schema, however, is the recommended approach to gaining an authoritative information about a schema and its metadata.

+   

+    
Credential Schema
+    

+     
The data template for a credential. Refers to the entirety of a Credential Schema, including both the Metadata and JSON Schema. The term may refer to a document either with, or without a proof.

+   

+
{
+  "type": "https://w3c-ccg.github.io/vc-json-schemas/schema/2.0/schema.json",
+  "version": "1.0",
+  "id": "did:example:MDP8AsFhHzhwUvGNuYkX7T;id=06e126d1-fa44-4882-a243-1e326fbe21db;version=1.0",
+  "name": "Email",
+  "author": "did:example:MDP8AsFhHzhwUvGNuYkX7T",
+  "authored": "2021-01-01T00:00:00+00:00",
+  "schema": {
+    "$id": "email-schema-1.0",
+    "$schema": "https://json-schema.org/draft/2019-09/schema",
+    "description": "Email",
+    "type": "object",
+    "properties": {
+      "emailAddress": {
+        "type": "string",
+        "format": "email"
+      }
+    },
+    "required": ["emailAddress"],
+    "additionalProperties": false
+  }
+}
+

+   

+    
Metadata
+    

+     
Top-level information on a Credential Schema. Pieces of data wrapping the JSON Schema to provide further context about the schema.

+   

+
{
+  "type": "https://w3c-ccg.github.io/vc-json-schemas/schema/2.0/schema.json",
+  "version": "1.0",
+  "id": "did:example:MDP8AsFhHzhwUvGNuYkX7T;id=06e126d1-fa44-4882-a243-1e326fbe21db",
+  "name": "Email",
+  "author": "did:example:MDP8AsFhHzhwUvGNuYkX7T",
+  "authored": "2021-01-01T00:00:00+00:00"
+}
+

+   

+    
proof
+    

+     
A digital signature over the Credential Schema for the sake of claiming authorship. A piece of Metadata. Most often done using [Linked_Data_Proofs].

+    
type
+    

+     
It is important in software systems for machines to understand the context of what a document is. In credential schemas this is declared in the type field. This field resolves to a JSON schema with details about the schema metadata that applies to the schema. A piece of Metadata.

+    
version
+    

+     
Denotes the revision of a given Credential Schema.

+    
name
+    

+     
A human-readable name for the schema. A piece of Metadata.

+    
author
+    

+     
[DID] of the identity which authored the credential schema. A piece of Metadata.

+    
authored
+    

+     
[RFC-3339] date on which the schema was created. A piece of Metadata.

+    
JSON Schema
+    

+     
schema

+    
schema
+    

+     
This is where the Credential Schema data fields are defined as a valid [JSON_SCHEMA]. A piece of Metadata.

+   

+
{
+    "$id": "email-schema-1.0",
+    "$schema": "https://json-schema.org/draft/2019-09/schema",
+    "description": "Email",
+    "type": "object",
+    "properties": {
+        "emailAddress": {
+            "type": "string",
+            "format": "email"
+        }
+    },
+    "required": ["emailAddress"],
+    "additionalProperties": false
+}
+

+   

+    
credential
+    

+     
Verifiable Credential

+    
Verifiable Credential
+    

+     
See [VC_DATA_MODEL]

+   

+   
3. Standards & Compliance

+   
The [VC_DATA_MODEL] specifies the models used for Verifiable Credentials and Verifiable Presentations, and while this spec attempts to align closely to the W3C model, it should NOT be assumed this specification is fully compliant at the time of this writing. Ultimately, we would like to comply with the W3C specification; however, due to the fact that the W3C specification is under active development and is subject to change, we have diverged from that model with several "forks" that are fully outlined in this specification.

+   
4. Formatting

+   
The [VC_DATA_MODEL] provides examples in the JSON Linked Data interchange format. The specification allows for other formats, such as standard JSON with JSON Schema but provides limited examples. In the credentialSchema section, JSON-SCHEMA-2018 validation is noted explicitly. This specification does not use [JSON-LD]. If it becomes evident that it would be useful to include [JSON-LD] or another format that decision would be made in a revisal draft at a later date.

+   
The Verifiable Credentials data model relies heavily upon standard JSON with validation provided by [JSON_SCHEMA]. The data model embeds [JSON_SCHEMA] documents inside a larger document that contains useful metadata about a given credential schema.

+   
5. Specification

+   
5.1. Overview

+   
The Credential Schema is a document that is used to guarantee the structure, and by extension the semantics, of the set of claims comprising a Verifiable Credential. A shared Credential Schema allows all parties to reference data in a known way.

+   
A schema can be viewed from four perspectives: the author, issuer, verifier and holder.

+   
Author: An author creates a schema as a blueprint for a verifiable credential, specifying the shape and format of the data in such a credential.

+   
Issuer: Issuers utilize schemas to provide structure and meaning to the data they issue as verifiable credentials. By using schemas, issuers contribute to a credentialing ecosystem, and promote the use and adoption of data standards.

+   
Verifier: A verifier requesting data needs to do so with knowledge of the credential shapes. Credential Schemas allow a Verifier to request data knowing that an issuer has generated a Credential in a well-known format, and that a holder can accurately respond to such a request.

+   
Holder: Holders, or those who are the subject of credential issuance, can make sense of the data they own – values – by viewing it against a schema—keys. When data is requested from them by referencing a Credential Schema, this known structure allows the holder to return the data specifically requested by the verifier.

+   
5.1.1. Guarantees

+   
With adherance to the specification, the following guarantees can be made about a schema:

+   
    
+    
  • 
+     
    A schema is versionable and it can evolve via new versions over time.
    
+    
  • 
+     
    A schema is available for any issuer to use and any verifier, or other platform member to read.
    
+    
  • 
+     
    A schema always guarantees the structure of a credential. The described structure can be used by the Verifier to understand what data the Holder holds. There is no requirement for the Verifier to validate sent data against the schema since this sent data may only be partial, for example in event of a Presentation Request only requiring a singular field from a credential though there may be multiple fields defined in the schema.
    
+   

+   
5.1.2. Storage

+   
Credential Schemas are created and made available as immutable objects on any number of storage mediums such as a distributed ledger, traditional database, or decentralized file storage. The same schema may be replicated across multiple file stores with the same identifier. Immutability is key to enable consistent sources of truth for credential issuance. Schemas can evolve by creating new versions.

+   
5.1.3. Versioning

+   
Schemas are versioned via a version property. The version denotes the revision of a particular schema for a given storage medium.

+   
Authors and Issuers care about versioning to track advancements and changes over time both for formatting changes (e.g. supporting [JSON_SCHEMA] draft-bhutton-json-schema-00 as opposed to Draft 7) as well as field changes (e.g. adding a new required field) as a schema evolves to its latest form. Holders care about versioning to know where and how their credential can be used. Similarly, Verifiers care about versioning to know which data, or schema versions they should accept in their systems.

+   
Gudelines for versioning can be found in the Versioning Guidelines section of this document.

+   
5.1.4. Processing

+   
There is wide support for JSON Schema processing and [JSON_SCHEMA_IMPLMENTATIONS] can be found in many programming languages.

+   
5.1.4.1. Acceptance

+   
A system may choose to accept schemas based on multiple different criteria: storage location, authorship, identifier, version, etc.

+   
The language by which a schema, or set of schemas are accepted by Credentialing Systems is out of scope of this document. It is advisable that such a language is flexible to accomodate important criterion of a schema, such as supporting version ranges with a common property, or enforcing authorship from a known author with a valid authentication mechanism (i.e. proof).

+   
5.1.4.2. Validation

+   
What determines the validity of a Credential is up to the verifier for that given Credential. Validity could mean a a valid proof, a valid proof and validation against a given schema, or other set of conditions.

+   
Validation of a given Credential against its schema is to be performed according to the [JSON_SCHEMA_VALIDATION] specification.

+   
5.2. Credential Schema Definition

+   
This section provides the [JSON_SCHEMA] definition for Credential Schema along with an example of a Credential Schema for an Email Verifiable Credential.

+   
JSON Schema

+
{
+  "$id": "credential-schema-2.0",
+  "$schema": "https://json-schema.org/draft/2019-09/schema",
+  "description": "JSON Schema for W3C Verifiable Credential JSON Schema",
+  "type": "object",
+  "properties": {
+    "type": {
+      "type": "string"
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+$"
+    },
+    "id": {
+      "type": "string"
+    },
+    "name": {
+      "type": "string"
+    },
+    "author": {
+      "type": "string"
+    },
+    "authored": {
+      "type": "string"
+    },
+    "schema": {
+      "type": "object",
+      "properties": {
+        "$id": {
+          "type": "string"
+        },
+        "$schema": {
+          "type": "string"
+        },
+        "description": {
+          "type": "string"
+        },
+        "name": {
+          "type": "string"
+        },
+        "type": {
+          "type": "string"
+        },
+        "properties": {
+          "type": "object"
+        },
+        "required": {
+          "type": "array",
+          "items": [
+            {
+              "type": "string"
+            }
+          ]
+        },
+        "additionalProperties": {
+          "type": "boolean"
+        }
+      },
+      "required": [
+        "$id",
+        "$schema",
+        "description",
+        "type",
+        "properties",
+        "required",
+        "additionalProperties"
+      ]
+    },
+    "proof": {
+      "type": "object"
+    }
+  },
+  "required": [
+    "type",
+    "version",
+    "id",
+    "name",
+    "author",
+    "authored",
+    "schema"
+  ]
+}
+

+   
5.2.1. Metadata

+   
The properties, in order, before the JSON Schema document, embedded into the JSON Schema are as follows:

+   
    
+    
  1. 
+     
    type
    
+    
  2. 
+     
    version
    
+    
  3. 
+     
    id
    
+    
  4. 
+     
    name
    
+    
  5. 
+     
    author
    
+    
  6. 
+     
    authored
    
+   

+
{
+  "type": "https://w3c-ccg.github.io/vc-json-schemas/schema/2.0/schema.json",
+  "version": "1.0",
+  "id": "06e126d1-fa44-4882-a243-1e326fbe21db",
+  "name": "Email",
+  "author": "did:example:MDP8AsFhHzhwUvGNuYkX7T",
+  "authored": "2021-01-01T00:00:00+00:00"
+}
+

+   
5.2.2. Schema

+   
This is where the Credential Schema data fields are defined as a valid JSON Schema document.

+
{
+ "$schema": "https://json-schema.org/draft/2019-09/schema",
+ "description": "Email",
+ "type": "object",
+ "properties": {
+   "emailAddress": {
+       "type": "string",
+       "format": "email"
+   }
+ },
+ "required": ["emailAddress"],
+ "additionalProperties": false
+}
+

+   
5.2.3. Proof

+   
Any Credential Schema may be authenticated using [Linked_Data_Proofs].

+
Example and more detail needed.
+

+   
6. Versioning Guidelines

+   
This section applies to version properties of the metadata.

+   
Versioning is defined as MODEL.REVISION where MODEL is a breaking change and REVISION is non-breaking. The version is contained within the schema identifier.

+   
With schemas we are concerned with a new schema and backwards compatibility of existing data on an older schema.

+   
MODEL Updating this number tells the end user that this version breaks the schema for ANY interaction with an older schema. For processing, if a holder presents a credential built from a schema with version 1.0, and the platform is looking for version 2.0, it is not able to parse ANY information.

+   
REVISION Updating this number tells the end user that this version may prevent interactions with parts of the schema. For processing, if a holder presents a credential built from a schema with version 1.0 and the platform is looking for version 1.5, there are likely to be SOME fields incompatible with the expected credential.

+   
6.1. Revision

+   
The addition or removal of an optional field is what constitutes a REVISION. Adding or removing an optional field does not break historical data in a schema, and in a claims exchange protocol, missing optional fields can be ignored.

+
{
+ "type": "https://w3c-ccg.github.io/vc-json-schemas/schema/2.0/schema.json",
+ "version": "1.0",
+ "id": "did:example:MDP8AsFhHzhwUvGNuYkX7T;id=06e126d1-fa44-4882-a243-1e326fbe21db;version=1.0",
+ "name": "Email",
+ "author": "did:example:MDP8AsFhHzhwUvGNuYkX7T",
+ "authored": "2018-01-01T00:00:00+00:00",
+ "schema": {
+   "$id": "email-schema-1.0",
+   "$schema": "https://json-schema.org/draft/2019-09/schema",
+   "description": "Email",
+   "type": "object",
+   "properties": {
+      "emailAddress": {
+      "type": "string",
+      "format": "email"
+    }
+   },
+   "required": ["emailAddress"],
+   "additionalProperties": false
+ }
+}
+

+   
In this example we once again reference the email schema, but this time we add an optional field backupEmailAddress. Notice how this would not break the claims exchange because the field is optional.

+
{
+ "type": "https://w3c-ccg.github.io/vc-json-schemas/schema/2.0/schema.json",
+ "version": "1.1",
+ "id": "did:example:MDP8AsFhHzhwUvGNuYkX7T;id=06e126d1-fa44-4882-a243-1e326fbe21db;version=1.1",
+ "name": "Email",
+ "author": "did:example:abc123",
+ "authored": "2018-01-01T00:00:00+00:00",
+ "schema": {
+   "$id": "email-schema-1.1",
+   "$schema": "https://json-schema.org/draft/2019-09/schema",
+   "description": "Email",
+   "type": "object",
+   "properties": {
+    "emailAddress": {
+      "type": "string",
+      "format": "email"
+    },
+    "backupEmailAddress": {
+      "type": "string",
+      "format": "email"
+    }
+   },
+   "required": ["emailAddress"],
+   "additionalProperties": false
+ }
+}
+

+   
6.2. Model

+   
When a schema breaks backwards compatiblity it is considered a model change. The most common case of a MODEL change is the addition or subtraction of a required field. It is important to note that for the change of a key name on a required field constitutes a MODEL change as this introduces a breaking change, adding a required field.

+   
An example of this rule is when the additionalProperties field’s value changes. Changing additionalProperties from false to true OR from true to false constitutes a breaking change, necessitating a MODEL increment.

+
{
+ "type": "https://w3c-ccg.github.io/vc-json-schemas/schema/2.0/schema.json",
+ "version": "1.1",
+ "id": "did:example:MDP8AsFhHzhwUvGNuYkX7T;id=06e126d1-fa44-4882-a243-1e326fbe21db;version=1.1",
+ "name": "Email",
+ "author": "did:example:MDP8AsFhHzhwUvGNuYkX7T",
+ "authored": "2018-01-01T00:00:00+00:00",
+ "schema": {
+   "$id": "email-schema-1.1",
+   "$schema": "https://json-schema.org/draft/2019-09/schema",
+   "description": "Email",
+   "type": "object",
+   "properties": {
+    "emailAddress": {
+      "type": "string",
+      "format": "email"
+    },
+    "backupEmailAddress": {
+      "type": "string",
+      "format": "email"
+    }
+   },
+   "required": ["emailAddress"],
+   "additionalProperties": false
+ }
+}
+

+   
This time our credentialing requirements for our email schema have changed and we need to attach a firstName for verification. This is a required field, so we know it is a MODEL change.

+
{
+ "type": "https://w3c-ccg.github.io/vc-json-schemas/schema/2.0/schema.json",
+ "version": "2.0",
+ "id": "did:example:MDP8AsFhHzhwUvGNuYkX7T;id=06e126d1-fa44-4882-a243-1e326fbe21db;version=2.0",
+ "name": "Email",
+ "author": "did:example:MDP8AsFhHzhwUvGNuYkX7T",
+ "authored": "2018-01-01T00:00:00+00:00",
+ "schema": {
+   "$id": "email-schema-2.0",
+   "$schema": "https://json-schema.org/draft/2019-09/schema",
+   "description": "Email",
+   "type": "object",
+   "properties": {
+    "emailAddress": {
+      "type": "string",
+      "format": "email"
+    },
+    "firstName": {
+      "type": "string"
+    },
+    "backupEmailAddress": {
+      "type": "string",
+      "format": "email"
+    }
+   },
+   "required": ["emailAddress", "firstName"],
+   "additionalProperties": false
+ }
+}
+

+   
7. Extensibility

+   
By introducing a version field we allow the credential schema to become extensible. Properties such as derivedFrom could reference a schema that a new schema is built on top of. Similarly, platform-utility features such as searchability could be provided by adding a tags array that contains categorization and classification information for a schema.

+   
These are just a few examples that illustrate the flexibility of the proposed model. It can be extended to support a wide variety of use-cases and make the burden on issuance and verification simpler by facilitating the development of higher-level tooling.

+   
8. Examples

+   
8.1. Verifiable Credentials

+   
We define an Email schema as the basis for a credential.

+
{
+  "type": "https://w3c-ccg.github.io/vc-json-schemas/schema/2.0/schema.json",
+  "version": "1.0",
+  "id": "did:example:MDP8AsFhHzhwUvGNuYkX7T;id=06e126d1-fa44-4882-a243-1e326fbe21db;version=1.0",
+  "name": "Email",
+  "author": "did:example:MDP8AsFhHzhwUvGNuYkX7T",
+  "authored": "2021-01-01T00:00:00+00:00",
+  "schema": {
+    "$id": "email-schema-1.0",
+    "$schema": "https://json-schema.org/draft/2019-09/schema",
+    "description": "Email",
+    "type": "object",
+    "properties": {
+      "emailAddress": {
+        "type": "string",
+        "format": "email"
+      }
+    },
+    "required": ["emailAddress"],
+    "additionalProperties": false
+  }
+}
+

+   
The example references a Credential Schema with an identifier did:example:MDP8AsFhHzhwUvGNuYkX7T;id=06e126d1-fa44-4882-a243-1e326fbe21db;version=1.0 inside of a Verifiable Credential following the [VC_DATA_MODEL]. The example is adapted from Example 18 in the specification.

+
{
+  "@context": [
+    "https://www.w3.org/2018/credentials/v1",
+    "https://www.w3.org/2018/credentials/examples/v1"
+  ],
+  "id": "http://example.edu/credentials/1872",
+  "type": ["VerifiableCredential", "EmailCredential"],
+  "issuer": "https://example.com/issuers/565049",
+  "issuanceDate": "2021-01-01T00:00:00Z",
+  "credentialSchema": {
+    "id": "did:example:MDP8AsFhHzhwUvGNuYkX7T;id=06e126d1-fa44-4882-a243-1e326fbe21db;version=1.0",
+    "type": "JsonSchemaValidator2018"
+  },
+  "credentialSubject": {
+    "id": "did:example:MDP8AsFhHzhwUvGNuYkX7T",
+    "emailAddress": "first.last@example.com"
+    }
+  },
+  "proof": { ... }
+}
+

+   
The ID of the Credential Schema is visible in the credentialSchema section of the credential, and provides information about the schema’s author and version. The type of JsonSchemaValidator2018 refers to a [JSON-LD] type providing information on how the data in the credentialSubject should be validated against the provided schema.

+   
9. Drawbacks

+   
Within a credentialing ecosystem, relying heavily upon [JSON_SCHEMA] makes data shapes for credentials consistent, and could enable an ecosystem with many similar schemas with slight changes (naming, capitalization). Without proper oversight or authoritative schemas to limit duplication or misuse, utilization of [JSON_SCHEMA] could lead to a poor user experience. At a higher, platform level tooling can be provided to minimize confusion and promote reuse.

+   
Within the broader Credentialing Ecosystem, interoperability could be more difficult if the wider community adopts [JSON-LD] without advocating for pairing with [JSON_SCHEMA] based schemas or credentials. This issue can mainly be side-stepped with the metadata we include –– the Credential Schema –– since this model is flexible to change. A new version could be introduced that supports [JSON-LD] and removes support for [JSON_SCHEMA]. A drawback here is the requirement that all schemas have this piece of metadata, which itself is versioned and evolvable.

+   
A flip side to drawbacks of the usage of [JSON_SCHEMA] is that there is a plethora of documentation, libraries, and usage of [JSON_SCHEMA] across programming languages and the web.

+   
10. Alternatives

+   
[JSON-LD] is the most prominent alternative, though it does not provide the same functionality in regards to strict data validation. It has been suggested that both [JSON_SCHEMA] and [JSON-LD] can work symbiotically in the credentialing ecosystem: [JSON-LD] providing semantic interoparability, and [JSON_SCHEMA] providing static validation.

+   
11. Security & Privacy Considerations

+   
Privacy & security considerations mainly revolve around Personally Identifiable Information (PII) leaks in schemas. Any field which a user could enter data is a potential area for personally identifiable information. When implementing systems that support the storage and querying of schemas relevant data privacy laws and regulations must be taken into account.

+   
12. Interoperability

+   
The primary concern of this specification is to facilitate an ecosystem in which Verifiable Credentials can be issued and used. To be interoperable, additional schema types may need to be supported. Given the investment into a robust versioning strategy of Credential Schema Metadata interoperability with the current design is less of a concern.

+   
A goal of publishing this document is to promote others to adopt this schema philosophy. It also opens the door for providing feedback and collaborative contribution to developing primitives that would lead to a successful verifiable ecosystem.

+  

+
+  
Index

+  
Terms defined by this specification

+  
+  
References

+  
Informative References

+  

+   
[DID]
+   
Decentralized Identifiers (DIDs) v1.0. URL: https://w3c.github.io/did-core/
+   
[JSON-LD]
+   
JSON-LD 1.1: A JSON-based Serialization for Linked Data. URL: https://w3c.github.io/json-ld-syntax/
+   
[JSON_SCHEMA]
+   
JSON Schema Bhutton Draft 00. URL: https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-00
+   
[JSON_SCHEMA_IMPLMENTATIONS]
+   
JSON Schema Implementations. URL: https://json-schema.org/implementations.html
+   
[JSON_SCHEMA_VALIDATION]
+   
JSON Schema Validation: A Vocabulary for Structural Validation of JSON draft-bhutton-json-schema-validation-00. URL: https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-validation-00
+   
[Linked_Data_Proofs]
+   
Linked Data Proofs 1.0. URL: https://w3c-ccg.github.io/ld-proofs/
+   
[RFC-3339]
+   
Date and Time on the Internet: Timestamps. URL: https://tools.ietf.org/html/rfc3339
+   
[VC_DATA_MODEL]
+   
Verifiable Credentials Data Model 1.0. URL: https://www.w3.org/TR/vc-data-model/
+  

+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+
\ No newline at end of file