-
Notifications
You must be signed in to change notification settings - Fork 93
/
index.html
6159 lines (5634 loc) · 239 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>
Decentralized Identifiers (DIDs) v1.0
</title>
<meta content='text/html; charset=utf-8' http-equiv='Content-Type'><!--
=== 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 class="remove"
src="https://unpkg.com/browse/jquery/dist/jquery.min.js"></script>
<script class="remove"
src="https://www.w3.org/Tools/respec/respec-w3c"></script>
<script class="remove"
src="https://unpkg.com/reqlist/lib/reqlist.js"></script>
<link class="removeOnSave" rel="stylesheet" type="text/css"
href="https://unpkg.com/reqlist/lib/reqlist.css" />
<script class='remove' src="./common.js"></script>
<script class="remove" type="text/javascript">
var respecConfig = {
// the W3C WG and public mailing list
group: "did",
wgPublicList: "public-did-wg",
// the specification's short name, as in http://www.w3.org/TR/short-name/
shortName: "did-core",
// specification status (e.g., WD, LCWD, NOTE, etc.). If in doubt use ED.
specStatus: "WD",
// Editor's Draft URL
edDraftURI: "https://w3c.github.io/did-core/",
// subtitle for the spec
subtitle: "Core architecture, data model, and representations",
// if you wish the publication date to be other than today, set this
//publishDate: "2019-11-07",
// previously published draft, uncomment this and set its
// YYYY-MM-DD date and its maturity status
previousPublishDate: "2020-11-08",
previousMaturity: "WD",
// automatically allow term pluralization
pluralize: true,
// extend the bibliography entries
localBiblio: ccg.localBiblio,
xref: "web-platform",
github: {
repoURL: "https://github.com/w3c/did-core/",
branch: "main"
},
includePermalinks: false,
// Uncomment these to use the respec extension that generates a list of
// normative statements:
// preProcess: [
// prepare_reqlist
// ],
postProcess: [
// add_reqlist_button,
restrictRefs
],
// list of specification editors
editors: [{
name: "Drummond Reed",
url: "https://www.linkedin.com/in/drummondreed/",
company: "Evernym",
companyURL: "https://www.evernym.com/",
w3cid: 3096
},
{
name: "Manu Sporny",
url: "http://manu.sporny.org/",
company: "Digital Bazaar",
companyURL: "https://digitalbazaar.com/",
w3cid: 41758
},
{
name: "Markus Sabadello",
url: "https://www.linkedin.com/in/markus-sabadello-353a0821",
company: "Danube Tech",
companyURL: "https://danubetech.com/",
w3cid: 46729
}
],
// list of specification authors
authors: [{
name: "Drummond Reed",
url: "https://www.linkedin.com/in/drummondreed/",
company: "Evernym",
companyURL: "https://www.evernym.com/",
w3cid: 3096
},
{
name: "Manu Sporny",
url: "http://manu.sporny.org/",
company: "Digital Bazaar",
companyURL: "https://digitalbazaar.com/",
w3cid: 41758
},
{
name: "Dave Longley",
url: "https://github.com/dlongley",
company: "Digital Bazaar",
companyURL: "https://digitalbazaar.com/",
w3cid: 48025
},
{
name: "Christopher Allen",
url: "https://www.linkedin.com/in/christophera",
company: "Blockchain Commons",
companyURL: "https://www.BlockchainCommons.com",
w3cid: 85560
},
{
name: "Ryan Grant",
url: "",
company: "",
companyURL: ""
},
{
name: "Markus Sabadello",
url: "https://www.linkedin.com/in/markus-sabadello-353a0821",
company: "Danube Tech",
companyURL: "https://danubetech.com/",
w3cid: 46729
}
]
};
</script>
<style>
pre .highlight {
font-weight: bold;
color: green;
}
pre .comment {
color: SteelBlue;
-webkit-user-select: none;
-moz-user-select: none;
-ms-user-select: none;
user-select: none;
}
code a[href] {
color: inherit;
border-bottom: none;
}
code a[href]:hover {
border-bottom: 1px solid #c63501;
}
</style>
</head>
<body data-cite="infra rfc3986">
<section id='abstract'>
<p>
<a>Decentralized identifiers</a> (DIDs) are a new type of identifier that
enables verifiable, decentralized digital identity. A <a>DID</a> identifies any
subject (e.g., a person, organization, thing, data model, abstract entity, etc.)
that the controller of the <a>DID</a> decides that it identifies. In contrast to
typical, federated identifiers, <a>DIDs</a> have been designed so that they may be
decoupled from centralized registries, identity providers, and certificate
authorities. Specifically, while other parties might be used to help enable the
discovery of information related to a <a>DID</a>, the design enables the
controller of a <a>DID</a> to prove control over it without requiring permission
from any other party. <a>DIDs</a> are <a>URIs</a> that associate a <a>DID subject</a>
with a <a>DID document</a> allowing trustable interactions associated with that
subject.
</p>
<p>
Each <a>DID document</a> can express cryptographic material, <a>verification
methods</a>, or <a>services</a>, which provide a set of mechanisms enabling
a <a>DID controller</a> to prove control of the <a>DID</a>. <a>Services</a>
enable trusted interactions associated with the <a>DID subject</a>. A
<a>DID</a> might provide the means to return the <a>DID subject</a> itself,
if the <a>DID subject</a> is an information resource such as a data model.
</p>
<p>
This document specifies a common data model, a URL format, and a set of
operations for <a>DIDs</a>, <a>DID documents</a>, and <a>DID methods</a>.
</p>
</section>
<section id='sotd'>
<p>
This specification is under active development and implementers are advised
against implementing the specification unless they are directly involved with
the W3C DID Working Group. There are use cases [[?DID-USE-CASES]] in active
development that establish requirements for this document.
</p>
<p>
At present, there exist
<a href="https://w3c-ccg.github.io/did-method-registry/#did-methods">80
experimental implementations</a> and a preliminary
<a href="https://github.com/w3c-ccg/did-test-suite/">test suite</a>
that will eventually determine whether or not implementations are conformant.
Readers are advised that Appendix <a href="#current-issues"></a> contains a
list of concerns and proposed changes that will most likely result in
alterations to this specification.
</p>
<p>
Comments regarding this document are welcome. Please file issues
directly on <a href="https://github.com/w3c/did-core/issues/">GitHub</a>,
or send them
to <a href="mailto:public-did-wg@w3.org">public-did-wg@w3.org</a> (
<a href="mailto:public-did-wg-request@w3.org?subject=subscribe">subscribe</a>,
<a href="https://lists.w3.org/Archives/Public/public-did-wg/">archives</a>).
</p>
<p>
Portions of the work on this specification have been funded by the United States
Department of Homeland Security's (US DHS) Science and Technology Directorate
under contracts HSHQDC-16-R00012-H-SB2016-1-002, and HSHQDC-17-C-00019, as well
as the US DHS Silicon Valley Innovation Program under contracts
70RSAT20T00000010, 70RSAT20T00000029, 70RSAT20T00000030. The content of this specification does not
necessarily reflect the position or the policy of the U.S. Government and no
official endorsement should be inferred.
</p>
<p>
Portions of the work on this specification have also been funded by the European
Union's StandICT.eu program under sub-grantee contract number CALL05/19.
</p>
<p>
Work on this specification has also been supported by the Rebooting the Web of
Trust community facilitated by Christopher Allen, Shannon Appelcline, Kiara
Robles, Brian Weller, Betty Dhamers, Kaliya Young, Kim Hamilton Duffy, Manu
Sporny, Drummond Reed, Joe Andrieu, and Heather Vescent.
</p>
</section>
<section class="informative">
<h1>Introduction</h1>
<p>
As individuals and organizations, many of us use globally unique identifiers in
a wide variety of contexts. They serve as communications addresses (telephone
numbers, email addresses, usernames on social media), ID numbers (for passports,
drivers licenses, tax IDs, health insurance), and product identifiers (serial
numbers, barcodes, RFIDs). Resources on the Internet are identified by globally
unique identifiers in the form of <abbr title="Media Access Control">MAC</abbr>
addresses; URIs (Uniform Resource Identifiers) are used for resources on the Web
and each web page you view in a browser has a globally unique URL (Uniform
Resource Locator).
</p>
<p>
The vast majority of these globally unique identifiers are not under our
control. They are issued by external authorities that decide who or what they
identify and when they can be revoked. They are useful only in certain contexts
and recognized only by certain bodies (not of our choosing). They may disappear
or cease to be valid with the failure of an organization. They may unnecessarily
reveal personal information. And in many cases they can be fraudulently
replicated and asserted by a malicious third-party ("identity theft").
</p>
<p>
The Decentralized Identifiers (DIDs) defined in this specification are a new
type of globally unique identifier designed to enable individuals and
organizations to generate our own identifiers using systems we trust, and to
prove control of those identifiers (authenticate) using cryptographic proofs
(for example, digital signatures).
</p>
<p>
Because we control the generation and assertion of these identifiers, each of us
can have as many DIDs as we need to respect our desired separation of
identities, personas, and contexts (in the everyday sense of these words). We
can scope the use of these identifiers to the most appropriate contexts. We can
interact with other people, institutions or systems that require us to identify
ourselves (or things we control) while maintaining control over how much
personal or private data should be revealed, and without depending on a central
authority to guarantee the continued existence of the identifier.
</p>
<p>
This specification does not presuppose any particular technology or
cryptography to underpin the generation, persistence, resolution or
interpretation of DIDs. Rather, it defines: a) the generic syntax for all
DIDs, and b) the generic requirements for performing the four basic CRUD
operations (create, read, update, deactivate) on the information associated
with a DID (called the DID document).
</p>
<p>
This enables implementers to design specific types of DIDs to work with the
computing infrastructure they trust (e.g., distributed ledger, decentralized
file system, distributed database, peer-to-peer network). The specification
for a specific type of DID is called a DID method. Implementers of
applications or systems using DIDs can choose to support the DID methods most
appropriate for their particular use cases.
</p>
<p>
This specification is for:
</p>
<ul>
<li>
Developers who want to enable users of their system to generate and assert their
own identifiers (producers of DIDs);
</li>
<li>
Developers who want to enable their systems to accept user-controlled
identifiers (consumers of DIDs);
</li>
<li>
Developers who wish to enable the use of DIDs with particular computing
infrastructure (DID method developers).
</li>
</ul>
<p class="note" title="Diversity of DID systems">
DID methods can also be developed for identifiers registered in federated or
centralized identity management systems. Indeed, almost all types of identifier
systems can add support for DIDs. This creates an interoperability bridge
between the worlds of centralized, federated, and decentralized identifiers.
</p>
<section class="informative">
<h2>A Simple Example</h2>
<p>
A <a>DID</a> is a simple text string consisting of three parts, the:
</p>
<ul>
<li>
URI scheme identifier (<code>did</code>)
</li>
<li>
Identifier for the <a>DID method</a>
</li>
<li>
DID method-specific identifier.
</li>
</ul>
<pre class="example nohighlight"
title="A simple example of a decentralized identifier (DID)">
did:example:123456789abcdefghi
</pre>
<p>
The example <a>DID</a> above resolves to a <a>DID document</a>. A <a>DID
document</a> contains information associated with the <a>DID</a>, such as ways
to cryptographically <a>authenticate</a> the <a>DID controller</a>, as
well as <a>services</a> that can be used to interact with the <a>DID subject</a>.
</p>
<pre class="example nohighlight" title="Minimal self-managed DID document">
{
"@context": "https://www.w3.org/ns/did/v1",
"id": "did:example:123456789abcdefghi",
"authentication": [{
<span class="comment">// used to authenticate as did:...fghi</span>
"id": "did:example:123456789abcdefghi#keys-1",
"type": "Ed25519VerificationKey2018", <span class="comment">// external (property value)</span>
"controller": "did:example:123456789abcdefghi",
"publicKeyBase58": "H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV"
}],
"service": [{
<span class="comment">// used to retrieve Verifiable Credentials associated with the DID</span>
"id":"did:example:123456789abcdefghi#vcs",
"type": "VerifiableCredentialService", <span class="comment">// external (property value)</span>
"serviceEndpoint": "https://example.com/vc/"
}]
}
</pre>
</section>
<section class="informative">
<h2>Design Goals</h2>
<p>
<a>Decentralized Identifiers</a> are a component of larger systems, such as
the Verifiable Credentials ecosystem [[VC-DATA-MODEL]], which drove the design
goals for this specification. These design goals are summarized here.
</p>
<table class="simple">
<thead>
<tr>
<th>
Goal
</th>
<th>
Description
</th>
</tr>
</thead>
<tbody>
<tr>
<td>
Decentralization
</td>
<td>
Eliminate the requirement for centralized authorities or single point
failure in identifier management, including the registration of globally unique
identifiers, public verification keys, <a>services</a>, and other
information.
</td>
</tr>
<tr>
<td>
Control
</td>
<td>
Give entities, both human and non-human, the power to directly control their
digital identifiers without the need to rely on external authorities.
</td>
</tr>
<tr>
<td>
Privacy
</td>
<td>
Enable entities to control the privacy of their information, including minimal,
selective, and progressive disclosure of attributes or other data.
</td>
</tr>
<tr>
<td>
Security
</td>
<td>
Enable sufficient security for requesting parties to depend on
<a>DID documents</a> for their required level of assurance.
</td>
</tr>
<tr>
<td>
Proof-based
</td>
<td>
Enable <a>DID controllers</a> to provide cryptographic proof when interacting
with other entities.
</td>
</tr>
<tr>
<td>
Discoverability
</td>
<td>
Make it possible for entities to discover <a>DIDs</a> for other entities, to
learn more about or interact with those entities.
</td>
</tr>
<tr>
<td>
Interoperability
</td>
<td>
Use interoperable standards so <a>DID</a> infrastructure can make use of
existing tools and software libraries designed for interoperability.
</td>
</tr>
<tr>
<td>
Portability
</td>
<td>
Be system- and network-independent and enable entities to use their digital
identifiers with any system that supports <a>DIDs</a> and <a>DID methods</a>.
</td>
</tr>
<tr>
<td>
Simplicity
</td>
<td>
Favor a reduced set of simple features to make the technology easier to
understand, implement, and deploy.
</td>
</tr>
<tr>
<td>
Extensibility
</td>
<td>
Where possible, enable extensibility provided it does not greatly hinder
interoperability, portability, or simplicity.
</td>
</tr>
</tbody>
</table>
</section>
<section>
<h2>
Architecture Overview
</h2>
<p>
This section provides a basic understanding of the major elements of <a>DID</a>
architecture. Formal definitions of terms are provided in
<a href="#terminology"></a>.
</p>
<figure id="architecture">
<img style="margin: auto; display: block; width: 75%;"
src="diagrams/did_architecture_overview.svg" alt="
Diagram showing that DIDs are recorded on a Verifiable Data Registry; DIDs
resolve to DID documents; DIDs identify DID subjects; a DID controller can
modify a DID document; a DID method generates a DID; a DID method instructs a
DID resolver.
" >
<figcaption>
The basic components of DID architecture.
</figcaption>
</figure>
<dl>
<dt>
DIDs and DID URLs
</dt>
<dd>
A <a>DID</a>, or Decentralized Identifier, is a <a>URI</a> composed of three parts: the
scheme "did:", a method identifier, and a unique, method-specific identifier
generated by the <a>DID method</a>. <a>DIDs</a> are resolvable to <a>DID documents</a>.
A <a>DID URL</a> extends the syntax of a basic <a>DID</a> to incorporate other standard
<a>URI</a> components (path, query, fragment) in order to locate a particular
<a>resource</a>—for example, a public key inside a <a>DID document</a>, or a
<a>resource</a> available external to the <a>DID document</a>.
</dd>
<dt>
DID Subjects
</dt>
<dd>
The subject of a <a>DID</a> is, by definition, the entity identified by the
<a>DID</a>. The <a>DID subject</a> may also be the <a>DID controller</a>.
Anything can be the subject of a <a>DID</a>: person, group, organization, physical
thing, logical thing, etc.
</dd>
<dt>
DID Controllers
</dt>
<dd>
The <a>controller</a> of a <a>DID</a> is the entity (person, organization, or
autonomous software) that has the capability—as defined by a <a>DID
method</a>—to make changes to a <a>DID document</a>. This capability is
typically asserted by the control of a set of cryptographic keys used by
software acting on behalf of the controller, though it may also be asserted via
other mechanisms. Note that a <a>DID</a> may have more than one controller, and the
<a>DID subject</a> can be the <a>DID controller</a>, or one of them.
</dd>
<dt>
Verifiable Data Registries
</dt>
<dd>
In order to be resolvable to <a>DID documents</a>, <a>DIDs</a> are typically
recorded on an underlying system or network of some kind. Regardless of the
specific technology used, any such system that supports recording <a>DIDs</a> and
returning data necessary to produce <a>DID documents</a> is called a
<a>verifiable data registry</a>. Examples include <a>distributed ledgers</a>,
decentralized file systems, databases of any kind, peer-to-peer networks, and
other forms of trusted data storage.
</dd>
<dt>
DID documents
</dt>
<dd>
<a>DID documents</a> contain information associated with a <a>DID</a>. They
typically express <a>verification methods</a> (such as public keys) and <a>services</a>
relevant to interactions with the <a>DID subject</a>. A <a>DID document</a> can be serialized
according to a particular syntax (see Section <a href="#representations"></a>). The
generic properties supported in a <a>DID document</a> are specified in <a
href="#core-properties"></a>. The <a>DID</a> itself is the value of the `id`
property. The properties present in a <a>DID document</a> may be updated according to
the applicable operations outlined in <a href="#methods"></a>.
</dd>
<dt>
DID Methods
</dt>
<dd>
<a>DID methods</a> are the mechanism by which a particular type of <a>DID</a>
and its associated <a>DID document</a> are created, resolved, updated, and
deactivated using a particular <a>verifiable data registry</a>. <a>DID
methods</a> are defined using separate DID method specifications (see
<a href="#methods"></a>).
<p class="note">
Conceptually, the relationship between this specification and a <a>DID
method</a> specification is similar to the relationship between the IETF generic
<a>URI</a> specification ([[RFC3986]]) and a specific <a>URI</a> scheme
([[IANA-URI-SCHEMES]] (such as the http: and https: schemes specified in
[[RFC7230]]). It is also similar to the relationship between the IETF generic
URN specification ([[RFC8141]]) and a specific URN namespace definition (such
as the <a>UUID</a> URN namespace defined in [[RFC4122]]). The difference is that
a DID method specification, as well as defining a specific <a>DID scheme</a>, also
specifies the methods creating, resolving, updating, and deactivating
<a>DIDs</a> and <a>DID documents</a> using a specific type of <a>verifiable data
registry</a>.
</p>
</dd>
<dt>
DID resolvers and DID resolution
</dt>
<dd>
A <a>DID resolver</a> is a software and/or hardware component that takes a
<a>DID</a> (and associated input metadata) as input and produces a conforming
<a>DID document</a> (and associated metadata) as output. This process is called
<a>DID resolution</a>. The inputs and outputs of the <a>DID resolution</a> process are
defined in <a href="#resolution"></a>. The specific steps for resolving a
specific type of <a>DID</a> are defined by the relevant <a>DID method</a>
specification. Additional considerations for implementing a <a>DID resolver</a> are
discussed in [[DID-RESOLUTION]].
</dd>
<dt>
DID URL dereferencers and DID URL dereferencing
</dt>
<dd>
A <a>DID URL</a> dereferencer is a software and/or hardware component that takes
a <a>DID URL</a> (and associated input metadata) as input and produces a <a>resource</a> (and
associated metadata) as output. This process is called <a>DID URL</a> dereferencing.
The inputs and outputs of the <a>DID URL</a> dereferencing process are defined in <a
href="#did-url-dereferencing"></a>. Additional considerations for implementing a
<a>DID URL</a> dereferencer are discussed in [[DID-RESOLUTION]].
</dd>
</dl>
</section>
<section id="conformance">
<p>
This document contains examples that contain JSON, CBOR, and JSON-LD content.
Some of these examples contain characters that are invalid, such as inline
comments (<code>//</code>) and the use of ellipsis (<code>...</code>) to denote
information that adds little value to the example. Implementers are cautioned to
remove this content if they desire to use the information as valid JSON, CBOR,
or JSON-LD.
</p>
<p>
Some examples contain terms (both property names and values) that are not
defined in this specification, for illustrative purposes. These are indicated
with a comment (<code>// external (property name|value)</code>). Such terms,
when used in a <a>DID document</a>, are expected to be registered in the DID
Specification Registries [[?DID-SPEC-REGISTRIES]] with links to both a formal
definition and JSON-LD context.
</p>
<p>
Interoperability of implementations for <a>DIDs</a> and <a>DID documents</a> will be tested by
evaluating an implementation's ability to create and parse <a>DIDs</a> and
<a>DID documents</a> that conform to the specification. Interoperability for
producers and consumers of <a>DIDs</a> and <a>DID documents</a> is provided by
ensuring the <a>DIDs</a> and <a>DID documents</a> conform. Interoperability for
<a>DID method</a> specifications is provided by the details in each <a>DID method</a>
specification. It is understood that, in the same way that a web browser is not
required to implement all known <a>URI</a> schemes, conformant software that works with
<a>DIDs</a> is not required to implement all known <a>DID methods</a> (however, all
implementations of a given <a>DID method</a> must be interoperable for that method).
</p>
<p>
A <dfn>conforming DID</dfn> is any concrete expression of the rules specified
in Section <a href="#identifier"></a> which complies with relevant normative
statements in that section.
</p>
<p>
A <dfn>conforming DID document</dfn> is any concrete expression of the data
model described in this specification which complies with the relevant
normative statements in Sections <a href="#data-model"></a> and <a
href="#core-properties"></a>. A serialization format for the conforming
document is deterministic, bi-directional, and lossless as described in
Section <a href="#representations"></a>.
</p>
<p>
A <dfn>conforming DID method</dfn> is any specification that complies with the
relevant normative statements in Section <a href="#methods"></a>.
</p>
<p>
A <dfn>conforming producer</dfn> is any algorithm realized as software and/or
hardware and conforms to this specification if it generates <a>conforming
DIDs</a> or <a>conforming DID Documents</a>. A conforming producer MUST
NOT produce non-conforming <a>DIDs</a> or <a>DID documents</a>.
</p>
<p>
A <dfn>conforming consumer</dfn> is any algorithm realized as software and/or
hardware and conforms to this specification if it consumes <a>conforming
DIDs</a> or <a>conforming DID documents</a>. A conforming consumer MUST
produce errors when consuming non-conforming <a>DIDs</a> or <a>DID documents</a>.
</p>
</section>
</section>
<section class="informative">
<h2>Terminology</h2>
<div data-include="terms.html">
</div>
<p>
In addition to the terminology above, this specification also uses terminology
from the [[INFRA]] specification to formally define the <a
href="#data-model">data model</a>. When [[INFRA]] terminology is used, such as
<a data-cite="INFRA#strings">string</a>, <a
data-cite="INFRA#ordered-set">ordered set</a>, and <a
data-cite="INFRA#maps">map</a>, it is linked directly to that specification.
</p>
</section>
<section>
<h2>Identifier</h2>
<p>
This section describes the formal syntax for <a>DIDs</a> and <a>DID URLs</a>. The term
"generic" is used to differentiate the syntax defined here from syntax defined
by <em>specific</em> <a>DID methods</a> in their respective specifications.
</p>
<section class="normative">
<h3>DID Syntax</h3>
<p>
The generic <a>DID scheme</a> is a <a>URI</a> scheme conformant with [[!RFC3986]].
</p>
<p>
The <a>DID scheme</a> name MUST be an
<a data-lt="ascii lowercase">ASCII lowercase string</a>.
</p>
<p>
The <a>DID method</a> name MUST be a string which consists of
<a data-lt="ascii lower alpha">ASCII lowercase characters</a> and
<a data-lt="ascii digit">ASCII digits</a>.
</p>
<p>
The following is the ABNF definition using the syntax in [[!RFC5234]], which
defines <code>ALPHA</code> and <code>DIGIT</code>. All other rule names not
defined in this ABNF are defined in [[RFC3986]].
</p>
<pre class="nohighlight">
did = "did:" method-name ":" method-specific-id
method-name = 1*method-char
method-char = %x61-7A / DIGIT
method-specific-id = *( *idchar ":" ) 1*idchar
idchar = ALPHA / DIGIT / "." / "-" / "_"
</pre>
<p class="issue atrisk" data-number="34">
This ABNF does not currently permit an empty <code>method-specific-id</code>
string. Some DID methods have expressed an interest in providing
resolution of an DID with an empty <code>method-specific-id</code> string,
for example to enable discovery of a DID document describing a
<a>verifiable data registry</a> by resolving the DID method name alone.
The Working Group is requesting feedback during the Candidate Recommendation
stage on whether or not an empty <code>method-specific-id</code> string is
of interest to implementers. This feature may change as a result of that feedback.
</p>
<p>
For requirements on <a>DID methods</a> relating to the <a>DID</a> syntax, see
Section <a href="#method-schemes"></a>.
</p>
</section>
<section class="normative">
<h3>DID URL Syntax</h3>
<p>
A <a>DID URL</a> always identifies a <a>resource</a> to be located. It can be
used, for example, to identify a specific part of a <a>DID document</a>.
</p>
<p>
This following is the ABNF definition using the syntax in [[!RFC5234]]. It
builds on the <code>did</code> scheme defined in <a href="#did-syntax"></a>. The
<a data-cite="!rfc3986#section-3.3"><code>path-abempty</code></a>,
<a data-cite="!rfc3986#section-3.4"><code>query</code></a>, and
<a data-cite="!rfc3986#section-3.5"><code>fragment</code></a>
components are identical to the ABNF rules defined in [[!RFC3986]].
</p>
<pre class="nohighlight">
did-url = did path-abempty [ "?" query ] [ "#" fragment ]
</pre>
<p class="note">
This specification reserves the semicolon (<code>;</code>) character for
possible future use as a sub-delimiter for parameters as described in
[[?MATRIX-URIS]].
</p>
<section>
<h2>DID Parameters</h2>
<p>
The <a>DID URL</a> syntax supports a simple format for parameters
based on the <code>query</code> component (See <a href="#query"></a>). Adding
a DID parameter to a <a>DID URL</a> means that the parameter becomes part of
the identifier for a <a>resource</a>.
</p>
<p>
Some DID parameters are completely independent of of any specific <a>DID
method</a>, and function the same way for all <a>DIDs</a>. Other DID
parameters are not necessarily supported by all <a>DID methods</a>. Where
optional parameters are supported, they are expected to operate uniformly
across the <a>DID methods</a> that do support them. Requirements which enable
this are detailed in the following table.
</p>
<table class="simple">
<thead>
<tr>
<th>
Parameter Name
</th>
<th>
Description
</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code><a>service</a></code>
</td>
<td>
Identifies a service from the <a>DID document</a> by service ID. Support for
this parameter is REQUIRED. The associated value MUST be an <a data-lt="ascii
string">ASCII string</a>.
</td>
</tr>
<tr>
<td>
<code>relativeRef</code>
</td>
<td>
A relative <a>URI</a> reference according to <a
data-cite="RFC3986#section-4.2">RFC3986 Section 4.2</a>
that identifies a <a>resource</a> at a <a>service endpoint</a>, which is selected from
a <a>DID document</a> by using the <code>service</code> parameter. Support for
this parameter is REQUIRED. The associated value MUST be an <a data-lt="ascii
string">ASCII string</a> and MUST use percent-encoding for certain characters
as specified in <a data-cite="RFC3986#section-2.1">RFC3986 Section 2.1</a>.
</td>
</tr>
<tr>
<td>
<code>versionId</code>
</td>
<td>
Identifies a specific version of a <a>DID document</a> to be resolved (the
version ID could be sequential, or a <a>UUID</a>, or method-specific). Support
for this parameter is OPTIONAL. If present, the associated value MUST be an <a
data-lt="ascii string">ASCII string</a>.
</td>
</tr>
<tr>
<td>
<code>versionTime</code>
</td>
<td>
Identifies a certain version timestamp of a <a>DID document</a> to be resolved.
That is, the <a>DID document</a> that was valid for a <a>DID</a> at a certain
time. Support for this parameter is OPTIONAL. If present, the associated value
MUST be an <a data-lt="ascii string">ASCII string</a> which is a valid XML
datetime value, as defined in section 3.3.7 of <a
href="https://www.w3.org/TR/xmlschema11-2/">W3C XML Schema Definition Language
(XSD) 1.1 Part 2: Datatypes</a> [[XMLSCHEMA11-2]]. This datetime value MUST be
normalized to UTC 00:00, as indicated by the trailing "Z".
</td>
</tr>
<tr>
<td>
<code>hl</code>
</td>
<td>
A resource hash of the <a>DID document</a> to add integrity protection, as
specified in [[?HASHLINK]]. This parameter is non-normative. Support for this
parameter is OPTIONAL. If present, the associated value MUST be an
<a data-lt="ascii string">ASCII string</a>.
</td>
</tr>
</tbody>
</table>
<p>
Implementers as well as <a>DID method</a> specification authors might use
additional DID parameters that are not listed here. For maximum
interoperability, it is RECOMMENDED that DID parameters use the official W3C
DID Specification Registries mechanism [[?DID-SPEC-REGISTRIES]], to avoid
collision with other uses of the same DID parameter with different semantics.
</p>
<p>
DID parameters might be used if there is a clear use case where the parameter
needs to be part of a <a>URI</a> that can be used as a link, or as a <a>resource</a>
in RDF / JSON-LD documents.
</p>
<p>
It is expected that DID parameters will <em>not</em> be used if the same
functionality can be expressed by passing input metadata to a <a>DID resolver</a>.
</p>
<p>
Additional considerations for processing these parameters are discussed in
[[?DID-RESOLUTION]].
</p>
<p>
Some example <a>DID URLs</a> using DID parameters are shown below.
</p>
<pre class="example nohighlight"
title="A DID URL with a 'service' DID parameter">
did:foo:21tDAKCERh95uGgKbJNHYp?service=agent
</pre>
<pre class="example nohighlight"
title="A DID URL with a 'versionTime' DID parameter">
did:foo:21tDAKCERh95uGgKbJNHYp?versionTime=2002-10-10T17:00:00Z
</pre>
<p class="note" title="DID parameters and DID resolution">
The <a>DID resolution</a> and the <a>DID URL dereferencing</a> functions can
be influenced by passing input metadata to a <a>DID resolver</a> that are
not part of the <a>DID URL</a>. (See <a
href="#did-resolution-input-metadata-properties"></a>). This is comparable to
HTTP, where certain parameters could either be included in an HTTP URL, or
alternatively passed as HTTP headers during the dereferencing process. The
important distinction is that DID parameters that are part of the <a>DID
URL</a> should be used to specify <em>what <a>resource</a> is being
identified</em>, whereas input metadata that is not part of the <a>DID URL</a>
should be use to control <em>how that <a>resource</a> is resolved or
dereferenced</em>.
</p>
</section>
<section>
<h2>Path</h2>
<p>
A <a>DID path</a> is identical to a generic <a>URI</a> path and MUST conform to the
<a data-cite="!rfc3986#section-3.3"><code>path-abempty</code></a> ABNF rule in
[[!RFC3986]].
</p>
<p>
A <a>DID method</a> specification MAY specify ABNF rules for <a>DID paths</a>
that are more restrictive than the generic rules in this section.
</p>
<pre class="example nohighlight">
did:example:123456/path
</pre>
</section>
<section>
<h2>Query</h2>
<p>
A <a>DID query</a> is derived from a generic <a>URI</a> query and MUST conform to the
<code>did-query</code> ABNF rule in Section <a href="#did-url-syntax">
</a>. If a <a>DID query</a> is present, it MUST be used
as described in Section <a href="#did-parameters"></a>.
</p>
<p>
A <a>DID method</a> specification MAY specify ABNF rules for <a>DID queries</a>
that are more restrictive than the generic rules in this section.
</p>
<pre class="example nohighlight">