-
Notifications
You must be signed in to change notification settings - Fork 15
/
index.html
1725 lines (1605 loc) · 70.5 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html>
<html>
<head>
<title>Verifiable Credentials Implementation Guidelines 1.0</title>
<meta http-equiv='Content-Type' content='text/html;charset=utf-8'/>
<!--
=== NOTA BENE ===
For the three scripts below, if your spec resides on dev.w3 you can check them
out in the same tree and use relative links so that they'll work offline,
-->
<script src='https://www.w3.org/Tools/respec/respec-w3c-common' class='remove'></script>
<script src="./common.js" class="remove"></script>
<script type="text/javascript" class="remove">
var respecConfig = {
// specification status (e.g. WD, LCWD, NOTE, etc.). If in doubt use ED.
specStatus: "ED",
// the specification's short name, as in http://www.w3.org/TR/short-name/
shortName: "vc-imp-guide",
// subtitle for the spec
subtitle: "Implementation guidance for Verifiable Credentials",
// if you wish the publication date to be other than today, set this
//publishDate: "2017-08-03",
// if there is a previously published draft, uncomment this and set its YYYY-MM-DD date
// and its maturity status
// previousPublishDate: "1977-03-15",
// previousMaturity: "WD",
// extend the bibliography entries
localBiblio: vcwg.localBiblio,
doJsonLd: true,
github: "https://github.com/w3c/vc-imp-guide",
includePermalinks: false,
// if there a publicly available Editor's Draft, this is the link
edDraftURI: "https://w3c.github.io/vc-imp-guide/",
// if this is a LCWD, uncomment and set the end of its review period
// lcEnd: "2009-08-05",
// editors, add as many as you like
// only "name" is required
editors: [{ name: "Andrei Sambra", url: "https://deiu.me/"}],
// authors, add as many as you like.
// This is optional, uncomment if you have authors as well as editors.
// only "name" is required. Same format as editors.
authors: [{
name: "Manu Sporny", url: "http://manu.sporny.org/",
company: "Digital Bazaar", companyURL: "http://digitalbazaar.com/"
}],
// name of the WG
wg: "Verifiable Claims Working Group",
// URI of the public WG page
wgURI: "https://www.w3.org/2017/vc/",
// name (with the @w3c.org) of the public mailing to which comments are due
wgPublicList: "public-vc-comments",
// URI of the patent status for this WG, for Rec-track documents
// !!!! IMPORTANT !!!!
// This is important for Rec-track documents, do not copy a patent URI from a random
// document unless you know what you're doing. If in doubt ask your friendly neighbourhood
// Team Contact.
wgPatentURI: "https://www.w3.org/2004/01/pp-impl/98922/status",
maxTocLevel: 4,
inlineCSS: true
};
</script>
<style>
pre .highlight {
font-weight: bold;
color: green;
}
pre .subject {
font-weight: bold;
color: RoyalBlue;
}
pre .property {
font-weight: bold;
color: DarkGoldenrod;
}
pre .comment {
font-weight: bold;
color: SteelBlue;
-webkit-user-select: none;
-moz-user-select: none;
-ms-user-select: none;
user-select: none;
}
.supported {
background-color: #93c47d;
}
.missing {
background-color: #e06666;
}
</style>
</head>
<body>
<section id='abstract'>
<p>
This document provides implementation guidance for Verifiable Credentials.
</p>
</section>
<section id='sotd'>
<p>
Comments regarding this document are welcome. Please file issues
directly on <a href="https://github.com/w3c/vc-data-model/issues/">GitHub</a>,
or send them to
<a href="mailto:public-vc-comments@w3.org">public-vc-comments@w3.org</a>
(<a href="mailto:public-vc-comments-request@w3.org?subject=subscribe">subscribe</a>,
<a href="https://lists.w3.org/Archives/Public/public-vc-comments/">archives</a>).
</p>
</section>
<section>
<h2>Introduction</h2>
<em>This section is non-normative.</em>
<p>
This guide provides some examples and resources for implementing
protocols which make use of <a>verifiable credentials</a>, beyond those available in the core specification.
</p>
<p>
It may be useful to first familiarize yourself with the official
<a href="https://www.w3.org/TR/verifiable-claims-use-cases/">Use Cases document</a>,
which offers a concise collection of examples of <a>Verifiable Credentials</a>
as they may appear in everyday life, and how they may be used.
</p>
<p>
The <a href="https://www.w3.org/TR/vc-data-model/">data model specification</a>
contains the technical details about <a>verifiable credentials</a>. However, the
data model specification does not specify any <em>protocols</em> for using
<a>verifiable credentials</a>, nor any <em>proof formats</em> or additional
<em>identifiers</em> upon which such protocols may depend.
</p>
</section>
<section>
<h2>Identifiers</h2>
<em>This section is non-normative.</em>
<p>
When expressing statements about a specific entity, such as a person, product,
or organization, it is often useful to have an identifier for it so that others
can express statements about the same thing. The <a>verifiable credentials</a>
<a href="https://www.w3.org/TR/vc-data-model//">data model specification</a>
contains numerous examples where the identifier is a
<a href="https://w3c-ccg.github.io/did-primer/">decentralized identifier</a>,
also known as a DID. An example of a DID is <code>did:example:123456abcdef</code>.
</p>
<p>
There is currently a proposed charter for a W3C <a href="https://w3c-ccg.github.io/did-wg-charter/">
Decentralized Identifier Working Group</a>, which will put DIDs on track to
become a W3C standard.
</p>
<p class="note">
As of the publication of the <a>verifiable credentials</a>
<a href="https://www.w3.org/TR/vc-data-model/">data model specification</a>,
DIDs are not necessary for <a>verifiable credentials</a> to be useful.
Specifically, <a>verifiable credentials</a> do not depend on <a>DIDs</a> and
<a>DIDs</a> do not depend on <a>verifiable credentials</a>. However, it is
expected that many <a>verifiable credentials</a> will use <a>DIDs</a> and that
software libraries implementing the
<a href="https://www.w3.org/TR/vc-data-model/">data model specification</a>
will benefit from knowing how to resolve <a>DIDs</a>. <a>DID</a>-based URLs may
be used to express identifiers associated with <a>subjects</a>, <a>issuers</a>,
<a>holders</a>, credential status lists, cryptographic keys, and other
machine-readable information associated with a <a>verifiable credential</a>.
</p>
</section>
<section class="informative">
<h2>Terminology</h2>
<div data-include="https://w3c.github.io/vc-data-model/terms.html"
data-oninclude="restrictReferences">
</div>
</section>
<section>
<h2>Verification</h2>
<em>This section is non-normative.</em>
<p>
<a>Verification</a> is the process a <a>verifier</a> or <a>holder</a> performs
when presented with a <a>verifiable presentation</a> or
<a>verifiable credential</a>. <a>Verification</a> includes checking the
presented item against the <a href="https://www.w3.org/TR/vc-data-model/">core
data model</a>, and may also include validating the provided proof section and
checking the item's status.
</p>
<section>
<h3>Core Data Model</h3>
<p>
Conformant tooling that processes Verifiable Credentials will ensure that
the core data model is verified when processing credentials.
</p>
</section>
<section>
<h3>Specific Verifiable Credentials</h3>
<p>
There are many data verification languages, the following approach is one
that should work for most use cases.
</p>
</section>
<section>
<h3>Content Integrity</h3>
<p>
Protecting the integrity of content is an important component of verification.
<a>Verifiers</a> need to have confidence that the content they rely on to
verify <a>credentials</a> doesn't change without their knowledge. This content
may include data schemas, identifiers, public keys, etc.
</p>
<p>
There are a number of ways to provide content integrity protection. A few of
these are described in greater detail below.
</p>
<section>
<h4>Hashlinks</h4>
<p>
<a href="https://tools.ietf.org/html/draft-sporny-hashlink-00">Hashlink URLs</a>
can be used to provide content integrity for links to external resources.
</p>
</section>
<section>
<h4>Verifiable Data Registries</h4>
<p>
A <a>verifiable data registry</a> can also provide content integrity protection.
One example of a <a>verifiable data registry</a> which provides content
integrity protection is a distributed ledger.
</p>
</section>
</section>
</section>
<section>
<h2>Disputes</h2>
<p>
There are at least two different cases to consider where an <a>entity</a>
wants to dispute a <a>credential</a> issued by an <a>issuer</a>:
</p>
<ul>
<li>
A <a>subject</a> disputes a claim made by the <a>issuer</a>. For example, the
<code>address</code> <a>property</a> is incorrect or out of date.
</li>
<li>
An <a>entity</a> disputes a potentially false claim made by the <a>issuer</a>
about a different <a>subject</a>. For example, an imposter has claimed the
social security number for an <a>entity</a>.
</li>
</ul>
<p>
The mechanism for issuing a <code>DisputeCredential</code> is the same as
for a regular <a>credential</a>, except that the <code>credentialSubject</code>
identifier in the <code>DisputeCredential</code> property is the identifier of
the disputed <a>credential</a>.
</p>
<p>
For example, if a <a>credential</a> with an identifier of
<code>https://example.org/credentials/245</code> is disputed, an <a>entity</a>
can issue one of the <a>credentials</a> shown below. In the first example, the
<a>subject</a> might present this to the <a>verifier</a> along with the disputed
<a>credential</a>. In the second example, the <a>entity</a> might publish the
<code>DisputeCredential</code> in a public venue to make it known that the
<a>credential</a> is disputed.
</p>
<pre class="example nohighlight" title="A subject disputes a credential">
{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1"
],
"id": "http://example.com/credentials/123",
"type": ["VerifiableCredential", "DisputeCredential"],
<span class="highlight">"credentialSubject": {
"id": "http://example.com/credentials/245",
"currentStatus": "Disputed",
"statusReason": {
"@value": "Address is out of date",
"@language": "en"
},
}</span>,
"issuer": "https://example.com/people#me",
"issuanceDate": "2017-12-05T14:27:42Z",
"proof": { ... }
}
</pre>
<pre class="example nohighlight" title="Another entity disputes a credential">
{
"@context": "https://w3id.org/credentials/v1",
"id": "http://example.com/credentials/321",
"type": ["VerifiableCredential", "DisputeCredential"],
<span class="highlight">"credentialSubject": {
"id": "http://example.com/credentials/245",
"currentStatus": "Disputed",
"statusReason": {
"@value": "Credential contains disputed statements",
"@language": "en"
},
"disputedClaim": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"address": "Is Wrong"
}
}</span>,
"issuer": "https://example.com/people#me",
"issuanceDate": "2017-12-05T14:27:42Z",
"proof": { ... }
}
</pre>
<p>
In the above <a>verifiable credential</a>, the <a>issuer</a> is claiming that
the address in the disputed <a>verifiable credential</a> is wrong. For example,
the <a>subject</a> might wrongly be claiming to have the same address as that of
the <a>issuer</a>.
</p>
<p class="note">
If a <a>credential</a> does not have an identifier, a content-addressed
identifier can be used to identify the disputed <a>credential</a>. Similarly,
content-addressed identifiers can be used to uniquely identify individual
claims.
</p>
</section>
<section>
<h3>Presentations</h3>
<p>
<a>Verifiable credentials</a> may be presented to a <a>verifier</a> by
using a <a>verifiable presentation</a>. A <a>verifiable presentation</a> can
be targeted to a specific <a>verifier</a> by using a Linked Data Proof
that includes a <code>domain</code> and <code>challenge</code>. This also
helps prevent a <a>verifier</a> from reusing a <a>verifiable presentation</a>
as their own.
</p>
<p>
The <code>domain</code> value can be any string or URI, and the
<code>challenge</code> should be a randomly generated string.
</p>
<p>
The following sample <a>verifiable presentation</a> is for authenticating to
a website, <code>https://example.com</code>.
</p>
<pre class="example nohighlight" title="A targeted verifiable presentation">
{
"@context": [
"https://www.w3.org/2018/credentials/v1"
],
"type": "VerifiablePresentation,
"verifiableCredential": { <span class="comment">...</span> },
"proof": {
"type": "Ed25519Signature2018",
"created": "2019-08-13T15:09:00Z",
<span class="highlight">"challenge": "d1b23d3...3d23d32d2",
"domain": "https://example.com",</span>
"jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..uyW7Hv
VOZ8QCpLJ63wHode0OdgWjsHfJ0O8d8Kfs55dMVEg3C1Z0bYUGV49s8IlTbi3eXsNvM63n
vah79E-lAg",
"proofPurpose": "authentication"
}
}
</pre>
</section>
<section>
<h2>Extensions</h2>
<em>This section is non-normative.</em>
<p>
The Verifiable Credentials Data Model is designed around an <em>open world
assumption</em>, meaning that any entity can say anything about another entity.
This approach enables permissionless innovation; there is no centralized
registry or authority through which an extension author must register
themselves nor the specific data models and vocabularies they create.
</p>
<p>
Instead, credential data model authors are expected to use machine-readable
vocabularies through the use of [LINKED-DATA]. This implementation guide
provides examples for how to express data models using a data format that
is popular with software developers and web page authors called [JSON-LD]. This
data format provides features that enable authors to express their data models
in idiomatic JSON while also ensuring that their vocabulary terms are
unambigiously understood, even by software that does not implement
JSON-LD processing.
</p>
<p>
The Verifiable Credentials data model also uses a graph-based data model,
which allows authors to model both simple relationships that describe
one or more attributes for a single entity and complex multi-entity
relationships.
</p>
<p>
The rest of this section describes how to author extensions that build on
the Verifiable Credentials Data Model.
</p>
<section>
<h3>Creating New Credential Types</h3>
<p>
We expect the most common extensions to the Verifiable Credentials Data Model
to be new credential types. Whenever someone has something to say about one or
more entities and they want their authorship to be verifiable, they should use
a Verifiable Credential. Sometimes there may be an existing credential type,
that someone else has created, that can be reused to make the statements they
want to make. However, there are often cases where new credential types are
needed.
</p>
<p>
New credential types can be created by following a few steps. This guide will
also walk you through creating an example new credential type. At a high level,
the steps to follow are:
</p>
<ol>
<li>
Design the data model.
</li>
<li>
Create a new JSON-LD context.
</li>
<li>
Select a publishing location.
</li>
<li>
Use the new JSON-LD context when issuing new credentials.
</li>
</ol>
<p>
So, let's walk through creating a new credential type which we will
call <code>ExampleAddressCredential</code>. The purpose of this credential
will be to express a person's postal address.
</p>
<h4>Design the data model</h4>
<p>
First, we must design a data model for our new credential type. We know that
we will need to be able to express the basics of a postal address, things
like a person's city, state, and zipcode. Of course, those items are quite
US centric, so we should consider internationalizing those terms. But before
we go further, since we're using [LINKED-DATA] vocabularies, there is a good
chance that commonly known concepts may already have a vocabulary that someone
else has created that we can leverage.
</p>
<p>
If we are going to use someone else's vocabulary, we will want to make sure it
is stable and unlikely to change in any significant way. There may even be
technologies that we can make use of that store immutable vocabularies that
we can reference, but those are not the focus of this example. Here we will
rely on the inertia that comes from a very popularly used vocabulary on the
Web, schema.org. It turns out that this vocabulary has just what we need; it
has already modeled a postal address and even has examples for how to express
it using JSON-LD.
</p>
<p>
Using the schema.org vocabulary and JSON-LD we can express a person's address
like so:
</p>
<pre class="example nohighlight" title="Example schema.org address">
{
<span class="highlight">
"@context": [
"http://schema.org"
]</span>,
"type": "Person",
"address": {
"type": "PostalAddress",
"streetAddress": "123 Main St."
"addressLocality": "Blacksburg",
"addressRegion": "VA",
"postalCode": "24060",
"addressCountry": "US"
}
}
</pre>
<p>
Note the above <code>@context</code> key in the JSON. This <code>@context</code>
refers to a machine-readable file (also expressed in JSON) that provides
term definitions [JSON-LD]. A term definition maps a key or type used in the
JSON, such as <code>address</code> or <code>PostalAddress</code>, to a globally
unique identifier: a URL.
</p>
<p>
This ensures that when software sees the <code>@context</code>
<em>http://schema.org</em>, that it will interpret the the keys and types in the
JSON in a globally consistent way, without requiring developers to use full URLs
in the JSON or in the code that may traverse it. As long as the software is
aware of the specific <code>@context</code> used (or if it uses JSON-LD
processing to transform it to some other known <code>@context</code>), then it
will understand the <em>context</em> in which the JSON was written and meant to
be understood. The use of <code>@context</code> also allows [JSON-LD] keywords
such as <code>@type</code> to be aliased to the simpler <code>type</code> as
is done in the above example.
</p>
<p>
Note that we could also express the JSON using full URLs, if we want to avoid
using <em>@context</em>. Here is what the example would look like if we did
that:
</p>
<pre class="example nohighlight" title="Example schema.org address with full URLs">
{
"@type": "http://schema.org/Person",
"http://schema.org/address": {
"@type": "http://schema.org/PostalAddress",
"http://schema.org/streetAddress": "123 Main St."
"http://schema.org/addressLocality": "Blacksburg",
"http://schema.org/addressRegion": "VA",
"http://schema.org/postalCode": "24060",
"http://schema.org/addressCountry": "US"
}
}
</pre>
<p>
While this form is an acceptable way to express the information such that it is
unambiguous, many software developers would prefer to use more idiomatic JSON.
The use of <code>@context</code> enables idiomatic JSON without losing global
consistency and without the need for a centralized registry or authority for
creating extensions. Note that <code>@context</code> can also have more than
one value. In this case, a JSON array is used to express multiple values, where
each value references another context that defines terms. Using this mechanism
we can first bring in the terms defined in the Verifiable Credentials Data Model
specification and then bring in the terms defined by schema.org:
</p>
<pre class="example nohighlight" title="Example address credential with schema.org context">
{
<span class="highlight">
"@context": [
"https://www.w3.org/2018/credentials/v1",
"http://schema.org"
]</span>,
...
"credentialSubject": {
"type": "Person",
"address": {
"type": "PostalAddress",
"streetAddress": "123 Main St."
"addressLocality": "Blacksburg",
"addressRegion": "VA",
"postalCode": "24060",
"addressCountry": "US"
}
},
...
}
</pre>
<p>
Note, however, that each <em>context</em> might have a different definition for
the same term, e.g., the JSON key <code>address</code> might map to a different
URL in each <em>context</em>. By default, [JSON-LD] allows terms in a
<code>@context</code> to be redefined using a <em>last term wins</em>
order. While these changes can be safely dealt with by using JSON-LD
processing, we want to lower the burden on consumers of Verifiable Credentials.
We want consumer software to be able to make assumptions about the meaning of
terms by only having to read and understand the string value associated with
the <code>@context</code> key. We don't want them to have to worry about terms
being redefined in unexpected ways. That way their software can inspect only
the <code>@context</code> values and then be hard coded to understand the
meaning of the terms.
</p>
<p>
In order to prevent term redefinition, the [JSON-LD] <code>@protected</code>
feature must be applied to term definitions in the <code>@context</code>. All
terms in the core Verifiable Credentials <code>@context</code> are
already protected in this way. The only time that an existing term is allowed
to be redefined is if the new definition is scoped underneath another new term
that is defined in a <em>context</em>. This matches developer expectations and
ensures that consumer software has strong guarantees about the semantics of the
data it is processing; it can be written such that it is never confused about
the definition of a term. Note that consumers must determine their own risk
profile for how to handle any credentials their software processes that include
terms that it does not understand.
</p>
<h4>Create a new JSON-LD context</h4>
<p>
Given the above, there is at least one reason why we don't want to use
the schema.org <em>context</em>: it is designed to be very flexible and thus
does not use the <code>@protected</code> feature. There are a few additional
reasons we want to create our own [JSON-LD] context though. First, the
schema.org context does not define our new credential type:
<em>ExampleAddressCredential</em>. Second, it is not served via a secure
protocol (e.g., <em>https</em>); rather, it uses <em>http</em>. Note that this
is less of a concern than it may seem, as it is recommended that all Verifiable
Credential consumer software hard code the <code>@context</code> values it
understands and not reach out to the Web to fetch them. Lastly, it is a very
large context, containing many more term definitions than are necessary for our
purposes.
</p>
<p>
So, we will create our own [JSON-LD] context that expresses just those term
definitions that we need for our new credential type. Note that this does not
mean that we must mint new URLs; we can still reuse the schema.org vocabulary
terms. All we are doing is creating a more concise and targeted context. Here's
what we'll need in our context:
</p>
<pre class="example nohighlight" title="Example address credential context">
{
"@version": 1.1,
"@protected": true,
"ExampleAddressCredential":
"https://example.org/ExampleAddressCredential",
"Person": {
"@id": "http://schema.org/Person",
"@context": {
"@version": 1.1,
"@protected": true,
"address": "http://schema.org/address"
}
},
"PostalAddress": {
"@id": "http://schema.org/PostalAddress",
"@context": {
"@version": 1.1,
"@protected": true,
"streetAddress": "http://schema.org/streetAddress",
"addressLocality": "http://schema.org/addressLocality",
"addressRegion": "http://schema.org/addressRegion",
"postalCode": "http://schema.org/postalCode",
"addressCountry": "http://schema.org/addressCountry"
}
}
}
</pre>
<p>
The above context defines a term for our new credential type
<em>ExampleAddressCredential</em>, mapping it to the URL
<em>https://example.org/ExampleAddressCredential</em>. We could have also
chosen a URI like <em>urn:private-example:ExampleAddressCredential</em>, but
this approach would not allow us to serve up a Web page to describe it, if we
so desire. The context also defines the terms for types <em>Person</em> and
<em>PostalAddress</em>, mapping them to their schema.org vocabulary URLs.
Furthermore, when those types are used, it also defines protected terms for
each of them via a <em>scoped context</em>, mapping terms like <em>address</em>
and <em>streetAddress</em> to their schema.org vocabulary URLs. For more
information on how to write a JSON-LD context or <em>scoped contexts</em>, see
the [JSON-LD] specification.
</p>
<h4>Select a publishing location</h4>
<p>
Now that we have a [JSON-LD] context, we must give it a URL. Technically
speaking, we could just use a URI, for example, a private URN such as
<em>urn:private-example:my-extension</em>. However, if we want people to be
able to read and discover it on the Web, we should give it a URL like
<em>https://example.org/example-address-credential-context/v1</em>.
</p>
<p>
When this URL is dereferenced, it should return
<em>application/ld+json</em> by default, to allow JSON-LD processors to process
the context. However, if a user agent requests <em>HTML</em>, it should return
human readable text that explains, to humans, what the term definitions are and
what they map to. Since we're reusing an existing vocabulary, schema.org, we
can also simply link to the definitions of the meaning of our types and terms
via their website. If we had created our own new vocabulary terms, we would
describe them on our own site, ideally including machine readable Information
as well.
</p>
<h4>Use the new JSON-LD context when issuing new credentials</h4>
<p>
Now we're ready for our context to be used by anyone who
wishes to issue an <em>ExampleAddressCredential</em>!
</p>
<pre class="example nohighlight" title="Example address credential with schema.org context">
{
<span class="highlight">
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://example.org/example-address-credential-context/v1"
]</span>,
"id": "https://example.org/credentials/1234",
"type": "ExampleAddressCredential",
"issuer": "https://example.org/people#me",
"issuanceDate": "2017-12-05T14:27:42Z",
"credentialSubject": {
"id": "did:example:1234",
"type": "Person",
"address": {
"type": "PostalAddress",
"streetAddress": "123 Main St."
"addressLocality": "Blacksburg",
"addressRegion": "VA",
"postalCode": "24060",
"addressCountry": "US"
}
},
"proof": { ... }
}
</pre>
<p>
Note that writing this new credential type requires permission from no one,
you must only adhere to the above referenced standards.
</p>
</section>
<section>
<h3>Human Readability</h3>
<p>
The JSON-LD Context declaration mechanism is used by implementations to
signal the context in which the data transmission is happening to consuming
applications:
</p>
<pre class="example nohighlight" title="Use of @context mechanism">
{
<span class="highlight">
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1"
]</span>,
"id": "http://example.edu/credentials/1872",
...
</pre>
<p>
Extension authors are urged to publish two types of information at the
context URLs. The first type of information is for machines, and is the
machine-readable JSON-LD Context. The second type of information is for
humans, and should be an HTML document. It is suggested that the default
mode of operation is to serve the machine-readable JSON-LD Context as that is
the primary intended use of the URL. If content-negotiation is supported,
requests for <code>text/html</code> should result in a human readable document.
The human readable document should at least contain usage information for the
extension, such as the expected order of URLs associated with the
<code>@context</code> property, specifications that elaborate on the extension,
and examples of typical usage of the extension.
</p>
</section>
</section>
<section>
<h2>Proof Formats</h2>
<em>This section is non-normative.</em>
<p>
The <a>verifiable credentials</a>
<a href="https://w3c.github.io/vc-data-model/">data model </a> is designed to be
proof format agnostic. <a href="https://w3c.github.io/vc-data-model/">The
specification</a> does not normatively require any particular digital proof or
signature format. While the data model is the canonical representation of a
<a>verifiable credential</a> or <a>verifiable presentation</a>, the proving
mechanisms for these are often tied to the syntax used in the transmission of
the document between parties. As such, each proofing mechanism has to specify
whether the validation of the proof is calculated against the state of the
document as transmitted, against the transformed data model, or against another
form. At the time of publication, at least two proof formats are being actively
utilized by implementers, and the Working Group felt that documenting what these
proof formats are and how they are being used would be beneficial to other
implementers.
</p>
<p>
This guide provides tables in section <a href="#pf1b">Benefits of JWTs</a> and
section <a href="#pf1b">Benefits of JSON-LD and LD-Proofs</a> that compare three
syntax and proof format ecosystems; JSON+JWTs, JSON-LD+JWTs, and
JSON-LD+LD-Proofs.
</p>
<p>
Because the Verifiable Credentials Data Model is extensible, and agnostic to any
particular proof format, the specification and use of additional proof formats
is supported.
</p>
<section>
<h3>Benefits of JWTs</h3>
<p>
The Verifiable Credentials Data Model is designed to be compatible with a
variety of existing and emerging syntaxes and digital proof formats. Each
approach has benefits and drawbacks. The following table is intended to
summarize a number of these native trade-offs.
</p>
<p>
The table below compares three syntax and proof format ecosystems; JSON+JWTs,
JSON-LD+JWTs, and JSON-LD+LD-Proofs.
</p>
<table class="simple" id="#pfatable">
<thead>
<tr>
<th style="text-align: center;">Feature</th>
<th style="text-align: center;">JSON<br>+<br>JWTs</th>
<th style="text-align: center;">JSON‑LD<br>+<br>JWTs</th>
<th style="text-align: center;">JSON‑LD<br>+<br>LD‑Proofs</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<a href="#pf1a">PF1a.</a> Proof format supports Zero-Knowledge Proofs.
</td>
<td class="supported">✓</td>
<td class="supported">✓</td>
<td class="supported">✓</td>
</tr>
<tr>
<td>
<a href="#pf2a">PF2a.</a> Proof format supports arbitrary proofs such as Proof
of Work, Timestamp Proofs, and Proof of Stake.
</td>
<td class="supported">✓</td>
<td class="supported">✓</td>
<td class="supported">✓</td>
</tr>
<tr>
<td>
<a href="#pf3a">PF3a.</a> Based on existing official standards.
</td>
<td class="supported">✓</td>
<td class="missing">✖</td>
<td class="missing">✖</td>
</tr>
<tr>
<td>
<a href="#pf4a">PF4a.</a> Designed to be small in size.
</td>
<td class="supported">✓</td>
<td class="missing">✖</td>
<td class="missing">✖</td>
</tr>
<tr>
<td>
<a href="#pf5a">PF5a.</a> Offline support without further processing.
</td>
<td class="supported">✓</td>
<td class="missing">✖</td>
<td class="missing">✖</td>
</tr>
<tr>
<td>
<a href="#pf6a">PF6a.</a> Wide adoption in other existing standards.
</td>
<td class="supported">✓</td>
<td class="supported">✓</td>
<td class="missing">✖</td>
</tr>
<tr>
<td>
<a href="#pf7a">PF7a.</a> No type ambiguity.
</td>
<td class="supported">✓</td>
<td class="missing">✖</td>
<td class="missing">✖</td>
</tr>
<tr>
<td>
<a href="#pf8a">PF8a.</a> Broad library support.
</td>
<td class="supported">✓</td>
<td class="missing">✖</td>
<td class="missing">✖</td>
</tr>
<tr>
<td>
<a href="#pf9a">PF9a.</a> Easy to understand what is signed.
</td>
<td class="supported">✓</td>
<td class="supported">✓</td>
<td class="missing">✖</td>
</tr>
<tr>
<td>
<a href="#pf10a">PF10a.</a> Ability to be used as authn/authz token with existing systems.
</td>
<td class="supported">✓</td>
<td class="supported">✓</td>
<td class="missing">✖</td>
</tr>
<tr>
<td>
<a href="#pf11a">PF11a.</a> No additional canonicalization required.
</td>
<td class="supported">✓</td>
<td class="missing">✖</td>
<td class="missing">✖</td>
</tr>
<tr>
<td>
<a href="#pf12a">PF12a.</a> No Internet PKI required.
</td>
<td class="supported">✓</td>
<td class="missing">✖</td>
<td class="missing">✖</td>
</tr>
<tr>
<td>
<a href="#pf13a">PF13a.</a> No resolution of external documents needed.
</td>
<td class="supported">✓</td>
<td class="missing">✖</td>
<td class="missing">✖</td>
</tr>
</tbody>
</table>
<p class="note">
Some of the features listed in the table above are debateable, since a feature
can always be added to a particular syntax or digital proof format. The table
is intended to identify native features of each combination such that no
additional language design or extension is required to achieve the identified
feature. Features that all languages provide, such as the ability to express
numbers, have not been included for the purposes of brevity. Find more information
about different proof formats in the next section.
</p>
<dl>
<dt id="pf1a">
PF1a: Proof format supports Zero-Knowledge Proofs.
</dt>
<dd>
JWTs can embed `proof` attributes for repudiable proofs such as Zero-Knowledge Proofs.
In that case, the JWS will not have an signature element.
</dd>
<dt id="pf2a">
PF2a: Proof format supports arbitrary proofs such as Proof of Work, Timestamp
Proofs, and Proof of Stake.
</dt>
<dd>
JWTs can embed `proof` attributes for any type of proofs such as Proof of Work, Timestamp,
Proofs, and Proof Stake.
</dd>
<dt id="pf3a">
PF3a: Based on existing official standards.
</dt>
<dd>
JSON and JWT are proposed and mature IETF standards. While JSON-LD 1.0 is in
REC state in W3C, JSON-LD 1.1 is still in WD state. LD-Proofs are not standardized at all.
</dd>
<dt id="pf4a">
PF4a: Designed to be small in size.
</dt>
<dd>
JSON was invented as a simple data format to be transmitted on the wire. A verifiable credential
can be expressed by its attributes only, without the necessity to introduce additional meta-information
such as @context. This makes the resulting JSON+JWT credential typically also smaller in size.
</dd>
<dt id="pf5a">
PF5a: Offline support without further processing.
</dt>
<dd>
A JWT can fully describe itself without the need to retrieve or verify any external documents.
JSON-LD requires the context to be queryable and requires further documents to be accessible