-
Notifications
You must be signed in to change notification settings - Fork 8
/
index.html
1372 lines (1366 loc) · 66.3 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>
<meta http-equiv='Content-Type' content='text/html;charset=utf-8'/>
<title>Verifiable Credentials JSON Schema Specification</title>
<script
src="https://www.w3.org/Tools/respec/respec-w3c"
class="remove"
defer
></script>
<script class="remove"
src="https://cdn.jsdelivr.net/gh/transmute-industries/respec-vc-jwt@5e316347f68a638e10539bb1655a2d2c7ee49ebf/dist/main.js"></script>
<script src="./common.js" class="remove"></script>
<script class="remove">
var respecConfig = {
specStatus: "CR",
implementationReportURI: "https://w3c.github.io/vc-json-schema-test-suite/",
crEnd: "2024-01-17",
group: "vc",
shortName: "vc-json-schema",
subtitle: "JSON Schemas for Verifiable Credentials",
previousMaturity: "FPWD",
previousPublishDate: "2023-05-23",
localBiblio: vcwg.localBiblio,
doJsonLd: true,
xref: true,
github: "https://github.com/w3c/vc-json-schema/",
includePermalinks: false,
edDraftURI: "https://w3c.github.io/vc-json-schema/",
testSuiteURI: "https://github.com/w3c/vc-json-schema-test-suite",
editors: [{
name: "Gabe Cohen",
url: "https://github.com/decentralgabe",
company: "Block",
companyURL: "https://www.tbd.website",
w3cid: 116851
}, {
name: 'Mike Prorock',
url: 'https://github.com/mprorock',
company: 'mesur.io',
companyURL: 'https://mesur.io/',
w3cid: 130636
}, {
name: 'Andres Uribe',
url: 'https://github.com/andresuribe',
company: "Block",
companyURL: "https://www.tbd.website",
w3cid: 140850
}],
authors: [{
name: "Gabe Cohen",
url: "https://github.com/decentralgabe",
company: "Block",
companyURL: "https://www.tbd.website",
w3cid: 116851
}],
formerEditors: [{
name: "Orie Steele",
company: "Transmute",
companyURL: "https://transmute.industries",
w3cid: 109171,
}],
lint: {
"no-unused-dfns": false
},
// TODO(gabe): this is broken
// postProcess: [restrictRefs],
maxTocLevel: 2,
inlineCSS: true,
postProcess: [window.respecVc.createVcExamples],
otherLinks: [{
key: "Related Documents",
data: [{
value: "Verifiable Credentials Data Model",
href: "https://www.w3.org/TR/vc-data-model/"
}]
}]
};
</script>
<style>
pre .highlight {
font-weight: bold;
color: green;
}
pre .comment {
font-weight: bold;
color: Gray;
}
.color-text {
font-weight: bold;
text-shadow: -1px 0 black, 0 1px black, 1px 0 black, 0 -1px black;
}
ol.algorithm {
counter-reset: numsection;
list-style-type: none;
}
ol.algorithm li {
margin: 0.5em 0;
}
ol.algorithm li:before {
font-weight: bold;
counter-increment: numsection;
content: counters(numsection, ".") ") ";
}
</style>
</head>
<body>
<section id='abstract'>
<h2>Abstract</h2>
<p>
Among other things, the [[VC-DATA-MODEL-2.0]] specifies the models used for Verifiable Credentials,
Verifiable Presentations, and explains the relationships between three parties:
<i>issuers</i>, <i>holders</i>, and <i>verifiers</i>. Verifiability, extensibility, and semantic
interoperability are critical pieces of functionality referenced throughout
the [[VC-DATA-MODEL-2.0]]. This specification provides a mechanism to make use of a Credential Schema in
<a>Verifiable Credential</a>, leveraging the existing
<a data-cite="VC-DATA-MODEL-2.0/#data-schemas">Data Schemas</a> concept.
</p>
</section>
<section id='sotd'>
<h2>Status of This Document</h2>
<p>
The Working Group is actively seeking implementation feedback for this
specification. In order to exit the Candidate Recommendation phase, the
Working Group has set the requirement of at least two independent
implementations for each mandatory feature in the specification. For details
on the conformance testing process, see the test suites listed in the
<a href="https://w3c.github.io/vc-json-schema-test-suite/">
implementation report</a>.
</p>
</section>
<section class="informative">
<h2>Introduction</h2>
<p>
This specification provides a mechanism for the use of <a>JSON Schemas</a> with
<a>Verifiable Credentials</a>. A significant part of the integrity of a <a>Verifiable Credential</a>
comes from the ability to structure its contents so that all three parties —
issuer, holder, verifier — may have a consistent mechanism of trust in
interpreting the data that they are provided with. We introducing a new data
model for an object to facilitate backing Credentials with <a>JSON Schemas</a>
that we call a <a>Credential Schema</a>.
</p>
<p>
This specification provides a standardized way of creating <a>Credential Schemas</a>
to be used in credentialing systems. Credential Schemas may apply to any portion
of a Verifiable Credential. Multiple JSON Schemas may back a single Verifiable Credential,
e.g. a schema for the `credentialSubject` and another for other credential properties.
</p>
<section class="informative">
<h3>Terminology</h3>
<div data-include="terms.html"></div>
</section>
<section id="conformance" class="normative">
</section>
</section>
<section class="normative">
<h2>Data Model</h2>
<p>
The following sections outline the data models for this document, of which there are two:
<code>JsonSchema</code> for usage of a [[JSON-SCHEMA]] directly in a <code>credentialSchema</code>
property, and <code>JsonSchemaCredential</code> for usage of a [[JSON-SCHEMA]] represented as a
<a>verifiable credential</a>.
</p>
<p>
Implementers MAY package a [[JSON-SCHEMA]] as a <a>verifiable credential</a> when they wish to
leverage features of the [[VC-DATA-MODEL-2.0]], answering questions such as:
<ul>
<li>Who is the author of this schema? (provided by the <code>issuer</code> property)</li>
<li>Is it schema still valid? (provided by the <code>validFrom</code>, <code>validUntil</code>, and <code>credentialStatus</code> properties)</li>
<li>Has the schema been tampered with? (provided by <a data-cite="VC-DATA-MODEL-2.0/#securing-verifiable-credentials">
Securing Verifiable Credentials</a>)</li>
</ul>
</p>
<section class="normative">
<h3>JsonSchema</h3>
<p>
This term is part of the
<a href="https://www.w3.org/2018/credentials/#JsonSchema">Verifiable Credentials Vocabulary v2.0</a>.
</p>
<p>
<b>JsonSchema</b> is used for the validation of W3C Verifiable Credentials using
JSON Schema. When dereferencing the <code>id</code> property associated with the
<code>JsonSchema</code> <code>type</code> value the result is a valid JSON
Schema document according to its specification version.
<p>
The specification version of [[JSON-SCHEMA]] can be any version noted in the section
on <a href="#json-schema-specifications">JSON Schema Specifications</a>.
</p>
<p>
<table class="simple">
<thead>
<tr>
<th>Property</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>id</td>
<td>The constraints on the <code>id</code> property are listed in the Verifiable Credentials
Data Model specification [[VC-DATA-MODEL-2.0]]. The value MUST be a URL that identifies
the schema associated with the <a>verifiable credential</a>.</td>
</tr>
<tr>
<td>type</td>
<td>The <code>type</code> property MUST be <code>JsonSchema</code>.</td>
</tr>
</tbody>
</table>
</p>
<p class="note" title="Restriction on the use of the jsonSchema property">
The <code><a href="#jsonschema-0">jsonSchema</a></code> property is only to be used
when the <code>JsonSchema</code> class instance is the object of the <code>credentialSubject</code>
property within a <code><a href="#jsonschemacredential">JsonSchemaCredential</a></code> instance.
</p>
<p>
An example of utilizing the VC Data Model's <code>credentialSchema</code>
is provided below:
<pre class="example vc-jose-cose-vc-example" title="Example JsonSchema">
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://www.w3.org/ns/credentials/examples/v2"
],
"id": "https://example.com/credentials/3732",
"type": ["VerifiableCredential", "EmailCredential"],
"issuer": "https://example.com/issuers/14",
"issuanceDate": "2010-01-01T19:23:24Z",
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"emailAddress": "[email protected]"
},
"credentialSchema": {
"id": "https://example.com/schemas/email.json",
"type": "JsonSchema"
}
}
</pre>
</p>
<p>
<p>
Upon dereferencing the value of the <code>id</code> <code>https://example.com/schemas/email.json</code>,
a process also be referred to as <a>schema resolution</a>, the following JSON Schema
document is returned:
</p>
<pre class="example" title="Example Email JSON Schema">
{
"$id": "https://example.com/schemas/email.json",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "EmailCredential",
"description": "EmailCredential using JsonSchema",
"type": "object",
"properties": {
"credentialSubject": {
"type": "object",
"properties": {
"emailAddress": {
"type": "string",
"format": "email"
}
},
"required": [
"emailAddress"
]
}
}
}
</pre>
</p>
</section>
<section class="normative">
<h3>JsonSchemaCredential</h3>
<p>
This term is part of the
<a href="https://www.w3.org/2018/credentials/#JsonSchemaCredential">Verifiable Credentials Vocabulary v2.0</a>.
</p>
<p>
<b>JsonSchemaCredential</b> is used for the validation of W3C Verifiable Credentials using
JSON Schema, where the JSON Schema is contained with a <a>verifiable credential</a>.
When dereferencing the <code>id</code> property associated with the
<code>credentialSchema</code> <code>type</code> value, the result is a valid
<a>verifiable credential</a>. For the resulting <a>verifiable credential</a>:
<p>
<ul>
<li>
The <code>credentialSubject</code> property MUST contain two properties:
<ul>
<li><code>type</code> – the value of which MUST be <code>JsonSchema</code></li>
<li><a href="#jsonschema-0"><code>jsonSchema</code></a> – an object which contains a valid JSON Schema</li>
</ul>
</li>
<li>
The value of the <code>credentialSchema</code> property MUST always be set to:
<pre title="Value of a JsonSchemaCredential's credentialSchema property">
{
"id": "https://www.w3.org/2022/credentials/v2/json-schema-credential-schema.json",
"type": "JsonSchema",
"digestSRI": "sha384-S57yQDg1MTzF56Oi9DbSQ14u7jBy0RDdx0YbeV7shwhCS88G8SCXeFq82PafhCrW"
}
</pre>
<p class="issue" title="Hash values might change during Candidate Recommendation">
The hash value of the <code>digestSRI</code> property might change during the Candidate Recommendation
phase based on implementer feedback that requires the referenced files to be modified.
</p>
</li>
</ul>
<p>
Any version of [[JSON-SCHEMA]] in the section on
<a href="#json-schema-specifications">JSON Schema Specifications</a>
can be used.
</p>
<p>
<table class="simple">
<thead>
<tr>
<th>Property</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>id</td>
<td>The constraints on the <code>id</code> property are listed in the Verifiable Credentials
Data Model specification [[VC-DATA-MODEL-2.0]]. The value MUST be a URL that identifies
the <a>verifiable credential</a> which contains a credential schema.</td>
</tr>
<tr>
<td>type</td>
<td>The <code>type</code> property MUST be <code>JsonSchemaCredential</code>.</td>
</tr>
<tr>
<td>credentialSubject.id</td>
<td>The <code>credentialSubject</code>'s <code>id</code> property MUST follow the guidance
provided for <a data-cite="VC-DATA-MODEL-2.0/#identifiers">identifiers</a> in the [[VC-DATA-MODEL-2.0]]
specification.</td>
</tr>
<tr>
<td>credentialSubject.type</td>
<td>The <code>credentialSubject</code>'s <code>type</code> property MUST be
<a href="#jsonschema">JsonSchema</a>.</td>
</tr>
<tr>
<td>credentialSubject.jsonSchema</td>
<td>The <code>credentialSubject</code> MUST use the <code>jsonSchema</code> property to
represent a valid [[JSON-SCHEMA]].</td>
</tr>
</tbody>
</table>
</p>
An example of utilizing the VC Data Model's <code>credentialSchema</code>
is provided below:
<pre class="example vc-jose-cose-vc-example" title="Example JsonSchemaCredential">
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://www.w3.org/ns/credentials/examples/v2"
],
"id": "https://example.com/credentials/3733",
"type": ["VerifiableCredential", "ExampleEmailCredential"],
"issuer": "https://example.com/issuers/14",
"issuanceDate": "2010-01-01T19:23:24Z",
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"emailAddress": "[email protected]"
},
"credentialSchema": {
"id": "https://example.com/credentials/3734",
"type": "JsonSchemaCredential"
}
}
</pre>
</p>
<p>
<p>
Upon dereferencing the value of the <code>id</code> <code>https://example.com/credentials/3734</code>,
a process also be referred to as <a>schema resolution</a>, the following verifiable credential,
representing a JSON Schema, is returned:
</p>
<pre class="example vc-jose-cose-vc-example" title="Example Email Credential Schema">
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://www.w3.org/ns/credentials/examples/v2"
],
"id": "https://example.com/credentials/3734",
"type": ["VerifiableCredential", "JsonSchemaCredential"],
"issuer": "https://example.com/issuers/14",
"issuanceDate": "2010-01-01T19:23:24Z",
"credentialSchema": {
"id": "https://www.w3.org/2022/credentials/v2/json-schema-credential-schema.json",
"type": "JsonSchema",
"digestSRI": "sha384-S57yQDg1MTzF56Oi9DbSQ14u7jBy0RDdx0YbeV7shwhCS88G8SCXeFq82PafhCrW"
},
"credentialSubject": {
"id": "https://example.com/schemas/email-credential-schema.json",
"type": "JsonSchema",
"jsonSchema": {
"$id": "https://example.com/schemas/email-credential-schema.json",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "EmailCredential",
"description": "EmailCredential using JsonSchemaCredential",
"type": "object",
"properties": {
"credentialSubject": {
"type": "object",
"properties": {
"emailAddress": {
"type": "string",
"format": "email"
}
},
"required": ["emailAddress"]
}
}
}
}
}
</pre>
</p>
<section class="normative">
<h4>jsonSchema</h4>
<p>
This term is part of the
<a href="https://www.w3.org/2018/credentials/#jsonSchema">Verifiable Credentials Vocabulary v2.0</a>.
</p>
<p><b>jsonSchema</b> enables the use of the <code>jsonSchema</code> property
within the <code>credentialSubject</code> of a verifiable credential. The term is
intended to be used with the <a href="#jsonschemacredential"></a> type only. The value of
the <code>jsonSchema</code> property MUST be a valid [[JSON-SCHEMA]].
</p>
<p>
<pre class="example jsonschemacredential-jsonschema nohighlight" title="Example JsonSchema Credential with jsonSchema">
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://www.w3.org/ns/credentials/examples/v2"
],
"id": "https://example.com/credentials/3734",
"type": ["VerifiableCredential", "JsonSchemaCredential"],
"issuer": "https://example.com/issuers/14",
"issuanceDate": "2010-01-01T19:23:24Z",
"credentialSchema": {
"id": "https://www.w3.org/2022/credentials/v2/json-schema-credential-schema.json",
"type": "JsonSchema",
},
"credentialSubject": {
"id": "https://example.com/schemas/favorite-color-schema.json",
"type": "JsonSchema",
<span class="highlight"> "jsonSchema": {
"$id": "https://example.com/schemas/favorite-color-schema.json",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "Favorite Color Schema",
"description": "Favorite Color using JsonSchemaCredential",
"type": "object",
"properties": {
"credentialSubject": {
"type": "object",
"properties": {
"favoriteColor": {
"type": "string"
"enum": ["red", "orange", "green", "blue", "yellow", "purple"]
}
},
"required": ["favoriteColor"]
}
}
}
</span>
}
}
</pre>
</p>
</section>
</section>
</section>
<section class="normative">
<h2>JSON Schema Specifications</h2>
<p>
The following section describes the allowed specifications for
using a [[JSON-SCHEMA]] with a <a>credential schema</a>.
</p>
<p>
To promote conformance and enable interoperability, implementers MUST
provide support for JSON Schema specifications where, in the following table,
the <i>required</i> column's value is <b>yes</b>.
</p>
<table class="simple">
<thead>
<tr>
<th style="white-space: nowrap">JSON Schema Specification</th>
<th>Date of Publication</th>
<th>$schema URI</th>
<th>Required</th>
</tr>
</thead>
<tbody>
<tr>
<td>[[JSON-SCHEMA-2020-12]]</td>
<td>10 June 2022</td>
<td><a href="https://json-schema.org/draft/2020-12/schema">https://json-schema.org/draft/2020-12/schema</a></td>
<td>Yes</td>
</tr>
<tr>
<td>[[?JSON-SCHEMA-2019-09]]</td>
<td>19 March 2020</td>
<td><a href="https://json-schema.org/draft/2019-09/schema">https://json-schema.org/draft/2019-09/schema</a></td>
<td>No</td>
</tr>
<tr>
<td>[[?JSON-SCHEMA-DRAFT-7]]</td>
<td>20 September 2018</td>
<td><a href="http://json-schema.org/draft-07/schema#">http://json-schema.org/draft-07/schema#</a></td>
<td>No</td>
</tr>
</tbody>
</table>
<p class="note" title="A stable JSON Schema specification is coming">
<a href="https://json-schema.org/blog/posts/future-of-json-schema">A stable JSON Schema specification</a>
is in the works. When it's released, we intend to update this table to require the stable version.
</p>
<section class="normative">
<h3>Reserved Keywords</h3>
<p>
JSON Schema specifications reserve certain keywords that hold specific meanings and
functions during the processing of JSON Schemas. It is crucial to avoid using conflicting
keys when creating JSON Schemas. The specification document for each version of JSON Schema
lists these reserved keywords, which can be found in the table provided above.
</p>
<p>
In the upcoming sections we list <i>some</i> keywords that possess unique significance in
[[JSON-SCHEMA]] documents and SHOULD NOT be used in conflicting ways, such as redefining
these keywords, or using them in a manner other than as noted by [[JSON-SCHEMA]] specifications.
</p>
<p>
Furthermore, we identify specific keywords, that are not explicitly defined by JSON Schema,
but are emphasized in this specification to support widespread usage.
</p>
<section class="normative">
<h4>$id</h4>
<p>
Across JSON Schema specifications, the <code>$id</code> keyword identifies a schema resource
with its canonical URI. The <code>$id</code> MUST be present, and its value MUST represent
a valid URI-reference as specified by the associated [[JSON-SCHEMA]] version.
</p>
<p>
It is RECOMMENDED that the value of the <code>$id</code> property match the <code>id</code>
value in the <code>credentialSchema</code> object of a <a>verifiable credential</a>, and
that the value of the <code>$id</code> is a dereferenceable <a>URL</a>.
</p>
</section>
<section class="normative">
<h4>$schema</h4>
<p>
Across JSON Schema specifications, the <code>$schema</code> keyword identifies a JSON Schema
providing the feature set for a given JSON Schema specification. This property MUST be present
in each schema. For example, when constructing a schema for <i>Draft 2020-12</i> the value of
the <code>$schema</code> identifier MUST be <code>https://json-schema.org/draft/2020-12/schema</code>.
</p>
</section>
<section class="normative">
<h4><dfn>title</dfn></h4>
<p>
It is RECOMMENDED that all JSON Schemas include the optional <code>title</code> property as defined in
[[JSON-SCHEMA]].
</p>
</section>
<section class="normative">
<h4><dfn>description</dfn></h4>
<p>
It is RECOMMENDED that all JSON Schemas include the optional <code>description</code> property as
defined in [[JSON-SCHEMA]].
</p>
</section>
<section class="normative">
<h4>lang</h4>
<p>
JSON Schemas SHOULD choose to include an optional <code>lang</code> property that indicates the
<a data-cite="i18n-glossary/#dfn-language-tag">language tag</a> for the values of the [=title=] and
[=description=] properties defined in the JSON Schema. The value of this field MUST be a
<a data-cite="i18n-glossary/#dfn-canonical-unicode-locale-identifier">canonical unicode locale identifier</a>.
When absent, implementers MUST assume that the value of this property is `und`.
</p>
</section>
<section class="normative">
<h4>dir</h4>
<p>
JSON Schemas SHOULD choose to include an optional <code>dir</code> property that indicates the
<a data-cite="i18n-glossary/#dfn-base-direction">base direction</a> for the values of the [=title=] and [=description=] properties defined in
the JSON Schema. The value of this property MUST be a <a>text-direction</a>. When absent, implementers
MUST assume that the value of this property is "[=text-direction/auto=]".
</p>
<p>
The <dfn>text-directions</dfn> are the following:
</p>
<dl>
<dt>
"<dfn data-dfn-for="text-direction">ltr</dfn>"
</dt>
<dd>
Left-to-right text.
</dd>
<dt>
"<dfn data-dfn-for="text-direction">rtl</dfn>"
</dt>
<dd>
Right-to-left text.
</dd>
<dt>
"<dfn data-dfn-for="text-direction">auto</dfn>" (default)
</dt>
<dd>
No explicit directionality.
</dd>
</dl>
</section>
</section>
<section class="normative">
<h3>Representations of JSON Schema</h3>
<p>
The standard representation of [[JSON-SCHEMA]] uses the [[RFC8259]] JSON data interchange
syntax</a> with <code>.json</code> as the file extension.
</p>
<p>
Implementers MAY use OpenAPI Specification's [[[OPENAPIS-3.1.0]]] [[YAML]] representation
of a [[JSON-SCHEMA]] with <code>.yaml</code> as the file extension.
<p class="note">
YAML representations of JSON Schemas can only be used with credential schemas whose type is <a href="#jsonschema">JsonSchema</a>.
</p>
An example [[JSON-SCHEMA]] using [[YAML]] is provided below.
<pre class="example" data-include="./example/yaml-json-schema.yaml" data-include-format="yaml"></pre>
</p>
</section>
</section>
<section class="normative">
<h2>Processing</h2>
<p>
This section details how to process Credential Schemas, which is commonly referred to
as <i>JSON schema validation</i>.
<p>
<p>
There are many open source implementations of [[JSON-SCHEMA]] validators across many common programming
languages. The <a href="https://openjsf.org/">OpenJS Foundation</a> maintains a list of implementations
as a part of the <a href="https://json-schema.org/implementations.html">JSON Schema official documentation</a>.
</p>
<p>
A common feature of a JSON Schema validator is the ability to detect the version of a JSON Schema document
and select the validator for that specific version of [[JSON-SCHEMA]]. This is done by switching on the
schema's <code>$schema</code> property and picking the corresponding validator. Schemas without a
<code>$schema</code> property are not considered valid and MUST NOT be processed. Implementers
SHOULD choose validators which possess this capability and are able to limit validation to the
<a href="#json-schema-specifications">JSON Schema specifications</a> supported by this document.
</p>
<p>
Conformant implementers MUST support JSON Schema specification versions marked as <b>required</b>
in the table defined in the <a href="#json-schema-specifications">JSON Schema specifications section</a>
of this document. Implementers MAY support JSON Schema specification versions not marked as
<b>required</b>.
</p>
<section class="normative">
<h3>Integrity Validation</h3>
<p>
Credential Schemas MAY be packaged as <a>verifiable credentials</a> as defined
by usage of the <a href="#jsonschemacredential">JsonSchemaCredential</a> type.
The credential containing a <a>credential schema</a> MAY be secured by using either an
embedded or external proof as defined in <a data-cite="VC-DATA-MODEL-2.0/#securing-verifiable-credentials">
Securing Verifiable Credentials</a>.
</p>
<p>
Secured credentials representing credential schemas SHOULD first be validated
according to the rules set out in the aforementioned securing specifications
before proceeding with additional processing.
</p>
<p class="issue" data-number="143">
Provide examples for secured credential schemas.
</p>
<p>
Credential Schemas of type <a href="#jsonschema">JsonSchema</a> MAY
be annotated with integrity information by adding the `digestSRI` property to the `credentialSchema` value
in the Verifiable Credential which contains the schema, using the method specified in
<a data-cite="VC-DATA-MODEL-2.0/#integrity-of-related-resources">Integrity of Related Resources</a>.
It is RECOMMENDED that validation of the integrity of the schema be done before evaluation.
</p>
<p>
An example of such usage is provided below:
</p>
<pre class="example vc-jose-cose-vc-example nohighlight" title="Example Verifiable Credential JsonSchema with Integrity Information">
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://www.w3.org/ns/credentials/examples/v2"
],
"id": "https://example.com/credentials/3733",
"type": ["VerifiableCredential", "EmailCredential"],
"issuer": "https://example.com/issuers/14",
"issuanceDate": "2010-01-01T19:23:24Z",
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"emailAddress": "[email protected]"
},
<span class="highlight"> "credentialSchema": {
"id": "https://example.com/schemas/email.json",
"type": "JsonSchema",
"digestSRI": "sha384-dNwyy/Zs/YjPor8aoOgnaCqb+PH24QcNFxbxM1XoBOxdbgnpQcVaGYH8QunXww2U"
}</span>
}
</pre>
</section>
<section class="normative">
<h3>Evaluation</h3>
<p>
Validation of a given credential against a schema is to be performed according
to its associated [[JSON-SCHEMA]] specification. Validation MUST result in one of the following three possible
outcomes:
<ul>
<li><b>Success</b> – The credential is considered to be valid against the given <a>credential schema</a>.</li>
<li><b>Failure</b> – The credential is not considedred to be valid against the given <a>credential schema</a>.</li>
<li><b>Indeterminate</b> – The credential could not be validated. Implementers MUST return this outcome when they encounter a schema whose version they do not support.</li>
</ul>
</p>
<p>
Examples for the Success and Failure possible outcomes are provided below.
</p>
<section class="normative">
<h4>Success Result</h4>
<p>
<pre class="example" title="Example Email JSON Schema">
{
"$id": "https://example.com/schemas/email.json",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "EmailCredential",
"description": "EmailCredential using JsonSchema",
"type": "object",
"properties": {
"credentialSubject": {
"type": "object",
"properties": {
"emailAddress": {
"type": "string",
"format": "email"
}
},
"required": ["emailAddress"]
}
}
}
</pre>
</p>
<p>
Validation according to the spec [[JSON-SCHEMA-2020-12]] yields a <i>Success</i> result
when applying it to the VC below.
</p>
<p>
<pre class="example vc-jose-cose-vc-example" title="Example Verifiable Credential - validation Success">
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://www.w3.org/ns/credentials/examples/v2"
],
"id": "https://example.com/credentials/3732",
"type": ["VerifiableCredential", "EmailCredential"],
"issuer": "https://example.com/issuers/14",
"issuanceDate": "2010-01-01T19:23:24Z",
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"emailAddress": "[email protected]"
},
"credentialSchema": {
"id": "https://example.com/schemas/email.json",
"type": "JsonSchema"
}
}
</pre>
</p>
</section>
<section>
<h4>Failure Result</h4>
<p>
Validation according to the spec [[JSON-SCHEMA-2020-12]] yields a <i>Failure</i> result when
applying it to the VC below.
</p>
<p>
<pre class="illegal-example vc-jose-cose-vc-example" title="Example Verifiable Credential - validation Failure">
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://www.w3.org/ns/credentials/examples/v2"
],
"id": "https://example.com/credentials/3732",
"type": ["VerifiableCredential", "EmailCredential"],
"issuer": "https://example.com/issuers/14",
"issuanceDate": "2010-01-01T19:23:24Z",
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"emailAddress": "not an email"
},
"credentialSchema": {
"id": "https://example.com/schemas/email.json",
"type": "JsonSchema"
}
}
</pre>
</p>
</section>
<section>
<h4>Indeterminate Result</h4>
<p>
Assuming that the implementer does not support [[?JSON-SCHEMA-2019-09]], an example of an <i>Indeterminate</i>
evaluation is provided below.
</p>
<p>
<pre class="example" title="Example Email JSON Schema using unsupported JSON Schema version">
{
"$id": "https://example.com/schemas/email.json",
"$schema": "https://json-schema.org/draft/2019-09/schema",
"title": "EmailCredential",
"description": "EmailCredential using JsonSchema",
"type": "object",
"properties": {
"credentialSubject": {
"type": "object",
"properties": {
"emailAddress": {
"type": "string",
"format": "email"
}
},
"required": [
"emailAddress"
]
}
}
}
</pre>
</p>
<p>
<pre class="example vc-jose-cose-vc-example" title="Example Verifiable Credential - validation Indeterminate">
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://www.w3.org/ns/credentials/examples/v2"
],
"id": "https://example.com/credentials/3732",
"type": ["VerifiableCredential", "EmailCredential"],
"issuer": "https://example.com/issuers/14",
"issuanceDate": "2010-01-01T19:23:24Z",
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"emailAddress": "not an email"
},
"credentialSchema": {
"id": "https://example.com/schemas/email.json",
"type": "JsonSchema"
}
}
</pre>
</p>
</section>
</section>
</section>
<section class="informative">
<h2>Implementation Considerations</h2>
<p>
This section details some issues implementers of the specification
may consider.
</p>
<section class="informative">
<h3>Credential Property Validation</h3>
<p>
Implementers may wish to validate certain properties in a
<a>verifiable credential</a>. To do this, <a>credential schemas</a> can be
constructed to validate subsets of a credential's data.
</p>
<p>
One example of such a construction would be to validate the presence of certain
top-level properties in a <a>verifiable credential</a>. The following example
demonstrates a schema which enforces that a credential issued against it
has an <code>validUntil</code> property and includes <code>evidence</code>.
</p>
<p>
<pre class="example" title="ValidUntil and Evidence Credential Schema">
{
"$id": "validuntil-and-evidence-schema",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "Example validUntil and evidence schema",
"description": "Schema requiring validUntil and evidence properties",
"type": "object",
"properties": {
"validUntil": {
"type": "object"
},
"evidence": {
"type": "object"
}
},
"required": ["validUntil", "evidence"]
}
</pre>
</p>
</section>
<section class="informative">
<h3>Additional Properties</h3>
<p>
When using [[JSON-SCHEMA]], it is advised that implementers avoid
setting the <code>additionalProperties</code> to <i>false</i>. Doing
so could inadvertently exclude properties in a credential from passing
validation.
</p>
<p>
As an example, consider a credential schema that is intended to validate
the <code>credentialSubject</code> property of a credential. It is common
for the <code>credentialSubject</code> property to include an <code>id</code>,
denoting the identifier the subject. Not including this <code>id</code> property
in a given schema would result in validation failure. The simple alternative
is to avoid setting <code>additionalProperties</code> to <i>false</i>.
</p>
<p>
<pre class="example" title="Example Name Credential Schema">
{
"$id": "name-schema",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "Name schema",
"description": "A schema capturing a human name",
"type": "object",
"properties": {
"credentialSubject": {
"type": "object",
"properties": {
"name": {
"type": "object",
"properties": {
"firstName": {
"type": "string"
},
"lastName": {
"type": "string"
},
"additionalProperties": false
},
"required": [
"firstName",
"lastName"
]
}
}
}
}
}
</pre>
</p>
</section>
<section class="informative">
<h3>Versioning</h3>
<p>
Versioning is not provided as an explicit feature of this specification.
Implementers are advised to make backwards compatabile changes to schemas, should
they be adjusted. Otherwise, it is advised that new <a>credential schemas</a>
be created with unique identifiers to avoid processing conflicts.
</p>
</section>
<section class="informative">
<h3>Content Integrity Protection</h3>
<p>
It is important to make sure that <a>credential schemas</a> have not been tampered with
before processing. When making use of the <code>JsonSchemaCredential2023</code> representation
of a schema, the credential's associated integrity protection mechanism can be used to detect mutations
of a <a>credential schema</a> via its digital signature.
</p>
<p>
As an alternative, the aforementioned <a data-cite="VC-DATA-MODEL-2.0/#integrity-of-related-resources">
Integrity of Related Resources</a> scheme may be used to provide content integrity
protection, ensuring that the underlying <a>credential schema</a> resource has not been tampered with.
</p>
</section>
<section class="informative">
<h3>Storage</h3>
<p>
Credential schemas can be stored on any number of storage media such as a distributed
ledger, traditional database, or decentralized file storage. For more robust availability
guarantees, the same schema could be replicated across multiple file stores.
</p>
</section>
<section class="informative">
<h3>Multiple Schemas</h3>
<p>
A common use case is to include multiple schemas to validate against a single
<a>verifiable Credential</a>. One such use case is to use <a href="https://github.com/w3c/vc-data-model/blob/main/schema/verifiable-credential/verifiable-credential-schema.json">the JSON Schema defined by the</a> [[VC-DATA-MODEL-2.0]] in addition to a schema to validate a specific property in the credential, such as the <code>credentialSubject</code>. Multiple schemas MAY be combined using native constructs from the [[JSON-SCHEMA]] specification, through use of properties such as <code>oneOf</code>, <code>anyOf</code>, or <code>allOf</code>.
</p>
<p>
An example of how to construct such a schema using the [[JSON-SCHEMA]] property
<code>allOf</code> is provided below, combining schemas for a <a>verifiable credential</a>,
name, and email address:
<pre class="example" title="Multiple Schema Credential Schema Example">
{
"allOf": [
{