-
Notifications
You must be signed in to change notification settings - Fork 12
/
Copy pathindex.html
2524 lines (2261 loc) · 112 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 Identifier Resolution (DID Resolution) v0.3</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" class="remove" defer></script>
<script src="./common.js"></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: "did-resolution",
// subtitle
subtitle: "Algorithms and guidelines for resolving DIDs and dereferencing DID URLs",
// if you wish the publication date to be other than today, set this
// publishDate: "2009-08-06",
// 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: ccg.localBiblio,
github: "https://github.com/w3c/did-resolution",
includePermalinks: false,
// if there a publicly available Editor's Draft, this is the link
edDraftURI: "https://w3c.github.io/did-resolution/",
// 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: "Markus Sabadello", url: "https://www.linkedin.com/in/markus-sabadello-353a0821",
company: "Danube Tech", companyURL: "https://danubetech.com/", w3cid: 46729 },
{ name: "Dmitri Zagidulin", url: "https://www.linkedin.com/in/dzagidulin",
company: "MIT CSAIL", companyURL: "http://computingjoy.com/", w3cid: 86708 }
],
// 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: "Markus Sabadello", url: "https://www.linkedin.com/in/markus-sabadello-353a0821",
company: "Danube Tech", companyURL: "https://danubetech.com/", w3cid: 46729 },
{ name: "Dmitri Zagidulin", url: "https://www.linkedin.com/in/dzagidulin",
company: "MIT CSAIL", companyURL: "http://computingjoy.com/", w3cid: 86708 }
],
// group
group: "did",
// name (with the @w3c.org) of the public mailing to which comments are due
wgPublicList: "public-did-wg",
maxTocLevel: 4,
inlineCSS: true
};
</script>
<style type="text/css">
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, ".") ") ";
}
.longdesc {
display: none;
}
.longdesc:target {
display: block;
background-color: #ff9;
}
</style>
</head>
<body data-cite="infra rfc3986">
<section id='abstract'>
<p>
Decentralized identifiers (DIDs) are a new type of identifier for
verifiable, "self-sovereign" digital identity. DIDs are fully under the
control of the DID controller, independent from any centralized registry,
identity provider, or certificate authority. DIDs resolve to DID
Documents — simple documents that describe how to use that specific DID.
</p>
<p>
This document specifies the algorithms and guidelines for resolving DIDs
and dereferencing DID URLs.
</p>
</section>
<section id='sotd'>
<p>
Comments regarding this document are welcome. Please file issues
directly on <a href="https://github.com/w3c/did-resolution/issues/">GitHub</a>,
or send them to
<a href="mailto:[email protected]">[email protected]</a>
(<a href="mailto:[email protected]?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 Science and Technology
Directorate under contracts HSHQDC-17-C-00019. 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>
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 id="introduction">
<h1>Introduction</h1>
<p><a>DID resolution</a> is the process of obtaining a <a>DID document</a> for a given <a>DID</a>. This is one
of four required operations that can be performed on any DID ("Read"; the other ones being "Create", "Update",
and "Deactivate"). The details of these operations differ depending on the <a>DID method</a>.
Building on top of <a>DID resolution</a>, <a>DID URL dereferencing</a> is the process of retrieving a representation
of a resource for a given <a>DID URL</a>. Software and/or hardware that is able to execute these processes is called
a <a>DID resolver</a>.
<p>This
specification defines common
requirements, algorithms including their inputs and results, architectural options, and various considerations for the
<a>DID resolution</a> and <a>DID URL dereferencing</a> processes.</p>
<p>Note that while this specification defines some base-level functionality for DID resolution, the actual steps
required to communicate with a DID's <a>verifiable data registry</a> are defined by the applicable
<a>DID method</a> specification.</p>
<p class="note">The difference between "resolving" a <a>DID</a> and "dereferencing" a <a>DID URL</a>
is being thoroughly discussed by the community. For example, see
<a href="https://github.com/w3c/did-spec/issues/166#issuecomment-464502719">this comment</a>.</p>
<section id="conformance">
<p>
A <dfn class="lint-ignore">conforming DID resolver</dfn> is any algorithm
realized as software and/or hardware that complies with the relevant normative
statements in <a href="#resolving"></a>.
</p>
<p>
A <dfn class="lint-ignore">conforming DID URL dereferencer</dfn> is any
algorithm realized as software and/or hardware that complies with the relevant
normative statements in <a href="#dereferencing"></a>.
</p>
</section>
<section class="informative">
<h2>
Audience
</h2>
<p>
This specification has three primary audiences: implementers of conformant DID methods;
implementers of conformant DID resolvers; and implementers of systems and services
that wish to resolve DIDs using DID resolvers. The intended audience includes,
but is not limited to, software architects, data modelers, application developers,
service developers, testers, operators, and user experience (UX) specialists.
Other people involved in a broad range of standards efforts related to decentralized
identity, verifiable credentials, and secure storage might also be interested in
reading this specification.
</p>
</section>
</section>
<section id="terminology">
<h1>Terminology</h1>
<div data-include="terms.html">
</div>
</section>
<section id="did-parameters">
<h2>DID Parameters</h2>
<p>
The <a>DID URL</a> syntax supports a simple format for parameters
(see section <a href="https://www.w3.org/TR/did-core/#query">Query</a>
in [[DID-CORE]]). 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>
<pre class="example nohighlight"
title="A DID URL with a 'versionTime' DID parameter">
did:example:123?versionTime=2021-05-10T17:00:00Z
</pre>
<pre class="example nohighlight"
title="A DID URL with a 'service' and a 'relativeRef' DID parameter">
did:example:123?service=files&relativeRef=/resume.pdf
</pre>
<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 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. The following table provides common DID parameters that
function the same way across all <a>DID methods</a>. Support for all
<a href="#did-parameters">DID Parameters</a> is OPTIONAL.
</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.
If present, 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.
If present, 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).
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. 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:00 and without sub-second decimal precision.
For example: <code>2020-12-20T19:17:47Z</code>.
</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.
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 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 URL that references a <a>resource</a> with more
precision than using the <a>DID</a> alone. It is expected that DID parameters
are <em>not</em> used if the same functionality can be expressed by passing
input metadata to a <a>DID resolver</a>.
</p>
<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 <a href="#did-resolution-options"></a> or
<a href="#did-url-dereferencing-options"></a> to a <a>DID resolver</a> that are
not part of the <a>DID URL</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 used to control <em>how that <a>resource</a> is resolved or
dereferenced</em>.
</p>
</section>
<section id="resolving">
<h1>DID Resolution</h1>
<p>
The <a>DID resolution</a> functions resolve a <a>DID</a> into a <a>DID
document</a> by using the "Read" operation of the applicable <a>DID method</a>
as described in <a href="https://w3c.github.io/did-core/#method-operations">Method Operations</a>. All
conforming <a>DID resolvers</a> implement the functions below, which have the
following abstract forms:
</p>
<pre title="Abstract functions for DID Resolution">
resolve(did, resolutionOptions) →
« didResolutionMetadata, didDocument, didDocumentMetadata »
resolveRepresentation(did, resolutionOptions) →
« didResolutionMetadata, didDocumentStream, didDocumentMetadata »
</pre>
<p>
The <code>resolve</code> function returns the <a>DID document</a> in its
abstract form (a <a data-cite="INFRA#maps">map</a>). The
<code>resolveRepresentation</code> function returns a byte stream of the <a>DID
Document</a> formatted in the corresponding representation.
</p>
<figure id="resolve-resolverepresentation">
<img style="margin: auto; display: block;"
src="diagrams/diagram-resolve-resolverepresentation.svg" alt="
Diagram illustrating how resolve() returns the DID document data model in
its abstract form and resolveRepresenation() returns it in one of the
conformant representations; conversion is possible using production and
consumption rules.">
<figcaption>
Functions resolve() and resolveRepresentation().
See also: <a class="longdesc-link"
href="#resolve-resolverepresentation-longdesc">narrative description</a>.
</figcaption>
</figure>
<div class="longdesc" id="resolve-resolverepresentation-longdesc">
<p>
The upper middle part of the diagram contains a rectangle with dashed grey outline, containing two
blue-outlined rectangles, one above the other.
The upper, larger rectangle is labeled, in blue, "Core Properties", and contains the following
<a data-cite="INFRA#maps">INFRA</a> notation:
</p>
<pre>
«[
"id" → "example:123",
"verificationMethod" → « «[
"id": "did:example:123#keys-1",
"controller": "did:example:123",
"type": "Ed25519VerificationKey2018",
"publicKeyBase58": "H3C2AVvLMv6gmMNam3uVA"
]» »,
"authentication" → «
"did:example:123#keys-1"
»
]»
</pre>
<p>
The lower, smaller rectangle is labeled, in blue, "Core Representation-specific Entries (JSON-LD)", and
contains the following monospaced <a data-cite="INFRA#maps">INFRA</a> notation:
</p>
<pre>
«[ "@context" → "https://www.w3.org/ns/did/v1" ]»
</pre>
<p>
From the grey-outlined rectangle, three pairs of arrows extend to three
different black-outlined rectangles, aligned in a horizontal row side-by-side, in the bottom half
of the diagram. Each pair of arrows consists of
one blue arrow pointing from the grey-outlined rectangle to the respective
black-outlined rectangle, labeled "produce", and one red arrow pointing in the
reverse direction, labeled "consume". The first black-outlined rectangle in the row
is labeled "application/did+ld+json", and contains
the following JSON-LD data:
</p>
<pre>
{
"@context": ["https://www.w3.org/ns/did/v1"],
"id": "did:example:123",
"verificationMethod": [{
"id": "did:example:123#keys-1",
"controller": "did:example:123",
"type": "Ed25519VerificationKey2018",
"publicKeyBase58": "H3C2AVvLMv6gmMNam3uVA"
}],
"authentication": [
"did:example:123#keys-1"
]
}
</pre>
<p>
The second rectangle in the row is labeled "application/did+json" and contains the following
JSON data:
</p>
<pre>
{
"id": "did:example:123",
"verificationMethod": [{
"id": "did:example:123#keys-1",
"controller": "did:example:123",
"type": "Ed25519VerificationKey2018",
"publicKeyBase58": "H3C2AVvLMv6gmMNam3uVA"
}],
"authentication": [
"did:example:123#keys-1"
]
}
</pre>
<p>
The third rectangle in the row is labeled "application/did+cbor", and contains hexadecimal data.
</p>
<p>
In the left part of the diagram, in the middle, there is a box, with black outline and light gray
background. This box is labeled "VERIFIABLE DATA REGISTRY" and contains a symbol representing a graph
with nodes and arcs. From this box, one arrow, labeled "resolve()", extends upwards and points to the
top half of the diagram where the grey-outlined rectangle is located. Another arrow, labeled
"resolveRepresentation()", extends downwards and points to the bottom half of the diagram, where the
row of three black-outlined rectangles is located.
</p>
</div>
<p>
All conformant <a>DID resolvers</a> MUST implement the <a>DID resolution</a>
functions for at least one <a>DID method</a> and MUST be able to return a
<a>DID document</a> in at least one conformant <a>representation</a>.
</p>
<p>
Conforming <a>DID resolver</a> implementations do not alter the signature of
these functions in any way. <a>DID resolver</a> implementations might map the
<code>resolve</code> and <code>resolveRepresentation</code> functions to a
method-specific internal function to perform the actual <a>DID resolution</a>
process. <a>DID resolver</a> implementations might implement and expose
additional functions with different signatures in addition to the
<code>resolve</code> and <code>resolveRepresentation</code> functions specified
here.
</p>
<p>
The input variables
of the <code>resolve</code> and <code>resolveRepresentation</code> functions are
as follows:
</p>
<dl>
<dt>
did
</dt>
<dd>
This is the <a>DID</a> to resolve. This input is REQUIRED and the value MUST
be a conformant <a>DID</a> as defined in <a href="https://w3c.github.io/did-core/#did-syntax"></a>.
</dd>
<dt>
resolutionOptions
</dt>
<dd>
A <a href="#metadata-structure">metadata structure</a> containing properties
defined in <a href="#did-resolution-options"></a>. This input is
REQUIRED, but the structure MAY be empty.
</dd>
</dl>
<p>
These functions each return multiple values, and no limitations
are placed on how these values are returned together.
The return values of <code>resolve</code> are
<a>didResolutionMetadata</a>, <a>didDocument</a>, and
<a>didDocumentMetadata</a>. The return values of
<code>resolveRepresentation</code> are
<a>didResolutionMetadata</a>, <a>didDocumentStream</a>, and
<a>didDocumentMetadata</a>. These values are described below:
</p>
<dl>
<dt>
<dfn>didResolutionMetadata</dfn>
</dt>
<dd>
A <a href="#metadata-structure">metadata structure</a> consisting of values
relating to the results of the <a>DID resolution</a> process which typically
changes between invocations of the <code>resolve</code> and
<code>resolveRepresentation</code> functions, as it represents data about the
resolution process itself. This structure is REQUIRED, and in the case of an
error in the resolution process, this MUST NOT be empty. This metadata is
defined by <a href="#did-resolution-metadata"></a>. If
<code>resolveRepresentation</code> was called, this structure MUST contain a
<code>contentType</code> property containing the Media Type of the
representation found in the <code>didDocumentStream</code>. If the resolution is
not successful, this structure MUST contain an <code>error</code> property
describing the error.
</dd>
<dt>
<dfn>didDocument</dfn>
</dt>
<dd>
If the resolution is successful, and if the <code>resolve</code> function was
called, this MUST be a <a>DID document</a> abstract data model (a <a
data-cite="INFRA#maps">map</a>) as described in <a href="https://w3c.github.io/did-core/#data-model"></a> that
is capable of being transformed into a <a href="https://w3c.github.io/did-core/#dfn-did-documents">conforming DID Document</a>
(representation), using the production rules specified by the representation.
The value of <code><a href="https://w3c.github.io/did-core/#dfn-id">id</a></code> in the resolved <a>DID document</a> MUST
match the <a>DID</a> that was resolved. If the resolution is unsuccessful, this
value MUST be empty.
</dd>
<dt>
<dfn>didDocumentStream</dfn>
</dt>
<dd>
If the resolution is successful, and if the <code>resolveRepresentation</code>
function was called, this MUST be a byte stream of the resolved <a>DID
document</a> in one of the conformant
<a href="https://w3c.github.io/did-core/#representations">representations</a>. The byte stream might then be
parsed by the caller of the <code>resolveRepresentation</code> function into a
<a href="https://w3c.github.io/did-core/#data-model">data model</a>, which can in turn be validated and
processed. If the resolution is unsuccessful, this value MUST be an empty
stream.
</dd>
<dt>
<dfn>didDocumentMetadata</dfn>
</dt>
<dd>
If the resolution is successful, this MUST be a <a
href="#metadata-structure">metadata structure</a>. This structure contains
metadata about the <a>DID document</a> contained in the <code>didDocument</code>
property. This metadata typically does not change between invocations of the
<code>resolve</code> and <code>resolveRepresentation</code> functions unless the
<a>DID document</a> changes, as it represents metadata about the <a>DID
document</a>. If the resolution is unsuccessful, this output MUST be an empty <a
href="#metadata-structure">metadata structure</a>. Properties defined by this
specification are in <a href="#did-document-metadata"></a>.
</dd>
</dl>
<section>
<h3>DID Resolution Options</h3>
<p>
The possible properties within this structure and their possible values are
registered in the DID Specification Registries [[?DID-SPEC-REGISTRIES]]. This
specification defines the following common properties.
</p>
<dl>
<dt>
accept
</dt>
<dd>
The Media Type of the caller's preferred <a>representation</a> of the <a>DID
document</a>. The Media Type MUST be expressed as an <a data-lt="ascii
string">ASCII string</a>. The <a>DID resolver</a> implementation SHOULD use this
value to determine the <a>representation</a> contained in the returned
<code>didDocumentStream</code> if such a <a>representation</a> is supported and
available. This property is OPTIONAL for the <code>resolveRepresentation</code>
function and MUST NOT be used with the <code>resolve</code> function.
</dd>
</dl>
</section>
<section>
<h3>DID Resolution Metadata</h3>
<p>
The possible properties within this structure and their possible values are
registered in the DID Specification Registries [[?DID-SPEC-REGISTRIES]]. This
specification defines the following DID resolution metadata properties:
</p>
<dl>
<dt>
contentType
</dt>
<dd>
The Media Type of the returned <code>didDocumentStream</code>. This property is
REQUIRED if resolution is successful and if the
<code>resolveRepresentation</code> function was called.
This property MUST NOT
be present if the <code>resolve</code> function was called. The value of this
property MUST be an <a data-lt="ascii string">ASCII string</a> that is the Media
Type of the conformant <a>representations</a>. The
caller of the <code>resolveRepresentation</code> function MUST use this value
when determining how to parse and process the <code>didDocumentStream</code>
returned by this function into the <a href="https://w3c.github.io/did-core/#data-model">data model</a>.
</dd>
<dt>
error
</dt>
<dd>
The error code from the resolution process. This property is REQUIRED when there
is an error in the resolution process. The value of this property MUST be a
single keyword <a data-lt="ascii string">ASCII string</a>. The possible property
values of this field SHOULD be registered in the DID Specification Registries
[[?DID-SPEC-REGISTRIES]]. This specification defines the following
common error values:
<dl>
<dt>
invalidDid
</dt>
<dd>
The <a>DID</a> supplied to the <a>DID resolution</a> function does not conform
to valid syntax. (See <a href="https://w3c.github.io/did-core/#did-syntax"></a>.)
</dd>
<dt>
notFound
</dt>
<dd>
The <a>DID resolver</a> was unable to find the <a>DID document</a>
resulting from this resolution request.
</dd>
<dt>
representationNotSupported
</dt>
<dd>
This error code is returned if the <a>representation</a> requested via the
<code>accept</code> input metadata property is not supported by the <a>DID
method</a> and/or <a>DID resolver</a> implementation.
</dd>
</dl>
</dd>
</dl>
</section>
<section>
<h3>DID Document Metadata</h3>
<p>
The possible properties within this structure and their possible values SHOULD
be registered in the DID Specification Registries [[?DID-SPEC-REGISTRIES]].
This specification defines the following common properties.
</p>
<dl>
<dt><dfn class="lint-ignore">created</dfn></dt>
<dd>
<a>DID document</a> metadata SHOULD include a <code>created</code> property to
indicate the timestamp of the <a href="https://w3c.github.io/did-core/#method-operations">Create operation</a>.
The value of the property MUST be a <a data-cite="INFRA#string">string</a>
formatted as an <a data-cite="XMLSCHEMA11-2#dateTime">XML Datetime</a>
normalized to UTC 00:00:00 and without sub-second decimal precision. For
example: <code>2020-12-20T19:17:47Z</code>.
</dd>
<dt><dfn class="lint-ignore">updated</dfn></dt>
<dd>
<a>DID document</a> metadata SHOULD include an <code>updated</code> property to
indicate the timestamp of the last <a href="https://w3c.github.io/did-core/#method-operations">Update
operation</a> for the document version which was resolved. The value of the
property MUST follow the same formatting rules as the <code>created</code>
property. The <code>updated</code> property is omitted if an Update operation
has never been performed on the <a>DID document</a>. If an <code>updated</code>
property exists, it can be the same value as the <code>created</code> property
when the difference between the two timestamps is less than one second.
</dd>
<dt><dfn class="lint-ignore">deactivated</dfn></dt>
<dd>
If a DID has been <a href="https://w3c.github.io/did-core/#method-operations">deactivated</a>,
<a>DID document</a> metadata MUST include this property with the boolean value
<code>true</code>. If a DID has not been deactivated, this property is OPTIONAL,
but if included, MUST have the boolean value <code>false</code>.
</dd>
<dt><dfn class="lint-ignore">nextUpdate</dfn></dt>
<dd>
<a>DID document</a> metadata MAY include a <code>nextUpdate</code> property if
the resolved document version is not the latest version of the document. It
indicates the timestamp of the next <a href="https://w3c.github.io/did-core/#method-operations">Update
operation</a>. The value of the property MUST follow the same formatting rules
as the <code>created</code> property.
</dd>
<dt><dfn class="lint-ignore">versionId</dfn></dt>
<dd>
<a>DID document</a> metadata SHOULD include a <code>versionId</code> property to
indicate the version of the last <a href="https://w3c.github.io/did-core/#method-operations">Update
operation</a> for the document version which was resolved. The value of the
property MUST be an <a data-lt="ascii string">ASCII string</a>.
</dd>
<dt><dfn class="lint-ignore">nextVersionId</dfn></dt>
<dd>
<a>DID document</a> metadata MAY include a <code>nextVersionId</code> property
if the resolved document version is not the latest version of the document. It
indicates the version of the next <a href="https://w3c.github.io/did-core/#method-operations">Update
operation</a>. The value of the property MUST be an <a data-lt="ascii
string">ASCII string</a>.
</dd>
<dt><dfn>equivalentId</dfn></dt>
<dd>
<p>
A <a>DID method</a> can define different forms of a <a>DID</a> that are
logically equivalent. An example is when a <a>DID</a> takes one form prior to
registration in a <a>verifiable data registry</a> and another form after such
registration. In this case, the <a>DID method</a> specification might need to
express one or more <a>DIDs</a> that are logically equivalent to the resolved
<a>DID</a> as a property of the <a>DID document</a>. This is the purpose of the
<code><a>equivalentId</a></code> property.
</p>
<p>
<a>DID document</a> metadata MAY include an <code>equivalentId</code> property.
If present, the value MUST be a <a
data-cite="INFRA#ordered-set">set</a> where each item is a
<a data-cite="INFRA#string">string</a> that conforms to the rules in Section <a
href="https://w3c.github.io/did-core/#did-syntax"></a>. The relationship is a statement that each
<code><a>equivalentId</a></code> value is logically equivalent to the
<code>id</code> property value and thus refers to the same <a>DID subject</a>.
Each <code><a>equivalentId</a></code> DID value MUST be produced by, and a form
of, the same <a>DID method</a> as the <code>id</code> property value. (e.g.,
<code>did:example:abc</code> == <code>did:example:ABC</code>)
</p>
<p>
A conforming <a>DID method</a> specification MUST guarantee that each
<code><a>equivalentId</a></code> value is logically equivalent to the
<code>id</code> property value.
</p>
<p>
A requesting party is expected to retain the values from the <code>id</code> and
<code><a>equivalentId</a></code> properties to ensure any subsequent
interactions with any of the values they contain are correctly handled as
logically equivalent (e.g., retain all variants in a database so an interaction
with any one maps to the same underlying account).
</p>
<p class="note" title="Stronger equivalence">
<code><a>equivalentId</a></code> is a much stronger form of equivalence than
<code><a href="https://w3c.github.io/did-core/#also-known-as">alsoKnownAs</a></code> because the equivalence MUST be guaranteed by
the governing <a>DID method</a>. <code><a>equivalentId</a></code> represents a
full graph merge because the same <a>DID document</a> describes both the
<code><a>equivalentId</a></code> <a>DID</a> and the <code>id</code> property
<a>DID</a>.
</p>
<p>
If a requesting party does not retain the values from the <code>id</code> and
<code><a>equivalentId</a></code> properties and ensure any subsequent
interactions with any of the values they contain are correctly handled as
logically equivalent, there might be negative or unexpected issues that
arise. Implementers are strongly advised to observe the
directives related to this metadata property.
</p>
</dd>
<dt><dfn>canonicalId</dfn></dt>
<dd>
<p>
The <code><a>canonicalId</a></code> property is identical to the
<code><a>equivalentId</a></code> property except: a) it is associated with a
single value rather than a set, and b) the <a>DID</a> is defined to be
the canonical ID for the <a>DID subject</a> within the scope of the containing
<a>DID document</a>.
</p>
<p>
<a>DID document</a> metadata MAY include a <code>canonicalId</code> property.
If present, the value MUST be a <a
data-cite="INFRA#string">string</a> that conforms to the rules in Section <a
href="https://w3c.github.io/did-core/#did-syntax"></a>. The relationship is a statement that the
<code><a>canonicalId</a></code> value is logically equivalent to the
<code>id</code> property value and that the <code><a>canonicalId</a></code>
value is defined by the <a>DID method</a> to be the canonical ID for the <a>DID
subject</a> in the scope of the containing <a>DID document</a>. A
<code><a>canonicalId</a></code> value MUST be produced by, and a form of, the
same <a>DID method</a> as the <code>id</code> property value. (e.g.,
<code>did:example:abc</code> == <code>did:example:ABC</code>).
</p>
<p>
A conforming <a>DID method</a> specification MUST guarantee that the
<code><a>canonicalId</a></code> value is logically equivalent to the
<code>id</code> property value.
</p>
<p>
A requesting party is expected to use the <code><a>canonicalId</a></code> value
as its primary ID value for the <a>DID subject</a> and treat all other
equivalent values as secondary aliases (e.g., update corresponding primary
references in their systems to reflect the new canonical ID directive).
</p>
<p class="note" title="Canonical equivalence">
<code><a>canonicalId</a></code> is the same statement of equivalence as
<code><a>equivalentId</a></code> except it is constrained to a single value that
is defined to be canonical for the <a>DID subject</a> in the scope of the <a>DID
document</a>. Like <code><a>equivalentId</a></code>,
<code><a>canonicalId</a></code> represents a full graph merge because the same
<a>DID document</a> describes both the <code><a>canonicalId</a></code> DID and
the <code>id</code> property <a>DID</a>.
</p>
<p>
If a resolving party does not use the <code><a>canonicalId</a></code> value as
its primary ID value for the DID subject and treat all other equivalent values
as secondary aliases, there might be negative or unexpected issues that arise
related to user experience. Implementers are strongly advised to observe the
directives related to this metadata property.
</p>
</dd>
</dl>
</section>
<section id="resolving-algorithm">
<h2>Algorithm</h2>
<p>The following <a>DID resolution</a> algorithm MUST be implemented by a conformant <a>DID resolver</a>.</p>
<ol class="algorithm">
<li>Validate that the <var>input <a>DID</a></var> conforms to the `did` rule of the
<a href="https://www.w3.org/TR/did-core/#did-syntax">DID Syntax</a>.
If not, the <a>DID resolver</a> MUST return the following result:
<ol class="algorithm">
<li><b>didResolutionMetadata</b>: <code>«[ "error" → "invalidDid", ... ]»</code></li>
<li><b>didDocument</b>: <code>null</code></li>
<li><b>didDocumentMetadata</b>: <code>«[ ]»</code></li>
</ol>
</li>
<li>Determine whether the DID method of the <var>input <a>DID</a></var> is supported by the <a>DID resolver</a>
that implements this algorithm. If not, the <a>DID resolver</a> MUST return the following result:
<ol class="algorithm">
<li><b>didResolutionMetadata</b>: <code>«[ "error" → "methodNotSupported", ... ]»</code></li>
<li><b>didDocument</b>: <code>null</code></li>
<li><b>didDocumentMetadata</b>: <code>«[ ]»</code></li>
</ol>
</li>
<li>Obtain the <a>DID document</a> for the <var>input <a>DID</a></var> by executing the
<a href="https://www.w3.org/TR/did-core/#method-operations">Read</a> operation against the
<var>input <a>DID</a>'s</var> <a>verifiable data registry</a>, as defined by the <var>input <a>DID method</a></var>:
<ol class="algorithm">
<li>Besides the <var>input <a>DID</a></var>, all additional <var>resolution options</var> of
this algorithm MUST be passed to the
<a href="https://www.w3.org/TR/did-core/#method-operations">Read</a> operation of the
<var>input <a>DID method</a></var>.</li>
<li>If the <var>input <a>DID</a></var> does not exist, return the following result:
<ol class="algorithm">
<li><b>didResolutionMetadata</b>: <code>«[ "error" → "notFound", ... ]»</code></li>
<li><b>didDocument</b>: <code>null</code></li>
<li><b>didDocumentMetadata</b>: <code>«[ ]»</code></li>
</ol>
</li>
<li>If the <var>input <a>DID</a></var> has been deactivated, return the following result:
<ol class="algorithm">
<li><b>didResolutionMetadata</b>: <code>«[ ... ]»</code></li>
<li><b>didDocument</b>: <code>null</code></li>
<li><b>didDocumentMetadata</b>: <code>«[ "deactivated" → true, ... ]»</code></li>
</ol>
</li>
<li>Otherwise, the result of the <a href="https://www.w3.org/TR/did-core/#method-operations">Read</a> operation
is called the <var>output <a>DID document</a></var>. This result MUST be represented in a
<a href="https://www.w3.org/TR/did-core/#representations">conformant representation</a> that
corresponds to the <b>accept</b> <var>resolution option</var>.</li>
<li>Return the following result:
<ol class="algorithm">
<li><b>didResolutionMetadata</b>: <code>«[ ... ]»</code></li>
<li><b>didDocument</b>: <var>output DID document</var></li>
<li><b>didDocumentMetadata</b>: <code>«[ "contentType" → </code><var>output DID document media type</var><code>, ... ]»</code></li>
</ol>
</li>
</ol>
</li>
</ol>
<p class="issue" data-number="5">There is discussion how a DID that has been
<a href="https://www.w3.org/TR/did-core/#method-operations">deactivated</a> should be treated during the <a>DID resolution</a>
process.</p>
<p class="issue" data-number="13">Specify how signatures/proofs on a DID document should be verified during the
DID resolution process.</p>
<p class="issue">Should we define functionality that enables discovery of the list of <a>DID methods</a> or other
capabilities that are supported by a <a>DID resolver</a>? Or is this implementation-specific and out-of-scope
for this spec? For example, see <a href="https://github.com/w3c/did-resolution/issues/26">here</a> and
<a href="https://github.com/w3c/did-resolution/issues/25">here</a>.</p>
</section>
</section>
<section id="dereferencing">
<h1>DID URL Dereferencing</h1>
<p>
The <a>DID URL dereferencing</a> function dereferences a <a>DID URL</a> into a
<a>resource</a> with contents depending on the <a>DID URL</a>'s components,
including the <a>DID method</a>, method-specific identifier, path, query, and
fragment. This process depends on <a>DID resolution</a> of the <a>DID</a>
contained in the <a>DID URL</a>. <a>DID URL dereferencing</a> might involve
multiple steps (e.g., when the DID URL being dereferenced includes a fragment),
and the function is defined to return the final resource after all steps are
completed. The following figure depicts the relationship described
above.
</p>
<figure id="did-url-dereference-overview">
<img style="margin: auto; display: block; width: 75%;"
src="diagrams/did_url_dereference_overview.svg" alt="
DIDs resolve to DID documents; DID URLs contains a DID; DID URLs dereferenced to DID document fragments or
external resources.
" >
<figcaption>
Overview of DID URL dereference
See also: <a class="longdesc-link"
href="#did-url-dereference-overview-longdesc">narrative description</a>.
</figcaption>
</figure>
<div class="longdesc" id="did-url-dereference-overview-longdesc">
<p>
The top left part of the diagram contains a rectangle with black outline, labeled "DID".
</p>
<p>
The bottom left part of the diagram contains a rectangle with black outline, labeled "DID URL".
This rectangle contains four smaller black-outlined rectangles, aligned in a horizontal row adjacent to
each other. These smaller rectangles are labeled, in order, "DID", "path", "query", and "fragment.
</p>
<p>
The top right part of the diagram contains a rectangle with black outline, labeled "DID document".
This rectangle contains three smaller black-outlined rectangles. These smaller rectangles are
labeled "id", "(property X)", and "(property Y)", and are surrounded by multiple series of three
dots (ellipses). A curved black arrow, labeled "DID document - relative fragment dereference", extends
from the rectangle labeled "(property X)", and points to the rectangle labeled "(property Y)".
</p>
<p>
The bottom right part of the diagram contains an oval shape with black outline, labeled "Resource".
</p>
<p>
A black arrow, labeled "resolves to a DID document", extends from the rectangle in the top left part of
the diagram, labeled "DID", and points to the rectangle in the top right part of diagram, labeled
"DID document".
</p>
<p>
A black arrow, labeled "refers to", extends from the rectangle in the top right part of the diagram,
labeled "DID document", and points to the oval shape in the bottom right part of diagram, labeled
"Resource".
</p>
<p>
A black arrow, labeled "contains", extends from the small rectangle labeled "DID" inside the
rectangle in the bottom left part of the diagram, labeled "DID URL", and points to the rectangle
in the top left part of diagram, labeled "DID".
</p>
<p>
A black arrow, labeled "dereferences to a DID document", extends from the rectangle in the bottom left
part of the diagram, labeled "DID URL", and points to the rectangle in the top right part of diagram,
labeled "DID document".
</p>
<p>
A black arrow, labeled "dereferences to a resource", extends from the rectangle in the bottom left
part of the diagram, labeled "DID URL", and points to the oval shape in the bottom right part of diagram,
labeled "Resource".
</p>
</div>
<p>
All conforming <a>DID resolvers</a> implement
the following function which has the following abstract form:
</p>
<pre title="Abstract functions for DID URL Dereferencing">
dereference(didUrl, dereferenceOptions) →
« dereferencingMetadata, contentStream, contentMetadata »