├── .pr-preview.json
├── w3c.json
├── LICENSE.md
├── README.md
├── common.js
└── index.html


/.pr-preview.json:
--------------------------------------------------------------------------------
1 | {
2 |     "src_file": "index.html",
3 |     "type": "respec"
4 |     }
5 | 


--------------------------------------------------------------------------------
/w3c.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "group": [
 3 |     "98922"
 4 |   ],
 5 |   "contacts": [
 6 |     "ashimura"
 7 |   ],
 8 |   "shortName": "vc-imp-guide",
 9 |   "repo-type": "note"
10 | }
11 | 


--------------------------------------------------------------------------------
/LICENSE.md:
--------------------------------------------------------------------------------
1 | All documents in this Repository are licensed by contributors
2 | under the 
3 | [W3C Software and Document License](https://www.w3.org/Consortium/Legal/copyright-software).
4 | 
5 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # W3C Verifiable Claims Working Group - Verifiable Credentials Implementation Guideline 1.0
2 | 
3 | [HTML rendered version](https://w3c.github.io/vc-imp-guide/)
4 | 
5 | ### Other Verifiable Claims github repos
6 | * [Data Model](https://github.com/w3c/vc-data-model)
7 | * [Test Suite](https://github.com/w3c/vc-test-suite)
8 | * [Use Cases](https://github.com/w3c/vc-use-cases)
9 | 


--------------------------------------------------------------------------------
/common.js:
--------------------------------------------------------------------------------
  1 | /* globals omitTerms, respecConfig, $, require */
  2 | /* exported linkCrossReferences, restrictReferences, fixIncludes */
  3 | 
  4 | var vcwg = {
  5 |   // Add as the respecConfig localBiblio variable
  6 |   // Extend or override global respec references
  7 |   localBiblio: {
  8 |     "REST": {
  9 |       title: "Architectural Styles and the Design of Network-based Software Architectures",
 10 |       date: "2000",
 11 |       href: "http://www.ics.uci.edu/~fielding/pubs/dissertation/",
 12 |       authors: [
 13 |         "Fielding, Roy Thomas"
 14 |       ],
 15 |       publisher: "University of California, Irvine."
 16 |     },
 17 |     "VC-USECASES": {
 18 |       title: "Verifiable Claims Use Cases",
 19 |       href: "https://www.w3.org/TR/verifiable-claims-use-cases/",
 20 |       authors: [
 21 |       	"Shane McCarron",
 22 |         "Daniel Burnett",
 23 |         "Gregg Kellogg",
 24 |         "Brian Sletten",
 25 |         "Manu Sporny"
 26 |       ],
 27 |       status: "FPWD",
 28 |       publisher: "Verifiable Claims Working Group"
 29 |     },
 30 |     "VC-STATUS-REGISTRY": {
 31 |       title: "Verifiable Credentials Status Scheme Registry",
 32 |       href: "https://w3c-ccg.github.io/vc-status-registry/",
 33 |       authors: [
 34 |         "Manu Sporny"
 35 |       ],
 36 |       status: "CG-DRAFT",
 37 |       publisher: "Credentials Community Group"
 38 |     },
 39 |     "LD-PROOFS": {
 40 |       title: "Linked Data Proofs",
 41 |       href: "https://w3c-dvcg.github.io/ld-proofs/",
 42 |       authors: [
 43 |         "Manu Sporny",
 44 |         "Dave Longley"
 45 |       ],
 46 |       status: "CG-DRAFT",
 47 |       publisher: "Digital Verification Community Group"
 48 |     },
 49 |     "LD-SIGNATURES": {
 50 |       title: "Linked Data Signatures",
 51 |       href: "https://w3c-dvcg.github.io/ld-signatures/",
 52 |       authors: [
 53 |         "Manu Sporny",
 54 |         "Dave Longley"
 55 |       ],
 56 |       status: "CG-DRAFT",
 57 |       publisher: "Digital Verification Community Group"
 58 |     },
 59 |     // aliases to known references
 60 |     "HTTP-SIGNATURES": {
 61 |       aliasOf: "http-signatures"
 62 |     },
 63 |     "MACAROONS": {
 64 |       title: 'Macaroons',
 65 |       // TODO: create spec
 66 |       href: 'http://macaroons.io/',
 67 |       authors: ['Arnar Birgisson', 'Joe Gibbs Politz', 'Úlfar Erlingsson',
 68 |         'Ankur Taly', 'Michael Vrable', 'Mark Lentczner'],
 69 |       status: 'unofficial',
 70 |       publisher: 'Credentials Community Group'
 71 |     },
 72 |     'OPEN-BADGES': {
 73 |       title: 'Open Badges',
 74 |       href: 'https://github.com/openbadges/openbadges-specification',
 75 |       authors: ['Brian Brennan', 'Mike Larsson', 'Chris McAvoy',
 76 |         'Nate Otto', 'Kerri Lemoie'],
 77 |       status:   'BA-DRAFT',
 78 |       publisher:  'Badge Alliance Standard Working Group'
 79 |     },
 80 |     'RDF-NORMALIZATION': {
 81 |       title: 'RDF Dataset Normalization',
 82 |       href: 'http://json-ld.github.io/normalization/spec/',
 83 |       authors: ['Dave Longley', 'Manu Sporny'],
 84 |       status:   'CG-DRAFT',
 85 |       publisher:  'Credentials W3C Community Group'
 86 |     },
 87 |     'DEMOGRAPHICS': {
 88 |       title: 'Simple Demographics Often Identify People Uniquely',
 89 |       href: 'http://dataprivacylab.org/projects/identifiability/paper1.pdf',
 90 |       authors: ['Latanya Sweeney'],
 91 |       publisher: 'Data Privacy Lab'
 92 |     }
 93 |   }
 94 | };
 95 | 
 96 | 
 97 | 
 98 | // We should be able to remove terms that are not actually
 99 | // referenced from the common definitions
100 | //
101 | // the termlist is in a block of class "termlist", so make sure that
102 | // has an ID and put that ID into the termLists array so we can
103 | // interrogate all of the included termlists later.
104 | var termNames = [] ;
105 | var termLists = [] ;
106 | var termsReferencedByTerms = [] ;
107 | 
108 | function restrictReferences(utils, content) {
109 |     "use strict";
110 |     var base = document.createElement("div");
111 |     base.innerHTML = content;
112 | 
113 |     // New new logic:
114 |     //
115 |     // 1. build a list of all term-internal references
116 |     // 2. When ready to process, for each reference INTO the terms,
117 |     // remove any terms they reference from the termNames array too.
118 |     $.each(base.querySelectorAll("dfn"), function(i, item) {
119 |         var $t = $(item) ;
120 |         var titles = $t.getDfnTitles();
121 |         var dropit = false;
122 |         // do we have an omitTerms
123 |         if (window.hasOwnProperty("omitTerms")) {
124 |             // search for a match
125 |             $.each(omitTerms, function(j, term) {
126 |                 if (titles.indexOf(term) !== -1) {
127 |                     dropit = true;
128 |                 }
129 |             });
130 |         }
131 |         // do we have an includeTerms
132 |         if (window.hasOwnProperty("includeTerms")) {
133 |             var found = false;
134 |             // search for a match
135 |             $.each(includeTerms, function(j, term) {
136 |                 if (titles.indexOf(term) !== -1) {
137 |                     found = true;
138 |                 }
139 |             });
140 |             if (!found) {
141 |                 dropit = true;
142 |             }
143 |         }
144 |         if (dropit) {
145 |             $t.parent().next().remove();
146 |             $t.parent().remove();
147 |         } else {
148 |             var n = $t.makeID("dfn", titles[0]);
149 |             if (n) {
150 |                 termNames[n] = $t.parent() ;
151 |             }
152 |         }
153 |     });
154 | 
155 |     var $container = $(".termlist",base) ;
156 |     var containerID = $container.makeID("", "terms") ;
157 |     termLists.push(containerID) ;
158 | 
159 |     return (base.innerHTML);
160 | }
161 | // add a handler to come in after all the definitions are resolved
162 | //
163 | // New logic: If the reference is within a 'dl' element of
164 | // class 'termlist', and if the target of that reference is
165 | // also within a 'dl' element of class 'termlist', then
166 | // consider it an internal reference and ignore it.
167 | 
168 | require(["core/pubsubhub"], function(respecEvents) {
169 |     "use strict";
170 |     respecEvents.sub('end', function(message) {
171 |         if (message === 'core/link-to-dfn') {
172 |             // all definitions are linked; find any internal references
173 |             $(".termlist a.internalDFN").each(function() {
174 |                 var $r = $(this);
175 |                 var id = $r.attr('href');
176 |                 var idref = id.replace(/^#/,"") ;
177 |                 if (termNames[idref]) {
178 |                     // this is a reference to another term
179 |                     // what is the idref of THIS term?
180 |                     var $def = $r.closest('dd') ;
181 |                     if ($def.length) {
182 |                         var $p = $def.prev('dt').find('dfn') ;
183 |                         var tid = $p.attr('id') ;
184 |                         if (tid) {
185 |                             if (termsReferencedByTerms[tid]) {
186 |                                 termsReferencedByTerms[tid].push(idref);
187 |                             } else {
188 |                                 termsReferencedByTerms[tid] = [] ;
189 |                                 termsReferencedByTerms[tid].push(idref);
190 |                             }
191 |                         }
192 |                     }
193 |                 }
194 |             }) ;
195 | 
196 |             // clearRefs is recursive.  Walk down the tree of
197 |             // references to ensure that all references are resolved.
198 |             var clearRefs = function(theTerm) {
199 |                 if ( termsReferencedByTerms[theTerm] ) {
200 |                     $.each(termsReferencedByTerms[theTerm], function(i, item) {
201 |                         if (termNames[item]) {
202 |                             delete termNames[item];
203 |                             clearRefs(item);
204 |                         }
205 |                     });
206 |                 }
207 |                 // make sure this term doesn't get removed
208 |                 if (termNames[theTerm]) {
209 |                     delete termNames[theTerm];
210 |                 }
211 |             };
212 | 
213 |             // now termsReferencedByTerms has ALL terms that
214 |             // reference other terms, and a list of the
215 |             // terms that they reference
216 |             $("a.internalDFN").each(function () {
217 |                 var $item = $(this) ;
218 |                 var t = $item.attr('href');
219 |                 var r = t.replace(/^#/,"") ;
220 |                 // if the item is outside the term list
221 |                 if ( ! $item.closest('dl.termlist').length ) {
222 |                     clearRefs(r);
223 |                 }
224 |             });
225 | 
226 |             // delete any terms that were not referenced.
227 |             /*
228 |             Object.keys(termNames).forEach(function(term) {
229 |                 var $p = $("#"+term) ;
230 |                 if ($p) {
231 |                     var tList = $p.getDfnTitles();
232 |                     $p.parent().next().remove();
233 |                     $p.parent().remove() ;
234 |                     tList.forEach(function( item ) {
235 |                       console.log("CHECKING ITEM", item, respecConfig);
236 |                         if (respecConfig.definitionMap[item]) {
237 |                             delete respecConfig.definitionMap[item];
238 |                         }
239 |                     });
240 |                 }
241 |             });*/
242 |         }
243 |     });
244 | });
245 | 


--------------------------------------------------------------------------------
/index.html:
--------------------------------------------------------------------------------
   1 | <!DOCTYPE html>
   2 | <html>
   3 |   <head>
   4 |     <title>Verifiable Credentials Implementation Guidelines 1.0</title>
   5 |     <meta http-equiv='Content-Type' content='text/html;charset=utf-8'/>
   6 |     <!--
   7 |       === NOTA BENE ===
   8 |       For the three scripts below, if your spec resides on dev.w3 you can check them
   9 |       out in the same tree and use relative links so that they'll work offline,
  10 |      -->
  11 |     <script src='https://www.w3.org/Tools/respec/respec-w3c-common' class='remove'></script>
  12 |     <script src="./common.js" class="remove"></script>
  13 |     <script type="text/javascript" class="remove">
  14 |       var respecConfig = {
  15 |         // specification status (e.g. WD, LCWD, NOTE, etc.). If in doubt use ED.
  16 |         specStatus: "ED",
  17 | 
  18 |         // the specification's short name, as in http://www.w3.org/TR/short-name/
  19 |         shortName: "vc-imp-guide",
  20 | 
  21 |         // subtitle for the spec
  22 |         subtitle: "Implementation guidance for Verifiable Credentials",
  23 | 
  24 |         // if you wish the publication date to be other than today, set this
  25 |         //publishDate:  "2017-08-03",
  26 | 
  27 |         // if there is a previously published draft, uncomment this and set its YYYY-MM-DD date
  28 |         // and its maturity status
  29 |         // previousPublishDate:  "1977-03-15",
  30 |         // previousMaturity:  "WD",
  31 | 
  32 |         // extend the bibliography entries
  33 |         localBiblio: vcwg.localBiblio,
  34 |         doJsonLd: true,
  35 | 
  36 |         github: "https://github.com/w3c/vc-imp-guide",
  37 |         includePermalinks: false,
  38 | 
  39 |         // if there a publicly available Editor's Draft, this is the link
  40 |         edDraftURI: "https://w3c.github.io/vc-imp-guide/",
  41 | 
  42 |         // if this is a LCWD, uncomment and set the end of its review period
  43 |         // lcEnd: "2009-08-05",
  44 | 
  45 |         // editors, add as many as you like
  46 |         // only "name" is required
  47 |         editors:  [{ name: "Andrei Sambra", url: "https://deiu.me/"}],
  48 | 
  49 |         // authors, add as many as you like.
  50 |         // This is optional, uncomment if you have authors as well as editors.
  51 |         // only "name" is required. Same format as editors.
  52 |         authors: [{
  53 |           name: "Manu Sporny", url: "http://manu.sporny.org/",
  54 |           company: "Digital Bazaar", companyURL: "http://digitalbazaar.com/"
  55 |         }],
  56 | 
  57 |         // name of the WG
  58 |         wg:           "Verifiable Claims Working Group",
  59 | 
  60 |         // URI of the public WG page
  61 |         wgURI:        "https://www.w3.org/2017/vc/",
  62 | 
  63 |         // name (with the @w3c.org) of the public mailing to which comments are due
  64 |         wgPublicList: "public-vc-comments",
  65 | 
  66 |         // URI of the patent status for this WG, for Rec-track documents
  67 |         // !!!! IMPORTANT !!!!
  68 |         // This is important for Rec-track documents, do not copy a patent URI from a random
  69 |         // document unless you know what you're doing. If in doubt ask your friendly neighbourhood
  70 |         // Team Contact.
  71 |         wgPatentURI:  "https://www.w3.org/2004/01/pp-impl/98922/status",
  72 |         maxTocLevel: 4,
  73 |         inlineCSS: true
  74 |       };
  75 |     </script>
  76 |     <style>
  77 | pre .highlight {
  78 |   font-weight: bold;
  79 |   color: green;
  80 | }
  81 | pre .subject {
  82 |   font-weight: bold;
  83 |   color: RoyalBlue;
  84 | }
  85 | pre .property {
  86 |   font-weight: bold;
  87 |   color: DarkGoldenrod;
  88 | }
  89 | pre .comment {
  90 |   font-weight: bold;
  91 |   color: SteelBlue;
  92 |   -webkit-user-select: none;
  93 |   -moz-user-select: none;
  94 |   -ms-user-select: none;
  95 |   user-select: none;
  96 | }
  97 | .supported {
  98 |   background-color: #93c47d;
  99 | }
 100 | .missing {
 101 |   background-color: #e06666;
 102 | }
 103 | </style>
 104 |   </head>
 105 |   <body>
 106 |     <section id='abstract'>
 107 |       <p>
 108 | This document provides implementation guidance for Verifiable Credentials.
 109 |       </p>
 110 |     </section>
 111 | 
 112 |     <section id='sotd'>
 113 |       <p>
 114 | Comments regarding this document are welcome. Please file issues
 115 | directly on <a href="https://github.com/w3c/vc-data-model/issues/">GitHub</a>,
 116 | or send them to
 117 | <a href="mailto:public-vc-comments@w3.org">public-vc-comments@w3.org</a>
 118 | (<a href="mailto:public-vc-comments-request@w3.org?subject=subscribe">subscribe</a>,
 119 | <a href="https://lists.w3.org/Archives/Public/public-vc-comments/">archives</a>).
 120 |       </p>
 121 |     </section>
 122 | 
 123 |     <section>
 124 |       <h2>Introduction</h2>
 125 |       <em>This section is non-normative.</em>
 126 | 
 127 |       <p>
 128 | This guide provides some examples and resources for implementing
 129 | protocols which make use of <a>verifiable credentials</a>, beyond those available in the core specification.
 130 |       </p>
 131 |       <p>
 132 | It may be useful to first familiarize yourself with the official
 133 | <a href="https://www.w3.org/TR/verifiable-claims-use-cases/">Use Cases document</a>,
 134 | which offers a concise collection of examples of <a>Verifiable Credentials</a>
 135 | as they may appear in everyday life, and how they may be used.
 136 |       </p>
 137 |       <p>
 138 | The <a href="https://www.w3.org/TR/vc-data-model/">data model specification</a>
 139 | contains the technical details about <a>verifiable credentials</a>. However, the
 140 | data model specification does not specify any <em>protocols</em> for using
 141 | <a>verifiable credentials</a>, nor any <em>proof formats</em> or additional
 142 | <em>identifiers</em> upon which such protocols may depend.
 143 |       </p>
 144 |     </section>
 145 | 
 146 |     <section>
 147 |       <h2>Identifiers</h2>
 148 |       <em>This section is non-normative.</em>
 149 |       <p>
 150 | When expressing statements about a specific entity, such as a person, product,
 151 | or organization, it is often useful to have an identifier for it so that others
 152 | can express statements about the same thing. The <a>verifiable credentials</a>
 153 | <a href="https://www.w3.org/TR/vc-data-model//">data model specification</a>
 154 | contains numerous examples where the identifier is a
 155 | <a href="https://w3c-ccg.github.io/did-primer/">decentralized identifier</a>,
 156 | also known as a DID. An example of a DID is <code>did:example:123456abcdef</code>.
 157 |       </p>
 158 |       <p>
 159 | There is currently a proposed charter for a W3C <a href="https://w3c-ccg.github.io/did-wg-charter/">
 160 | Decentralized Identifier Working Group</a>, which will put DIDs on track to
 161 | become a W3C standard.
 162 |       </p>
 163 |       <p class="note">
 164 | As of the publication of the <a>verifiable credentials</a>
 165 | <a href="https://www.w3.org/TR/vc-data-model/">data model specification</a>,
 166 | DIDs are not necessary for <a>verifiable credentials</a> to be useful.
 167 | Specifically, <a>verifiable credentials</a> do not depend on <a>DIDs</a> and
 168 | <a>DIDs</a> do not depend on <a>verifiable credentials</a>. However, it is
 169 | expected that many <a>verifiable credentials</a> will use <a>DIDs</a> and that
 170 | software libraries implementing the
 171 | <a href="https://www.w3.org/TR/vc-data-model/">data model specification</a>
 172 | will benefit from knowing how to resolve <a>DIDs</a>. <a>DID</a>-based URLs may
 173 | be used to express identifiers associated with <a>subjects</a>, <a>issuers</a>,
 174 | <a>holders</a>, credential status lists, cryptographic keys, and other
 175 | machine-readable information associated with a <a>verifiable credential</a>.
 176 |       </p>
 177 | 
 178 |     </section>
 179 | 
 180 |     <section class="informative">
 181 |       <h2>Terminology</h2>
 182 | 
 183 |       <div data-include="https://w3c.github.io/vc-data-model/terms.html"
 184 |         data-oninclude="restrictReferences">
 185 |       </div>
 186 |     </section>
 187 | 
 188 |     <section>
 189 |       <h2>Verification</h2>
 190 | 
 191 |       <em>This section is non-normative.</em>
 192 | 
 193 |       <p>
 194 | <a>Verification</a> is the process a <a>verifier</a> or <a>holder</a> performs
 195 | when presented with a <a>verifiable presentation</a> or
 196 | <a>verifiable credential</a>. <a>Verification</a> includes checking the
 197 | presented item against the <a href="https://www.w3.org/TR/vc-data-model/">core
 198 | data model</a>, and may also include validating the provided proof section and
 199 | checking the item's status.
 200 |       </p>
 201 | 
 202 |       <section>
 203 |         <h3>Core Data Model</h3>
 204 | 
 205 |         <p>
 206 | Conformant tooling that processes Verifiable Credentials will ensure that
 207 | the core data model is verified when processing credentials.
 208 |         </p>
 209 |       </section>
 210 | 
 211 |       <section>
 212 |         <h3>Specific Verifiable Credentials</h3>
 213 | 
 214 |         <p>
 215 | There are many data verification languages, the following approach is one
 216 | that should work for most use cases.
 217 |         </p>
 218 |       </section>
 219 |       <section>
 220 |         <h3>Content Integrity</h3>
 221 |         <p>
 222 | Protecting the integrity of content is an important component of verification.
 223 | <a>Verifiers</a> need to have confidence that the content they rely on to
 224 | verify <a>credentials</a> doesn't change without their knowledge. This content
 225 | may include data schemas, identifiers, public keys, etc.
 226 |         </p>
 227 |         <p>
 228 | There are a number of ways to provide content integrity protection. A few of
 229 | these are described in greater detail below.
 230 |         </p>
 231 |         <section>
 232 |           <h4>Hashlinks</h4>
 233 | 
 234 |           <p>
 235 | <a href="https://tools.ietf.org/html/draft-sporny-hashlink-00">Hashlink URLs</a>
 236 | can be used to provide content integrity for links to external resources.
 237 |           </p>
 238 |         </section>
 239 |         <section>
 240 |           <h4>Verifiable Data Registries</h4>
 241 |           <p>
 242 | A <a>verifiable data registry</a> can also provide content integrity protection.
 243 | One example of a <a>verifiable data registry</a> which provides content
 244 | integrity protection is a distributed ledger.
 245 |           </p>
 246 |         </section>
 247 |       </section>
 248 |     </section>
 249 |     <section>
 250 |       <h2>Disputes</h2>
 251 | 
 252 |       <p>
 253 | There are at least two different cases to consider where an <a>entity</a>
 254 | wants to dispute a <a>credential</a> issued by an <a>issuer</a>:
 255 |       </p>
 256 | 
 257 |       <ul>
 258 |         <li>
 259 | A <a>subject</a> disputes a claim made by the <a>issuer</a>. For example, the
 260 | <code>address</code> <a>property</a> is incorrect or out of date.
 261 |         </li>
 262 |         <li>
 263 | An <a>entity</a> disputes a potentially false claim made by the <a>issuer</a>
 264 | about a different <a>subject</a>. For example, an imposter has claimed the
 265 | social security number for an <a>entity</a>.
 266 |         </li>
 267 |       </ul>
 268 | 
 269 |       <p>
 270 | The mechanism for issuing a <code>DisputeCredential</code> is the same as
 271 | for a regular <a>credential</a>, except that the <code>credentialSubject</code>
 272 | identifier in the <code>DisputeCredential</code> property is the identifier of
 273 | the disputed <a>credential</a>.
 274 |       </p>
 275 | 
 276 |       <p>
 277 | For example, if a <a>credential</a> with an identifier of
 278 | <code>https://example.org/credentials/245</code> is disputed, an <a>entity</a>
 279 | can issue one of the <a>credentials</a> shown below. In the first example, the
 280 | <a>subject</a> might present this to the <a>verifier</a> along with the disputed
 281 | <a>credential</a>. In the second example, the <a>entity</a> might publish the
 282 | <code>DisputeCredential</code> in a public venue to make it known that the
 283 | <a>credential</a> is disputed.
 284 |       </p>
 285 | 
 286 |       <pre class="example nohighlight" title="A subject disputes a credential">
 287 | {
 288 |   "@context": [
 289 |     "https://www.w3.org/2018/credentials/v1",
 290 |     "https://www.w3.org/2018/credentials/examples/v1"
 291 |   ],
 292 |   "id": "http://example.com/credentials/123",
 293 |   "type": ["VerifiableCredential", "DisputeCredential"],
 294 |   <span class="highlight">"credentialSubject": {
 295 |     "id": "http://example.com/credentials/245",
 296 |     "currentStatus": "Disputed",
 297 |     "statusReason": {
 298 |       "@value": "Address is out of date",
 299 |       "@language": "en"
 300 |     },
 301 |   }</span>,
 302 |   "issuer": "https://example.com/people#me",
 303 |   "issuanceDate": "2017-12-05T14:27:42Z",
 304 |   "proof": { <span class="comment">...</span> }
 305 | }
 306 |       </pre>
 307 | 
 308 |       <pre class="example nohighlight" title="Another entity disputes a credential">
 309 | {
 310 |   "@context": "https://w3id.org/credentials/v1",
 311 |   "id": "http://example.com/credentials/321",
 312 |   "type": ["VerifiableCredential", "DisputeCredential"],
 313 |   <span class="highlight">"credentialSubject": {
 314 |     "id": "http://example.com/credentials/245",
 315 |     "currentStatus": "Disputed",
 316 |     "statusReason": {
 317 |       "@value": "Credential contains disputed statements",
 318 |       "@language": "en"
 319 |     },
 320 |     "disputedClaim": {
 321 |       "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
 322 |       "address": "Is Wrong"
 323 |     }
 324 |   }</span>,
 325 |   "issuer": "https://example.com/people#me",
 326 |   "issuanceDate": "2017-12-05T14:27:42Z",
 327 |   "proof": { <span class="comment">...</span> }
 328 | }
 329 |       </pre>
 330 | 
 331 |       <p>
 332 | In the above <a>verifiable credential</a>, the <a>issuer</a> is claiming that
 333 | the address in the disputed <a>verifiable credential</a> is wrong. For example,
 334 | the <a>subject</a> might wrongly be claiming to have the same address as that of
 335 | the <a>issuer</a>.
 336 |       </p>
 337 |       <p class="note">
 338 | If a <a>credential</a> does not have an identifier, a content-addressed
 339 | identifier can be used to identify the disputed <a>credential</a>. Similarly,
 340 | content-addressed identifiers can be used to uniquely identify individual
 341 | claims.
 342 |       </p>
 343 |     </section>
 344 | 
 345 |     <section>
 346 |       <h3>Presentations</h3>
 347 | 
 348 |       <p>
 349 | <a>Verifiable credentials</a> may be presented to a <a>verifier</a> by
 350 | using a <a>verifiable presentation</a>. A <a>verifiable presentation</a> can
 351 | be targeted to a specific <a>verifier</a> by using a Linked Data Proof
 352 | that includes a <code>domain</code> and <code>challenge</code>. This also
 353 | helps prevent a <a>verifier</a> from reusing a <a>verifiable presentation</a>
 354 | as their own.
 355 |       </p>
 356 | 
 357 |       <p>
 358 | The <code>domain</code> value can be any string or URI, and the
 359 | <code>challenge</code> should be a randomly generated string.
 360 |       </p>
 361 | 
 362 |       <p>
 363 | The following sample <a>verifiable presentation</a> is for authenticating to
 364 | a website, <code>https://example.com</code>.
 365 |       </p>
 366 | 
 367 |       <pre class="example nohighlight" title="A targeted verifiable presentation">
 368 | {
 369 |   "@context": [
 370 |     "https://www.w3.org/2018/credentials/v1"
 371 |   ],
 372 |   "type": "VerifiablePresentation,
 373 |   "verifiableCredential": { <span class="comment">...</span> },
 374 |   "proof": {
 375 |     "type": "Ed25519Signature2018",
 376 |     "created": "2019-08-13T15:09:00Z",
 377 |     <span class="highlight">"challenge": "d1b23d3...3d23d32d2",
 378 |     "domain": "https://example.com",</span>
 379 |     "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..uyW7Hv
 380 |       VOZ8QCpLJ63wHode0OdgWjsHfJ0O8d8Kfs55dMVEg3C1Z0bYUGV49s8IlTbi3eXsNvM63n
 381 |       vah79E-lAg",
 382 |     "proofPurpose": "authentication"
 383 |   }
 384 | }
 385 |       </pre>
 386 | 
 387 |     </section>
 388 | 
 389 |     <section>
 390 |       <h2>Extensions</h2>
 391 | 
 392 |       <em>This section is non-normative.</em>
 393 | 
 394 |       <p>
 395 | The Verifiable Credentials Data Model is designed around an <em>open world
 396 | assumption</em>, meaning that any entity can say anything about another entity.
 397 | This approach enables permissionless innovation; there is no centralized
 398 | registry or authority through which an extension author must register
 399 | themselves nor the specific data models and vocabularies they create.
 400 |       </p>
 401 | 
 402 |       <p>
 403 | Instead, credential data model authors are expected to use machine-readable
 404 | vocabularies through the use of [LINKED-DATA]. This implementation guide
 405 | provides examples for how to express data models using a data format that
 406 | is popular with software developers and web page authors called [JSON-LD]. This
 407 | data format provides features that enable authors to express their data models
 408 | in idiomatic JSON while also ensuring that their vocabulary terms are
 409 | unambigiously understood, even by software that does not implement
 410 | JSON-LD processing.
 411 |       </p>
 412 | 
 413 |       <p>
 414 | The Verifiable Credentials data model also uses a graph-based data model,
 415 | which allows authors to model both simple relationships that describe
 416 | one or more attributes for a single entity and complex multi-entity
 417 | relationships.
 418 |       </p>
 419 | 
 420 |       <p>
 421 | The rest of this section describes how to author extensions that build on
 422 | the Verifiable Credentials Data Model.
 423 |       </p>
 424 | 
 425 |       <section>
 426 |         <h3>Creating New Credential Types</h3>
 427 | 
 428 |         <p>
 429 | We expect the most common extensions to the Verifiable Credentials Data Model
 430 | to be new credential types. Whenever someone has something to say about one or
 431 | more entities and they want their authorship to be verifiable, they should use
 432 | a Verifiable Credential. Sometimes there may be an existing credential type,
 433 | that someone else has created, that can be reused to make the statements they
 434 | want to make. However, there are often cases where new credential types are
 435 | needed.
 436 |         </p>
 437 | 
 438 |         <p>
 439 | New credential types can be created by following a few steps. This guide will
 440 | also walk you through creating an example new credential type. At a high level,
 441 | the steps to follow are:
 442 |         </p>
 443 | 
 444 |         <ol>
 445 |           <li>
 446 | Design the data model.
 447 |           </li>
 448 |           <li>
 449 | Create a new JSON-LD context.
 450 |           </li>
 451 |           <li>
 452 | Select a publishing location.
 453 |           </li>
 454 |           <li>
 455 | Use the new JSON-LD context when issuing new credentials.
 456 |           </li>
 457 |         </ol>
 458 | 
 459 |         <p>
 460 | So, let's walk through creating a new credential type which we will
 461 | call <code>ExampleAddressCredential</code>. The purpose of this credential
 462 | will be to express a person's postal address.
 463 |         </p>
 464 | 
 465 |         <h4>Design the data model</h4>
 466 | 
 467 |         <p>
 468 | First, we must design a data model for our new credential type. We know that
 469 | we will need to be able to express the basics of a postal address, things
 470 | like a person's city, state, and zipcode. Of course, those items are quite
 471 | US centric, so we should consider internationalizing those terms. But before
 472 | we go further, since we're using [LINKED-DATA] vocabularies, there is a good
 473 | chance that commonly known concepts may already have a vocabulary that someone
 474 | else has created that we can leverage.
 475 |         </p>
 476 | 
 477 |         <p>
 478 | If we are going to use someone else's vocabulary, we will want to make sure it
 479 | is stable and unlikely to change in any significant way. There may even be
 480 | technologies that we can make use of that store immutable vocabularies that
 481 | we can reference, but those are not the focus of this example. Here we will
 482 | rely on the inertia that comes from a very popularly used vocabulary on the
 483 | Web, schema.org. It turns out that this vocabulary has just what we need; it
 484 | has already modeled a postal address and even has examples for how to express
 485 | it using JSON-LD.
 486 |         </p>
 487 | 
 488 |         <p>
 489 | Using the schema.org vocabulary and JSON-LD we can express a person's address
 490 | like so:
 491 |         </p>
 492 | 
 493 |         <pre class="example nohighlight" title="Example schema.org address">
 494 |           {
 495 |             <span class="highlight">
 496 |             "@context": [
 497 |               "http://schema.org"
 498 |             ]</span>,
 499 |             "type": "Person",
 500 |             "address": {
 501 |               "type": "PostalAddress",
 502 |               "streetAddress": "123 Main St."
 503 |               "addressLocality": "Blacksburg",
 504 |               "addressRegion": "VA",
 505 |               "postalCode": "24060",
 506 |               "addressCountry": "US"
 507 |             }
 508 |           }
 509 |         </pre>
 510 | 
 511 |         <p>
 512 | Note the above <code>@context</code> key in the JSON. This <code>@context</code>
 513 | refers to a machine-readable file (also expressed in JSON) that provides
 514 | term definitions [JSON-LD]. A term definition maps a key or type used in the
 515 | JSON, such as <code>address</code> or <code>PostalAddress</code>, to a globally
 516 | unique identifier: a URL.
 517 |         </p>
 518 | 
 519 |         <p>
 520 | This ensures that when software sees the <code>@context</code>
 521 | <em>http://schema.org</em>, that it will interpret the the keys and types in the
 522 | JSON in a globally consistent way, without requiring developers to use full URLs
 523 | in the JSON or in the code that may traverse it. As long as the software is
 524 | aware of the specific <code>@context</code> used (or if it uses JSON-LD
 525 | processing to transform it to some other known <code>@context</code>), then it
 526 | will understand the <em>context</em> in which the JSON was written and meant to
 527 | be understood. The use of <code>@context</code> also allows [JSON-LD] keywords
 528 | such as <code>@type</code> to be aliased to the simpler <code>type</code> as
 529 | is done in the above example.
 530 |         </p>
 531 | 
 532 |         <p>
 533 | Note that we could also express the JSON using full URLs, if we want to avoid
 534 | using <em>@context</em>. Here is what the example would look like if we did
 535 | that:
 536 |         </p>
 537 | 
 538 |         <pre class="example nohighlight" title="Example schema.org address with full URLs">
 539 |           {
 540 |             "@type": "http://schema.org/Person",
 541 |             "http://schema.org/address": {
 542 |               "@type": "http://schema.org/PostalAddress",
 543 |               "http://schema.org/streetAddress": "123 Main St."
 544 |               "http://schema.org/addressLocality": "Blacksburg",
 545 |               "http://schema.org/addressRegion": "VA",
 546 |               "http://schema.org/postalCode": "24060",
 547 |               "http://schema.org/addressCountry": "US"
 548 |             }
 549 |           }
 550 |         </pre>
 551 | 
 552 |         <p>
 553 | While this form is an acceptable way to express the information such that it is
 554 | unambiguous, many software developers would prefer to use more idiomatic JSON.
 555 | The use of <code>@context</code> enables idiomatic JSON without losing global
 556 | consistency and without the need for a centralized registry or authority for
 557 | creating extensions. Note that <code>@context</code> can also have more than
 558 | one value. In this case, a JSON array is used to express multiple values, where
 559 | each value references another context that defines terms. Using this mechanism
 560 | we can first bring in the terms defined in the Verifiable Credentials Data Model
 561 | specification and then bring in the terms defined by schema.org:
 562 |         </p>
 563 | 
 564 |         <pre class="example nohighlight" title="Example address credential with schema.org context">
 565 |           {
 566 |             <span class="highlight">
 567 |             "@context": [
 568 |               "https://www.w3.org/2018/credentials/v1",
 569 |               "http://schema.org"
 570 |             ]</span>,
 571 |             <span class="comment">...</span>
 572 |             "credentialSubject": {
 573 |               "type": "Person",
 574 |               "address": {
 575 |                 "type": "PostalAddress",
 576 |                 "streetAddress": "123 Main St."
 577 |                 "addressLocality": "Blacksburg",
 578 |                 "addressRegion": "VA",
 579 |                 "postalCode": "24060",
 580 |                 "addressCountry": "US"
 581 |               }
 582 |             },
 583 |             <span class="comment">...</span>
 584 |           }
 585 |         </pre>
 586 | 
 587 |         <p>
 588 | Note, however, that each <em>context</em> might have a different definition for
 589 | the same term, e.g., the JSON key <code>address</code> might map to a different
 590 | URL in each <em>context</em>. By default, [JSON-LD] allows terms in a
 591 | <code>@context</code> to be redefined using a <em>last term wins</em>
 592 | order. While these changes can be safely dealt with by using JSON-LD
 593 | processing, we want to lower the burden on consumers of Verifiable Credentials.
 594 | We want consumer software to be able to make assumptions about the meaning of
 595 | terms by only having to read and understand the string value associated with
 596 | the <code>@context</code> key. We don't want them to have to worry about terms
 597 | being redefined in unexpected ways. That way their software can inspect only
 598 | the <code>@context</code> values and then be hard coded to understand the
 599 | meaning of the terms.
 600 |         </p>
 601 | 
 602 |         <p>
 603 | In order to prevent term redefinition, the [JSON-LD] <code>@protected</code>
 604 | feature must be applied to term definitions in the <code>@context</code>. All
 605 | terms in the core Verifiable Credentials <code>@context</code> are
 606 | already protected in this way. The only time that an existing term is allowed
 607 | to be redefined is if the new definition is scoped underneath another new term
 608 | that is defined in a <em>context</em>. This matches developer expectations and
 609 | ensures that consumer software has strong guarantees about the semantics of the
 610 | data it is processing; it can be written such that it is never confused about
 611 | the definition of a term. Note that consumers must determine their own risk
 612 | profile for how to handle any credentials their software processes that include
 613 | terms that it does not understand.
 614 |         </p>
 615 | 
 616 |         <h4>Create a new JSON-LD context</h4>
 617 | 
 618 |         <p>
 619 | Given the above, there is at least one reason why we don't want to use
 620 | the schema.org <em>context</em>: it is designed to be very flexible and thus
 621 | does not use the <code>@protected</code> feature. There are a few additional
 622 | reasons we want to create our own [JSON-LD] context though. First, the
 623 | schema.org context does not define our new credential type:
 624 | <em>ExampleAddressCredential</em>. Second, it is not served via a secure
 625 | protocol (e.g., <em>https</em>); rather, it uses <em>http</em>. Note that this
 626 | is less of a concern than it may seem, as it is recommended that all Verifiable
 627 | Credential consumer software hard code the <code>@context</code> values it
 628 | understands and not reach out to the Web to fetch them. Lastly, it is a very
 629 | large context, containing many more term definitions than are necessary for our
 630 | purposes.
 631 |         </p>
 632 | 
 633 |         <p>
 634 | So, we will create our own [JSON-LD] context that expresses just those term
 635 | definitions that we need for our new credential type. Note that this does not
 636 | mean that we must mint new URLs; we can still reuse the schema.org vocabulary
 637 | terms. All we are doing is creating a more concise and targeted context. Here's
 638 | what we'll need in our context:
 639 |         </p>
 640 | 
 641 |         <pre class="example nohighlight" title="Example address credential context">
 642 |           {
 643 |             "@version": 1.1,
 644 |             "@protected": true,
 645 | 
 646 |             "ExampleAddressCredential":
 647 |               "https://example.org/ExampleAddressCredential",
 648 | 
 649 |             "Person": {
 650 |               "@id": "http://schema.org/Person",
 651 |               "@context": {
 652 |                 "@version": 1.1,
 653 |                 "@protected": true,
 654 | 
 655 |                 "address": "http://schema.org/address"
 656 |               }
 657 |             },
 658 |             "PostalAddress": {
 659 |               "@id": "http://schema.org/PostalAddress",
 660 |               "@context": {
 661 |                 "@version": 1.1,
 662 |                 "@protected": true,
 663 | 
 664 |                 "streetAddress": "http://schema.org/streetAddress",
 665 |                 "addressLocality": "http://schema.org/addressLocality",
 666 |                 "addressRegion": "http://schema.org/addressRegion",
 667 |                 "postalCode": "http://schema.org/postalCode",
 668 |                 "addressCountry": "http://schema.org/addressCountry"
 669 |               }
 670 |             }
 671 |           }
 672 |         </pre>
 673 | 
 674 |         <p>
 675 | The above context defines a term for our new credential type
 676 | <em>ExampleAddressCredential</em>, mapping it to the URL
 677 | <em>https://example.org/ExampleAddressCredential</em>. We could have also
 678 | chosen a URI like <em>urn:private-example:ExampleAddressCredential</em>, but
 679 | this approach would not allow us to serve up a Web page to describe it, if we
 680 | so desire. The context also defines the terms for types <em>Person</em> and
 681 | <em>PostalAddress</em>, mapping them to their schema.org vocabulary URLs.
 682 | Furthermore, when those types are used, it also defines protected terms for
 683 | each of them via a <em>scoped context</em>, mapping terms like <em>address</em>
 684 | and <em>streetAddress</em> to their schema.org vocabulary URLs. For more
 685 | information on how to write a JSON-LD context or <em>scoped contexts</em>, see
 686 | the [JSON-LD] specification.
 687 |         </p>
 688 | 
 689 |         <h4>Select a publishing location</h4>
 690 | 
 691 |         <p>
 692 | Now that we have a [JSON-LD] context, we must give it a URL. Technically
 693 | speaking, we could just use a URI, for example, a private URN such as
 694 | <em>urn:private-example:my-extension</em>. However, if we want people to be
 695 | able to read and discover it on the Web, we should give it a URL like
 696 | <em>https://example.org/example-address-credential-context/v1</em>.
 697 |         </p>
 698 | 
 699 |         <p>
 700 | When this URL is dereferenced, it should return
 701 | <em>application/ld+json</em> by default, to allow JSON-LD processors to process
 702 | the context. However, if a user agent requests <em>HTML</em>, it should return
 703 | human readable text that explains, to humans, what the term definitions are and
 704 | what they map to. Since we're reusing an existing vocabulary, schema.org, we
 705 | can also simply link to the definitions of the meaning of our types and terms
 706 | via their website. If we had created our own new vocabulary terms, we would
 707 | describe them on our own site, ideally including machine readable Information
 708 | as well.
 709 |         </p>
 710 | 
 711 |         <h4>Use the new JSON-LD context when issuing new credentials</h4>
 712 | 
 713 |         <p>
 714 | Now we're ready for our context to be used by anyone who
 715 | wishes to issue an <em>ExampleAddressCredential</em>!
 716 |         </p>
 717 | 
 718 |         <pre class="example nohighlight" title="Example address credential with schema.org context">
 719 |           {
 720 |             <span class="highlight">
 721 |             "@context": [
 722 |               "https://www.w3.org/2018/credentials/v1",
 723 |               "https://example.org/example-address-credential-context/v1"
 724 |             ]</span>,
 725 |             "id": "https://example.org/credentials/1234",
 726 |             "type": "ExampleAddressCredential",
 727 |             "issuer": "https://example.org/people#me",
 728 |             "issuanceDate": "2017-12-05T14:27:42Z",
 729 |             "credentialSubject": {
 730 |               "id": "did:example:1234",
 731 |               "type": "Person",
 732 |               "address": {
 733 |                 "type": "PostalAddress",
 734 |                 "streetAddress": "123 Main St."
 735 |                 "addressLocality": "Blacksburg",
 736 |                 "addressRegion": "VA",
 737 |                 "postalCode": "24060",
 738 |                 "addressCountry": "US"
 739 |               }
 740 |             },
 741 |             "proof": { <span class="comment">...</span> }
 742 |           }
 743 |         </pre>
 744 | 
 745 |         <p>
 746 | Note that writing this new credential type requires permission from no one,
 747 | you must only adhere to the above referenced standards.
 748 |         </p>
 749 | 
 750 |       </section>
 751 | 
 752 |       <section>
 753 |         <h3>Human Readability</h3>
 754 |         <p>
 755 | The JSON-LD Context declaration mechanism is used by implementations to
 756 | signal the context in which the data transmission is happening to consuming
 757 | applications:
 758 |         </p>
 759 | 
 760 |         <pre class="example nohighlight" title="Use of @context mechanism">
 761 |           {
 762 |             <span class="highlight">
 763 |             "@context": [
 764 |               "https://www.w3.org/2018/credentials/v1",
 765 |               "https://www.w3.org/2018/credentials/examples/v1"
 766 |             ]</span>,
 767 |             "id": "http://example.edu/credentials/1872",
 768 |             <span class="comment">...</span>
 769 |         </pre>
 770 | 
 771 |         <p>
 772 | Extension authors are urged to publish two types of information at the
 773 | context URLs. The first type of information is for machines, and is the
 774 | machine-readable JSON-LD Context. The second type of information is for
 775 | humans, and should be an HTML document. It is suggested that the default
 776 | mode of operation is to serve the machine-readable JSON-LD Context as that is
 777 | the primary intended use of the URL. If content-negotiation is supported,
 778 | requests for <code>text/html</code> should result in a human readable document.
 779 | The human readable document should at least contain usage information for the
 780 | extension, such as the expected order of URLs associated with the
 781 | <code>@context</code> property, specifications that elaborate on the extension,
 782 | and examples of typical usage of the extension.
 783 |         </p>
 784 |       </section>
 785 | 
 786 |     </section>
 787 | 
 788 |     <section>
 789 |       <h2>Proof Formats</h2>
 790 |       <em>This section is non-normative.</em>
 791 | 
 792 |       <p>
 793 | The <a>verifiable credentials</a>
 794 | <a href="https://w3c.github.io/vc-data-model/">data model </a> is designed to be
 795 | proof format agnostic. <a href="https://w3c.github.io/vc-data-model/">The
 796 | specification</a> does not normatively require any particular digital proof or
 797 | signature format. While the data model is the canonical representation of a
 798 | <a>verifiable credential</a> or <a>verifiable presentation</a>, the proving
 799 | mechanisms for these are often tied to the syntax used in the transmission of
 800 | the document between parties. As such, each proofing mechanism has to specify
 801 | whether the validation of the proof is calculated against the state of the
 802 | document as transmitted, against the transformed data model, or against another
 803 | form. At the time of publication, at least two proof formats are being actively
 804 | utilized by implementers, and the Working Group felt that documenting what these
 805 | proof formats are and how they are being used would be beneficial to other
 806 | implementers.
 807 |       </p>
 808 |       <p>
 809 | This guide provides tables in section <a href="#pf1b">Benefits of JWTs</a> and
 810 | section <a href="#pf1b">Benefits of JSON-LD and LD-Proofs</a> that compare three
 811 | syntax and proof format ecosystems; JSON+JWTs, JSON-LD+JWTs, and
 812 | JSON-LD+LD-Proofs.
 813 |       </p>
 814 |       <p>
 815 | Because the Verifiable Credentials Data Model is extensible, and agnostic to any
 816 | particular proof format, the specification and use of additional proof formats
 817 | is supported.
 818 |       </p>
 819 |         <section>
 820 |             <h3>Benefits of JWTs</h3>
 821 | 
 822 |             <p>
 823 | The Verifiable Credentials Data Model is designed to be compatible with a
 824 | variety of existing and emerging syntaxes and digital proof formats. Each
 825 | approach has benefits and drawbacks. The following table is intended to
 826 | summarize a number of these native trade-offs.
 827 |             </p>
 828 | 
 829 |             <p>
 830 | The table below compares three syntax and proof format ecosystems; JSON+JWTs,
 831 | JSON-LD+JWTs, and JSON-LD+LD-Proofs.
 832 |             </p>
 833 | 
 834 |             <table class="simple" id="#pfatable">
 835 |                 <thead>
 836 |                 <tr>
 837 |                     <th style="text-align: center;">Feature</th>
 838 |                     <th style="text-align: center;">JSON<br>+<br>JWTs</th>
 839 |                     <th style="text-align: center;">JSON&#8209;LD<br>+<br>JWTs</th>
 840 |                     <th style="text-align: center;">JSON&#8209;LD<br>+<br>LD&#8209;Proofs</th>
 841 |                 </tr>
 842 |                 </thead>
 843 | 
 844 |                 <tbody>
 845 |                 <tr>
 846 |                     <td>
 847 | <a href="#pf1a">PF1a.</a> Proof format supports Zero-Knowledge Proofs.
 848 |                     </td>
 849 |                     <td class="supported">✓</td>
 850 |                     <td class="supported">✓</td>
 851 |                     <td class="supported">✓</td>
 852 |                 </tr>
 853 |                 <tr>
 854 |                     <td>
 855 | <a href="#pf2a">PF2a.</a> Proof format supports arbitrary proofs such as Proof
 856 | of Work, Timestamp Proofs, and Proof of Stake.
 857 |                     </td>
 858 |                     <td class="supported">✓</td>
 859 |                     <td class="supported">✓</td>
 860 |                     <td class="supported">✓</td>
 861 |                 </tr>
 862 |                 <tr>
 863 |                     <td>
 864 | <a href="#pf3a">PF3a.</a> Based on existing official standards.
 865 |                     </td>
 866 |                     <td class="supported">✓</td>
 867 |                     <td class="missing">✖</td>
 868 |                     <td class="missing">✖</td>
 869 |                 </tr>
 870 |                 <tr>
 871 |                     <td>
 872 | <a href="#pf4a">PF4a.</a> Designed to be small in size.
 873 |                     </td>
 874 |                     <td class="supported">✓</td>
 875 |                     <td class="missing">✖</td>
 876 |                     <td class="missing">✖</td>
 877 |                 </tr>
 878 |                 <tr>
 879 |                     <td>
 880 | <a href="#pf5a">PF5a.</a> Offline support without further processing.
 881 |                     </td>
 882 |                     <td class="supported">✓</td>
 883 |                     <td class="missing">✖</td>
 884 |                     <td class="missing">✖</td>
 885 |                 </tr>
 886 |                 <tr>
 887 |                     <td>
 888 | <a href="#pf6a">PF6a.</a> Wide adoption in other existing standards.
 889 |                     </td>
 890 |                     <td class="supported">✓</td>
 891 |                     <td class="supported">✓</td>
 892 |                     <td class="missing">✖</td>
 893 |                 </tr>
 894 |                 <tr>
 895 |                     <td>
 896 | <a href="#pf7a">PF7a.</a> No type ambiguity.
 897 |                     </td>
 898 |                     <td class="supported">✓</td>
 899 |                     <td class="missing">✖</td>
 900 |                     <td class="missing">✖</td>
 901 |                 </tr>
 902 |                 <tr>
 903 |                     <td>
 904 | <a href="#pf8a">PF8a.</a> Broad library support.
 905 |                     </td>
 906 |                     <td class="supported">✓</td>
 907 |                     <td class="missing">✖</td>
 908 |                     <td class="missing">✖</td>
 909 |                 </tr>
 910 |                 <tr>
 911 |                     <td>
 912 | <a href="#pf9a">PF9a.</a> Easy to understand what is signed.
 913 |                     </td>
 914 |                     <td class="supported">✓</td>
 915 |                     <td class="supported">✓</td>
 916 |                     <td class="missing">✖</td>
 917 |                 </tr>
 918 |                 <tr>
 919 |                     <td>
 920 | <a href="#pf10a">PF10a.</a> Ability to be used as authn/authz token with existing systems.
 921 |                     </td>
 922 |                     <td class="supported">✓</td>
 923 |                     <td class="supported">✓</td>
 924 |                     <td class="missing">✖</td>
 925 |                 </tr>
 926 |                 <tr>
 927 |                     <td>
 928 | <a href="#pf11a">PF11a.</a> No additional canonicalization required.
 929 |                     </td>
 930 |                     <td class="supported">✓</td>
 931 |                     <td class="missing">✖</td>
 932 |                     <td class="missing">✖</td>
 933 |                 </tr>
 934 |                 <tr>
 935 |                     <td>
 936 | <a href="#pf12a">PF12a.</a> No Internet PKI required.
 937 |                     </td>
 938 |                     <td class="supported">✓</td>
 939 |                     <td class="missing">✖</td>
 940 |                     <td class="missing">✖</td>
 941 |                 </tr>
 942 |                 <tr>
 943 |                     <td>
 944 | <a href="#pf13a">PF13a.</a> No resolution of external documents needed.
 945 |                     </td>
 946 |                     <td class="supported">✓</td>
 947 |                     <td class="missing">✖</td>
 948 |                     <td class="missing">✖</td>
 949 |                 </tr>
 950 | 
 951 |               </tbody>
 952 |             </table>
 953 | 
 954 |             <p class="note">
 955 | Some of the features listed in the table above are debateable, since a feature
 956 | can always be added to a particular syntax or digital proof format. The table
 957 | is intended to identify native features of each combination such that no
 958 | additional language design or extension is required to achieve the identified
 959 | feature. Features that all languages provide, such as the ability to express
 960 | numbers, have not been included for the purposes of brevity. Find more information
 961 | about different proof formats in the next section.
 962 |             </p>
 963 | 
 964 |             <dl>
 965 |               <dt id="pf1a">
 966 | PF1a: Proof format supports Zero-Knowledge Proofs.
 967 |               </dt>
 968 |                 <dd>
 969 | JWTs can embed `proof` attributes for repudiable proofs such as Zero-Knowledge Proofs.
 970 | In that case, the JWS will not have an signature element.
 971 |                 </dd>
 972 |                 <dt id="pf2a">
 973 | PF2a: Proof format supports arbitrary proofs such as Proof of Work, Timestamp
 974 | Proofs, and Proof of Stake.
 975 |                 </dt>
 976 |                 <dd>
 977 | JWTs can embed `proof` attributes for any type of proofs such as Proof of Work, Timestamp,
 978 | Proofs, and Proof Stake.
 979 |                 </dd>
 980 |                 <dt id="pf3a">
 981 | PF3a: Based on existing official standards.
 982 |                 </dt>
 983 |                 <dd>
 984 | JSON and JWT are proposed and mature IETF standards. While JSON-LD 1.0 is in
 985 | REC state in W3C, JSON-LD 1.1 is still in WD state. LD-Proofs are not standardized at all.
 986 |                 </dd>
 987 |                 <dt id="pf4a">
 988 | PF4a: Designed to be small in size.
 989 |                 </dt>
 990 |                 <dd>
 991 | JSON was invented as a simple data format to be transmitted on the wire. A verifiable credential
 992 | can be expressed by its attributes only, without the necessity to introduce additional meta-information
 993 | such as @context. This makes the resulting JSON+JWT credential typically also smaller in size.
 994 |                 </dd>
 995 |                 <dt id="pf5a">
 996 | PF5a: Offline support without further processing.
 997 |                 </dt>
 998 |                 <dd>
 999 | A JWT can fully describe itself without the need to retrieve or verify any external documents.
1000 | JSON-LD requires the context to be queryable and requires further documents to be accessible
1001 | to check the prevalent document, e.g., LD-Proof. Additional caching needs to be implemented
1002 | to support offline use cases.
1003 |                 </dd>
1004 |                 <dt id="pf6a">
1005 | PF6a: Wide adoption in other existing standards.
1006 |                 </dt>
1007 |                 <dd>
1008 | JWT founds its application in many other existing standards, e.g., OAuth2, OpenID Connect.
1009 | This allows for backward compatibility with existing authentication and authorization
1010 | frameworks without or with only minor modifications to these legacy systems.
1011 |                 </dd>
1012 |                 <dt id="pf7a">
1013 | PF7a: No type ambiguity.
1014 |                 </dt>
1015 |                 <dd>
1016 | It is best practice that JSON data structures typically do not expect changing types of
1017 | their internal attributes. JSON-LD has implicit support for compact form serialization
1018 | which transforms arrays with a single element only to switch its data type. Developers
1019 | writing parsers have to implement special handling of these data types, which results in
1020 | more code, is more error-prone and sometimes does not allow parsers based on code
1021 | generation, which rely on static types.
1022 |                 </dd>
1023 |                 <dt id="pf8a">
1024 | PF8a: Broad library support.
1025 |                 </dt>
1026 |                 <dd>
1027 | JWT and JSON due to its maturity and standardization, have a lot of open-source library
1028 | support. While JSON-LD 1.0 is a standard and has support for different programming
1029 | languages, it is still behind JSON which is often part of the native platform
1030 | toolchain, e.g., JavaScript. For LD-Proofs, on the other hand, only a few scattered
1031 | libraries exist.
1032 |                 </dd>
1033 |                 <dt id="pf9a">
1034 | PF9a: Easy to understand what is signed.
1035 |                 </dt>
1036 |                 <dd>
1037 | JWT makes it visible what is signed in contrast to LD-Proofs, e.g., LD Signatures, that
1038 | are detached from the actual payload and contain links to external documents which makes
1039 | it not obvious for a developer to figure out what is part of the signature.
1040 |                 </dd>
1041 |                 <dt id="pf10a">
1042 | PF10a: Ability to be used as authn/authz token with existing systems.
1043 |                 </dt>
1044 |                 <dd>
1045 | Many existing applications rely on JWT for authentication and authorization purposes.
1046 | In theory, developers maintaining these applications could leverage JWT-based verifiable
1047 | presentations in their current systems with minor or no modifications. LD-Proofs represents
1048 | a new approach which would require more work to achieve the same result.
1049 |                 </dd>
1050 |                 <dt id="pf11a">
1051 | PF11a: No additional canonicalization required.
1052 |                 </dt>
1053 |                 <dd>
1054 | Beyond base64 URL encoding JSON and JWT don't require any canonicalization to be transmitted
1055 | on the wire. The JWS can be calculated on any data inside of the payload. This results in less
1056 | computation, less complexity, and light-weight libraries compared to JSON-LD and LD-Proofs where
1057 | canonicalization is required.
1058 |                 </dd>
1059 |                 <dt id="pf12a">
1060 | PF12a: No Internet PKI required.
1061 |                 </dt>
1062 |                 <dd>
1063 | JSON-LD and LD-Proofs rely on resolving external documents, e.g., <code>@context</code>. This means that
1064 | a verifiable credential system would rely on existing Internet PKI to a certain extend and
1065 | cannot be fully decentralized. A JWT-based system does not need to introduce this dependency.
1066 |                 </dd>
1067 |                 <dt id="pf13a">
1068 | PF13a: No resolution of external documents needed.
1069 |                 </dt>
1070 |                 <dd>
1071 | JSON-LD and LD-Proofs require the resolution of external documents, which leads to an
1072 | increased network load for the verifier of a verifiable presentation. This needs to be
1073 | mitigated through caching strategies.
1074 |                 </dd>
1075 |             </dl>
1076 |         </section>
1077 |         <section>
1078 |           <h3>Benefits of JSON-LD and LD-Proofs</h3>
1079 | 
1080 |           <p>
1081 | The Verifiable Credentials Data Model is designed to be compatible with a
1082 | variety of existing and emerging syntaxes and digital proof formats. Each
1083 | approach has benefits and drawbacks. The following table is intended to
1084 | summarize a number of these native trade-offs.
1085 |           </p>
1086 | 
1087 |           <p>
1088 | The table below compares three syntax and proof format ecosystems; JSON+JWTs,
1089 | JSON-LD+JWTs, and JSON-LD+LD-Proofs. Readers should be aware that
1090 | Zero-Knowledge Proofs are currently proposed as a sub-type of LD-Proofs and
1091 | thus fall into the final column below.
1092 |           </p>
1093 | 
1094 |           <table class="simple" id="#pfbtable">
1095 |             <thead>
1096 |               <tr>
1097 |                 <th style="text-align: center;">Feature</th>
1098 |                 <th style="text-align: center;">JSON<br>+<br>JWTs</th>
1099 |                 <th style="text-align: center;">JSON&#8209;LD<br>+<br>JWTs</th>
1100 |                 <th style="text-align: center;">JSON&#8209;LD<br>+<br>LD&#8209;Proofs</th>
1101 |               </tr>
1102 |             </thead>
1103 | 
1104 |             <tbody>
1105 |               <tr>
1106 |                 <td>
1107 | <a href="#pf1b">PF1b.</a> Support for open world data modelling.
1108 |                 </td>
1109 |                 <td class="missing">✖</td>
1110 |                 <td class="supported">✓</td>
1111 |                 <td class="supported">✓</td>
1112 |               </tr>
1113 |               <tr>
1114 |                 <td>
1115 | <a href="#pf2b">PF2b.</a> Universal identifier mechanism for JSON objects via
1116 | the use of URIs.
1117 |                 </td>
1118 |                 <td class="missing">✖</td>
1119 |                 <td class="supported">✓</td>
1120 |                 <td class="supported">✓</td>
1121 |               </tr>
1122 |               <tr>
1123 |                 <td>
1124 | <a href="#pf3b">PF3b.</a> A way to disambiguate properties shared among different
1125 | JSON documents by mapping them to IRIs via a context.
1126 |                 </td>
1127 |                 <td class="missing">✖</td>
1128 |                 <td class="supported">✓</td>
1129 |                 <td class="supported">✓</td>
1130 |               </tr>
1131 |               <tr>
1132 |                 <td>
1133 | <a href="#pf4b">PF4b.</a> A mechanism to refer to data in an external document,
1134 | where the data may be merged with the local document without a merge conflict
1135 | in semantics or structure.
1136 |                 </td>
1137 |                 <td class="missing">✖</td>
1138 |                 <td class="supported">✓</td>
1139 |                 <td class="supported">✓</td>
1140 |               </tr>
1141 |               <tr>
1142 |                 <td>
1143 | <a href="#pf5b">PF5b.</a> The ability to annotate strings with their language.
1144 |                 </td>
1145 |                 <td class="missing">✖</td>
1146 |                 <td class="supported">✓</td>
1147 |                 <td class="supported">✓</td>
1148 |               </tr>
1149 |               <tr>
1150 |                 <td>
1151 | <a href="#pf6b">PF6b.</a> A way to associate arbitrary datatypes, such as dates
1152 | and times, with arbitrary property values.
1153 |                 </td>
1154 |                 <td class="missing">✖</td>
1155 |                 <td class="supported">✓</td>
1156 |                 <td class="supported">✓</td>
1157 |               </tr>
1158 |               <tr>
1159 |                 <td>
1160 | <a href="#pf7b">PF7b.</a> A facility to express one or more directed graphs,
1161 | such as a social network, in a single document.
1162 |                 </td>
1163 |                 <td class="missing">✖</td>
1164 |                 <td class="supported">✓</td>
1165 |                 <td class="supported">✓</td>
1166 |               </tr>
1167 |               <tr>
1168 |                 <td>
1169 | <a href="#pf8b">PF8b.</a> Supports signature sets.
1170 |                 </td>
1171 |                 <td class="missing">✖</td>
1172 |                 <td class="missing">✖</td>
1173 |                 <td class="supported">✓</td>
1174 |               </tr>
1175 |               <tr>
1176 |                 <td>
1177 | <a href="#pf9b">PF9b.</a> Embeddable in HTML such that search crawlers will
1178 | index the machine-readable content.
1179 |                 </td>
1180 |                 <td class="missing">✖</td>
1181 |                 <td class="missing">✖</td>
1182 |                 <td class="supported">✓</td>
1183 |               </tr>
1184 |               <tr>
1185 |                 <td>
1186 | <a href="#pf10b">PF10b.</a> Data on the wire is easy to debug and serialize to
1187 | database systems.
1188 |                 </td>
1189 |                 <td class="missing">✖</td>
1190 |                 <td class="missing">✖</td>
1191 |                 <td class="supported">✓</td>
1192 |               </tr>
1193 |               <tr>
1194 |                 <td>
1195 | <a href="#pf11b">PF11b.</a> Nesting signed data does not cause data size to
1196 | double for every embedding.
1197 |                 </td>
1198 |                 <td class="missing">✖</td>
1199 |                 <td class="missing">✖</td>
1200 |                 <td class="supported">✓</td>
1201 |               </tr>
1202 |               <tr>
1203 |                 <td>
1204 | <a href="#pf12b">PF12b.</a> Proof format supports Zero-Knowledge Proofs.
1205 |                 </td>
1206 |                 <td class="missing">✖</td>
1207 |                 <td class="missing">✖</td>
1208 |                 <td class="supported">✓</td>
1209 |               </tr>
1210 |               <tr>
1211 |                 <td>
1212 | <a href="#pf13b">PF13b.</a> Proof format supports arbitrary proofs such as Proof
1213 | of Work, Timestamp Proofs, and Proof of Stake.
1214 |                 </td>
1215 |                 <td class="missing">✖</td>
1216 |                 <td class="missing">✖</td>
1217 |                 <td class="supported">✓</td>
1218 |               </tr>
1219 |               <tr>
1220 |                 <td>
1221 | <a href="#pf14b">PF14b.</a> Proofs can be expressed unmodified in other data
1222 | syntaxes such as YAML, N-Quads, and CBOR.
1223 |                 </td>
1224 |                 <td class="missing">✖</td>
1225 |                 <td class="missing">✖</td>
1226 |                 <td class="supported">✓</td>
1227 |               </tr>
1228 |               <tr>
1229 |                 <td>
1230 | <a href="#pf15b">PF15b.</a> Changing property-value ordering, or introducing
1231 | whitespace does not invalidate signature.
1232 |                 </td>
1233 |                 <td class="missing">✖</td>
1234 |                 <td class="missing">✖</td>
1235 |                 <td class="supported">✓</td>
1236 |               </tr>
1237 |               <tr>
1238 |                 <td>
1239 | <a href="#pf16b">PF16b.</a> Designed to easily support experimental signature
1240 | systems.
1241 |                 </td>
1242 |                 <td class="missing">✖</td>
1243 |                 <td class="missing">✖</td>
1244 |                 <td class="supported">✓</td>
1245 |               </tr>
1246 |               <tr>
1247 |                 <td>
1248 | <a href="#pf17b">PF17b.</a> Supports signature chaining.
1249 |                 </td>
1250 |                 <td class="missing">✖</td>
1251 |                 <td class="missing">✖</td>
1252 |                 <td class="supported">✓</td>
1253 |               </tr>
1254 |               <tr>
1255 |                 <td>
1256 | <a href="#pf18b">PF18b.</a> Does not require pre-processing or post-processing.
1257 |                 </td>
1258 |                 <td class="missing">✖</td>
1259 |                 <td class="missing">✖</td>
1260 |                 <td class="supported">✓</td>
1261 |               </tr>
1262 |               <tr>
1263 |                 <td>
1264 | <a href="#pf19b">PF19b.</a> Canonicalization requires only base-64 encoding.
1265 |                 </td>
1266 |                 <td class="missing">✖</td>
1267 |                 <td class="missing">✖</td>
1268 |                 <td class="supported">✓</td>
1269 |               </tr>
1270 |             </tbody>
1271 |           </table>
1272 | 
1273 |           <p class="note">
1274 | Some of the features listed in the table above are debateable, since a feature
1275 | can always be added to a particular syntax or digital proof format. The table
1276 | is intended to identify native features of each combination such that no
1277 | additional language design or extension is required to achieve the identified
1278 | feature. Features that all languages provide, such as the ability to express
1279 | numbers, have not been included for the purposes of brevity.
1280 |           </p>
1281 | 
1282 |           <dl>
1283 |             <dt id="pf1b">
1284 | PF1b: Support for open world data modelling
1285 |             </dt>
1286 |             <dd>
1287 | An <em>open world data model</em> is one where any entity can make any
1288 | statement about anything while simultaneously ensuring that the semantics of
1289 | the statement are unambiguous. This specification is enabled by an open world
1290 | data model called Linked Data. One defining characteristic of supporting an open
1291 | world data model is the ability to specify the semantic context in which data
1292 | is being expressed. JSON-LD provides this mechanism via the
1293 | <code>@context</code> property. JSON has no such feature.
1294 |             </dd>
1295 |             <dt id="pf2b">
1296 | PF2b: Universal identifier mechanism for JSON objects via the use of URIs.
1297 |             </dt>
1298 |             <dd>
1299 | All entities in a JSON-LD document are identified either via an automatic URI,
1300 | or via an explicit URI. This enables all entities in a document to be
1301 | unambiguously referenced. JSON does not have a native URI type nor does it
1302 | require objects to have one, making it difficult to impossible to unambiguously
1303 | identify an entity expressed in JSON.
1304 |             </dd>
1305 |             <dt id="pf3b">
1306 | PF3b: A way to disambiguate properties shared among different JSON documents by
1307 | mapping them to IRIs via a context.
1308 |             </dt>
1309 |             <dd>
1310 | All object properties in a JSON-LD document, such as the property "homepage",
1311 | are either keywords or they are mapped to an IRI. This feature enables open
1312 | world systems to identify the semantic meaning of the property in an unambiguous
1313 | way, which enables seamless merging of data between disparate systems.
1314 | JSON object properties are not mapped to IRIs, which result in ambiguities with
1315 | respect to the semantic meaning of the property. For example, one JSON document
1316 | might use "title" (meaning "book title") in a way that is semantically
1317 | incompatible with another JSON document using "title" (meaning "job title").
1318 |             </dd>
1319 |             <dt id="pf4b">
1320 | PF4b: A mechanism to refer to data in an external document, where the data may
1321 | be merged with the local document without a merge conflict in semantics or
1322 | structure.
1323 |             </dt>
1324 |             <dd>
1325 | JSON-LD provides a mechanism that enables a data value to use a URL to refer
1326 | to data outside of the local document. This external data may then be
1327 | automatically merged with the local document without a merge conflict in
1328 | semantics or structure. This feature enables a system to apply the
1329 | "follow your nose" principle to discover a richer set of data that is
1330 | associated with the local document. While a JSON document can contain pointers
1331 | to external data, interpreting the pointer is often application specific and
1332 | usually does not support merging the external data to construct a richer data
1333 | set.
1334 |             </dd>
1335 |             <dt id="pf5b">
1336 | PF5b: The ability to annotate strings with their language.
1337 |             </dt>
1338 |             <dd>
1339 | JSON-LD enables a developer to specify the language, such as English, French,
1340 | or Japanese, in which a text string is expressed via the use of language tags.
1341 | JSON does not provide such a feature.
1342 |             </dd>
1343 |             <dt id="pf6b">
1344 | PF6b: A way to associate arbitrary datatypes, such as dates
1345 | and times, with arbitrary property values.
1346 |             </dt>
1347 |             <dd>
1348 | JSON-LD enables a developer to specify the data type of a property value,
1349 | such as Date, unsigned integer, or Temperature by specifying it in the
1350 | JSON-LD Context. JSON does not provide such a feature.
1351 |             </dd>
1352 |             <dt id="pf7b">
1353 | PF7b: A facility to express one or more directed graphs, such as a social
1354 | network, in a single document.
1355 |             </dt>
1356 |             <dd>
1357 | JSON-LD's abstract data model supports the expression of information
1358 | as a directed graph of labeled nodes and edges, which enables an open world
1359 | data model to be supported. JSON's abstract data model only supports the
1360 | expression of information as a tree of unlabeled nodes and edges, which
1361 | restricts the types of relationships and structures that can be natively
1362 | expressed in the language.
1363 |             </dd>
1364 |             <dt id="pf8b">
1365 | PF8b: Supports signature sets.
1366 |             </dt>
1367 |             <dd>
1368 | A signature set is an unordered set of signatures over a data payload. Use
1369 | cases, such as cryptographic signatures applied to a legal contract,
1370 | typically require more than one signature to be associated with the contract
1371 | in order to legally bind two or more parties under the terms of the contract.
1372 | Linked Data Proofs, including Linked Data Signatures, natively support sets of
1373 | signatures. JWTs only enable a single signature over a single payload.
1374 |             </dd>
1375 |             <dt id="pf9b">
1376 | PF9b: Embeddable in HTML such that search crawlers will index the
1377 | machine-readable content.
1378 |             </dt>
1379 |             <dd>
1380 | All major search crawlers natively parse and index information expressed as
1381 | JSON-LD in HTML pages. LD-Proofs enable the current data format that search
1382 | engines use to be extended to support digital signatures. JWTs have no mechanism
1383 | to express data in HTML pages and are currently not indexed by search crawlers.
1384 |             </dd>
1385 |             <dt id="pf10b">
1386 | PF10b: Data on the wire is easy to debug and serialize to database systems.
1387 |             </dt>
1388 |             <dd>
1389 | When developers are debugging software systems, it is beneficial for them to be
1390 | able to see the data that they are operating on using common debugging tools.
1391 | Similarly, it is useful to be able to serialize data from the network to a
1392 | database and then from the database back out to the network using a minimal
1393 | number of pre and post processing steps. LD-Proofs enable developers to use
1394 | common JSON tooling without having to convert the format into a different
1395 | format or structure. JWTs base-64 encode payload information, resulting in
1396 | complicated pre and post processing steps to convert the data into JSON data
1397 | while not destroying the digital signature. Similarly, schema-less databases,
1398 | which are typically used to index JSON data, cannot index information
1399 | that is expressed in an opaque base-64 encoded wrapper.
1400 |             </dd>
1401 |             <dt id="pf11b">
1402 | PF11b: Nesting signed data does not cause data size to double for every
1403 | embedding.
1404 |             </dt>
1405 |             <dd>
1406 | When a JWT is encapsulated by another JWT, the entire payload must be base-64
1407 | encoded in the initial JWT, and then base-64 encoded again in the encapsulating
1408 | JWT. This is often necessary when a cryptographic signature is required on a
1409 | document that contains a cryptographic signature, such as when a Notary
1410 | signs a document that has been signed by someone else seeking the Notary's
1411 | services. LD-Proofs do not require base-64 encoding the signed portion of a
1412 | document and instead rely on a canonicalization process that is just as
1413 | secure, and that only requires the cryptographic signature to be encoded
1414 | instead of the entire payload.
1415 |             </dd>
1416 |             <dt id="pf12b">
1417 | PF12b: Proof format supports Zero-Knowledge Proofs.
1418 |             </dt>
1419 |             <dd>
1420 | The LD-Proof format is capable of modifying the algorithm that generates
1421 | the hash or hashes that are cryptographically signed. This cryptographic
1422 | agility enables digital signature systems, such as Zero-Knowledge Proofs,
1423 | to be layered on top of LD-Proofs instead of an entirely new digital signature
1424 | container format to be created. JWTs are designed such that an entirely new
1425 | digital signature container format will be required to support Zero-Knowledge
1426 | Proofs.
1427 |             </dd>
1428 |             <dt id="pf13b">
1429 | PF13b: Proof format supports arbitrary proofs such as Proof of Work, Timestamp
1430 | Proofs, and Proof of Stake.
1431 |             </dt>
1432 |             <dd>
1433 | The LD-Proof format was designed with a broader range of proof types in mind
1434 | and supports cryptographic proofs beyond simple cryptographic signatures.
1435 | These proof types are in common usage in systems such as decentralized ledgers
1436 | and provide additional guarantees to
1437 | <a>verifiable credentials</a>, such as the ability to prove that a particular
1438 | claim was made at a particular time or that a certain amount of energy was
1439 | expended to generate a particular credential. The JWT format does not support
1440 | arbitrary proof formats.
1441 |             </dd>
1442 |             <dt id="pf14b">
1443 | PF14b: Proofs can be expressed unmodified in other data syntaxes such as XML,
1444 | YAML, N-Quads, and CBOR.
1445 |             </dt>
1446 |             <dd>
1447 | The LD-Proof format utilizes a canonicalization algorithm to generate a
1448 | cryptographic hash that is used as an input to the cryptographic proof
1449 | algorithm. This enables the bytes generated as the cryptographic proof to be
1450 | compact and expressible in a variety of other syntaxes such as XML,
1451 | YAML, N-Quads, and CBOR. Since JWTs require the use of JSON to be generated,
1452 | they are inextricably tied to the JSON syntax.
1453 |             </dd>
1454 |             <dt id="pf15b">
1455 | PF15b: Changing property-value ordering, or introducing whitespace does not
1456 | invalidate signature.
1457 |             </dt>
1458 |             <dd>
1459 | Since LD-Proofs utilize a canonicalization algorithm, the introduction of
1460 | whitespace that does not change the meaning of the information being expressed
1461 | has no effect on the final cryptographic hash over the information. This means
1462 | that simple changes in whitespace formatting, such as those changes made when
1463 | writing data to a schema-less database and then retrieving the same information
1464 | from the same database do not cause the digital signature to fail. JWTs
1465 | encode the payload using the base-64 format which is not resistant to
1466 | whitespace formatting that has no effect on the information expressed. This
1467 | shortcoming of JWTs make it challenging to, for example, express signed data in
1468 | web pages that search crawlers index.
1469 |             </dd>
1470 |             <dt id="pf16b">
1471 | PF16b: Designed to easily support experimental signature systems.
1472 |             </dt>
1473 |             <dd>
1474 | The LD-Proof format is naturally extensible, not requiring the format to be
1475 | extended in a formal international standards working group in order to
1476 | prevent namespace collisions. The JWT format requires entries in a centralized
1477 | registry in order to avoid naming collisions and does not support
1478 | experimentation as easily as the LD-Proof format does. LD-Proof format
1479 | extension is done through the decentralized publication of cryptographic
1480 | suites that are guaranteed to not conflict with other LD-Proof
1481 | extensions. This approach enables developers to easily experiment with new
1482 | cryptographic signature mechanisms that support selective disclosure,
1483 | zero-knowledge proofs, and post-quantum algorithms.
1484 |             </dd>
1485 |             <dt id="pf17b">
1486 | PF17b: Supports signature chaining.
1487 |             </dt>
1488 |             <dd>
1489 | A signature chain is an ordered set of signatures over a data payload. Use
1490 | cases, such as cryptographic signatures applied to a notarized document,
1491 | typically require a signature by the signing party and then an additional one
1492 | by a notary to be made after the original signing party has made their
1493 | signature. Linked Data Proofs, including Linked Data Signatures, natively
1494 | support chains of signatures. JWTs only enable a single signature over a
1495 | single payload.
1496 |             </dd>
1497 |             <dt id="pf18b">
1498 | PF18b: Does not require pre-processing or post-processing.
1499 |             </dt>
1500 |             <dd>
1501 | In order to encode a <a>verifiable credential</a> or a
1502 | <a>verifiable presentation</a> in a JWT, an extra set of steps
1503 | are required to convert the data to and from the JWT format. No such extra
1504 | converstion step are required for <a>verifiable credentials</a> and
1505 | <a>verifiable presentations</a> protected by LD-Proofs.
1506 |             </dd>
1507 |             <dt id="pf19b">
1508 | PF19b: Canonicalization requires only base-64 encoding.
1509 |             </dt>
1510 |             <dd>
1511 | The JWT format utilizes a simple base-64 encoding format to generate the
1512 | cryptographic hash of the data. The encoding format for LD-Proofs requires
1513 | a more complex canonicalization algorithm to generate the cryptographic
1514 | hash. The benefits of the JWT approach are simplicity at the cost of
1515 | encoding flexibility. The benefits of the LD-Proof approach are flexibility at
1516 | the cost of implementation complexity.
1517 |           </dd>
1518 |         </dl>
1519 | 
1520 |       </section>
1521 | 
1522 |     </section>
1523 | 
1524 |     <section>
1525 |       <h2>Zero-Knowledge Proofs</h2>
1526 |       <em>This section is non-normative</em>
1527 |         <p>
1528 | The Verifiable Credentials Data Model is designed to be compatible with a
1529 | variety of existing and emerging digital proof formats. Each
1530 | proof format has benefits and drawbacks. Many proof formats cannot reveal
1531 | only selected attribute values from a verifiable credential; they can only
1532 | reveal all (or none).
1533 |         </p>
1534 |         <p>
1535 | Zero-Knowledge Proofs (ZKPs) are a proof format that enables
1536 | privacy-preserving data-minimization features in <a>verifiable presentations</a>,
1537 | such as selective disclosure and predicate proofs.
1538 |         </p>
1539 |         <p>
1540 | Selective disclosure is the ability of a holder to reveal a subset of
1541 | the attributes of a verifiable credential in a verifiable presentation.
1542 | A presentation based on zero-knowledge proof mechanisms only contains
1543 | those attributes and associated values that are required to satisfy
1544 | the presentation requirements.
1545 |         </p>
1546 |         <p>
1547 | Zero-knowledge predicate proofs are a type of proof associated with
1548 | an attribute. Predicate proofs include comparisons, such as
1549 | "greater than", "less than", "not equal", "range",
1550 | "set membership", and "set non-membership".
1551 | Predicate proofs can be constructed without requiring the issuer
1552 | to create special fields, such as
1553 | "age-under-18", "age-over-21", or "age-over-60", in the verifiable credential
1554 | at the time the credential is issued.
1555 | For example, if a holder has a credential with a "birth-date" claim,
1556 | the holder can create a predicate proof based on "birth-date" in the
1557 | verifiable presentation. A predicate value derived from "birth-date" in
1558 | the verifiable credential can cryptographically prove to the verifier that
1559 | the holder's age is greater (or less) than a specified number, without
1560 | revealing the holder's "birth-date".
1561 |         </p>
1562 |         <p>
1563 | Verifiable credentials based on zero-knowledge proof mechanisms are
1564 | also quantum-resistant after presentation.
1565 |         </p>
1566 |         <p>
1567 | Drawbacks of zero-knowledge proof mechanisms include that they are more complex
1568 | and may require larger proofs than some other proof mechanisms.
1569 |         </p>
1570 | 
1571 |     </section>
1572 | 
1573 |     <section>
1574 |       <h2>Progressive Trust</h2>
1575 |       <em>This section is non-normative.</em>
1576 | 
1577 |       <p>
1578 | Entities that use <a>verifiable credentials</a> and
1579 | <a>verifiable presentations</a> should follow protocols that enable progressive
1580 | trust. Progressive trust refers to enabling individuals to share information
1581 | about themselves only on an as needed basis, slowing building up more trust as
1582 | more information is shared with another party.
1583 |       </p>
1584 |       <p>
1585 | Progressive trust is strongly related to the principle of data minimization, and
1586 | enabled by technologies such as selective disclosure and predicate proofs. We
1587 | encourage the use of progressive trust as a guiding principle for implementers
1588 | as they develop protocols for <a>issuers</a>, <a>holders</a>, and
1589 | <a>verifiers</a>.
1590 | 
1591 |       </p>
1592 | 
1593 |       <section>
1594 |         <h3>Data Minimization</h3>
1595 |         <p>
1596 | Data minimization is a principle that encourages <a>verifiers</a> to request the
1597 | minimum amount of data necessary from <a>holders</a>, and for <a>holders</a> to
1598 | only provide the minimum amount of data to <a>verifiers</a>. This "minimum
1599 | amount of data" depends on the situation and may change over the course of a
1600 | <a>holder</a>'s interaction with a <a>verifier</a>.
1601 |         </p>
1602 |         <p>
1603 | For example, a <a>holder</a> may apply for a loan, with a bank acting as the
1604 | <a>verifier</a>. There are several points at which the bank may want to determine
1605 | whether the <a>holder</a> is qualified to continue in the process of applying for
1606 | the loan; for instance, the bank may have a policy of only providing loans to
1607 | existing account holders. A protocol that follows the principle of data
1608 | minimization would allow the <a>holder</a> to reveal to the <a>verifier</a> only
1609 | that they are an existing account holder, before the bank requests any additional
1610 | information, such as account balances or employment status. In this way, the
1611 | applicant may progressively entrust the bank with more information, as the data
1612 | needed by the bank to make its determinations is requested a piece at a time, as
1613 | needed, rather than as a complete set, up front.
1614 |         </p>
1615 |       </section>
1616 | 
1617 |       <section>
1618 |         <h3>Selective Disclosure</h3>
1619 | 
1620 |         <p>
1621 | Selective disclosure is the ability of a <a>holder</a> to select some elements
1622 | of a <a>verifiable credential</a> to share with a <a>verifier</a>, without
1623 | revealing the rest. There are several different methods which support selective
1624 | disclosure, we provide two examples:
1625 |         </p>
1626 |         <ul>
1627 |           <li>
1628 | <b>Atomic Credentials</b> - These are <a>verifiable credentials</a> which
1629 | consist of a single claim. An <a>issuer</a> may provide a set of atomic
1630 | credentials that duplicates the claims of a standard credential. This atomicity
1631 | allows a <a>holder</a> to disclose only those claims which need to be revealed
1632 | to a <a>verifier</a>, rather than requiring all of the claims of a standard
1633 | credential to be revealed.
1634 |           </li>
1635 |           <li>
1636 | <b>Selective Disclosure Signatures</b> - Certain signature schemes natively
1637 | support selective disclosure of <a>verifiable credential</a> claims. One
1638 | example of these is
1639 | <a href="https://groups.csail.mit.edu/cis/pubs/lysyanskaya/cl02b.pdf">Camenisch-Lysyanskaya
1640 | signatures</a>. Such Signatures allow a <a>holder</a> to disclose only those
1641 | claims which need to be revealed to a <a>verifier</a>, rather than requiring
1642 | all of the credential's claims to be revealed.
1643 | 
1644 |           </li>
1645 |         </ul>
1646 |         <p>
1647 | 
1648 |         </p>
1649 | 
1650 |       </section>
1651 |       <section>
1652 |         <h3>Predicates</h3>
1653 |         <p>
1654 | Another technique which may be used to support progressive trust is to use
1655 | predicates as the values of revealed claims. Predicates allow a <a>holder</a> to
1656 | provide True/False values to a <a>verifier</a> rather than revealing claim
1657 | values.
1658 |         </p>
1659 |         <p>
1660 | Predicate proofs may be enabled by <a>verifiable credential</a> <a>issuers</a>
1661 | as claims, e.g., the <a>credentialSubject</a> may include an
1662 | <code>ageOver18</code> <a>property</a> rather than a <code>birthdate</code>
1663 | <a>property</a>. This would allow <a>holders</a> to provide proof that they are
1664 | over 18 without revealing their birthdates.
1665 |         </p>
1666 |         <p>
1667 | Certain signature types enable predicate proofs by allowing claims from a
1668 | standard <a>verifiable credential</a> to be presented as predicates. For
1669 | example, a <a href="https://groups.csail.mit.edu/cis/pubs/lysyanskaya/cl02b.pdf">
1670 | Camenisch-Lysyanskaya signed</a> <a>verifiable credential</a> that contains a
1671 | <code>credentialSubject</code> with a <code>birthdate</code> <a>property</a> may
1672 | be included in a <a>verifiable presentation</a> as a derived credential that
1673 | contains an <code>ageOver18</code> <a>property</a>.
1674 |         </p>
1675 |       </section>
1676 |       <section>
1677 |         <h3>Further Techniques</h3>
1678 |         <p>
1679 | The examples provided in this section are intended to illustrate some possible
1680 | mechanisms for supporting progressive trust, not provide an exhaustive or
1681 | comprehensive list of all the ways progressive trust may be supported. Research
1682 | in this area continues with the use of cutting-edge proof techniques such as
1683 | <a href="https://z.cash/technology/zksnarks/">zk-SNARKS</a> and
1684 | <a href="https://crypto.stanford.edu/bulletproofs/">Bulletproofs</a>, as well as
1685 | different signature protocols.
1686 |         </p>
1687 |         <p>
1688 | A draft report by the <a href="https://www.w3.org/community/credentials/">
1689 | Credentials Community Group</a> on
1690 | <a href="https://w3c-ccg.github.io/data-minimization/">data minimization</a> may
1691 | also be useful reading for implementers looking to enable progressive trust.
1692 |         </p>
1693 |       </section>
1694 |     </section>
1695 | 
1696 |     <section>
1697 |       <h2>Test suite</h2>
1698 | 
1699 |       <em>This section is non-normative.</em>
1700 | 
1701 |       <p>
1702 |         The W3C Verifiable Claims Working Group has produced a
1703 |         <a href="https://github.com/w3c/vc-test-suite/">test suite</a> in order
1704 |         for implementers to confirm their conformance with the current specifications.
1705 |       </p>
1706 |       <p>
1707 |         You can review the <a href="https://w3c.github.io/vc-test-suite/implementations/">current
1708 |         draft implementation report</a>, which contains conformance testing results for submitted
1709 |         implementations supporting the Verifiable Credentials Data Model specification.
1710 |       </p>
1711 |     </section>
1712 |   </body>
1713 | </html>
1714 | 


--------------------------------------------------------------------------------