Skip to content

Commit

Permalink
separated did metadata normative/informative statements (#128)
Browse files Browse the repository at this point in the history 
* separated did metadata normative/informative statements per our previous discussions

---------

Signed-off-by: 2byrds <[email protected]>
  • Loading branch information
@2byrds
2byrds authored Feb 2, 2024
1 parent fcb31cd commit f6177aa
Show file tree
Hide file tree
Showing 2 changed files with 22 additions and 43 deletions.
6 changes: 6 additions & 0 deletions spec/appendix.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,12 @@ See also: decentralized identifier, [ref: self-certifying identifier (SCID)].
[[def: DID document, DID documents]]
~ A set of data describing the subject of a [[ref: DID]], as defined by [DID Core](https://www.w3.org/TR/did-core/#dfn-did-documents). See also section [DID Documents](#did-documents).

[[def: DID resolution metadata]]
~ DID resolution metadata is metadata about the DID Resolution process that was performed in order to obtain the DID document for a given DID. See also [DID Resolution Metadata](https://www.w3.org/TR/did-core/#did-resolution-metadata) in the DID Core specification.

[[def: DID document metadata]]
~ DID document metadata is metadata about the DID and the DID document that is the result of the DID Resolution process. See also [DID Document Metadata](https://www.w3.org/TR/did-core/#did-document-metadata) in the DID Core specification.

[[def: direct mode]]
~ an operational mode of the [[ref: KERI]] protocol where a controller and a verifier of an [[ref: AID]] exchange the [[ref: KEL]] of the AID directly, as defined by the [KERI whitepaper](https://github.com/SmithSamuelM/Papers/blob/master/whitepapers/KERI_WP_2.x.web.pdf). See [WebOfTrust glossary](https://weboftrust.github.io/WOT-terms/docs/glossary/direct-mode) for more detail.

Expand Down
59 changes: 16 additions & 43 deletions spec/did_metadata.md
View file
Original file line number Diff line number Diff line change
@@ -1,39 +1,21 @@
## DID Metadata

This section describes the support of the `did:webs` method for metadata, as described in sections
[DID Resolution Metadata](https://www.w3.org/TR/did-core/#did-resolution-metadata) and
[DID Document Metadata](https://www.w3.org/TR/did-core/#did-document-metadata) in the DID Core specification.

This metadata is returned by a DID Resolver in addition to the DID document. Also see the
[DID Resolution](https://w3c-ccg.github.io/did-resolution/) specification for further details.
This section describes the support of the `did:webs` method for metadata, including [[ref: DID resolution metadata]] and [[ref: DID document metadata]]. This metadata is returned by a DID Resolver in addition to the DID document. Also see the [DID Resolution](https://w3c-ccg.github.io/did-resolution/) specification for further details.

### DID Resolution Metadata

DID resolution metadata is metadata about the DID Resolution process that was performed in order to obtain
the DID document for a given DID.

At the moment, this specification does not define the use of
any specific DID Resolution metadata properties in the `did:webs` method, but may in the future include
various metadata, such as which KERI Watchers were used during the resolution process.
At the moment, this specification does not define the use of any specific [[ref:DID resolution metadata]] properties in the `did:webs` method, but may in the future include various metadata, such as which KERI Watchers were used during the resolution process.

### DID Document Metadata

DID document metadata is metadata about the DID and the DID document that is the result of the DID
Resolution process. This specification defines how various DID document metadata properties are used
by the `did:webs` method.
This section of the specification defines how various DID document metadata properties are used by the `did:webs` method.

#### Use of `versionId`

This DID document metadata property indicates the current version of the DID document that has been
resolved.

In the case of `did:webs`, this is defined to be the sequence number (i.e. the `s` field) of
the last event in the [[ref: KERI event stream]] that was used to construct the DID document according to
the rules in section [DID Document from KERI Events](#did-document-from-keri-events).
The `versionId` DID document metadata property indicates the current version of the DID document that has been resolved.

If the DID parameter `versionId` (see section [Support for `versionId`](#support-for-versionid)) was used when
resolving the `did:webs` DID, and if the DID Resolution process was successful, then this corresponding DID
document metadata property is guaranteed to be equal to the value of the DID parameter.
1. `did:webs` versionId is defined to be the sequence number (i.e. the `s` field) of the last event in the [[ref: KERI event stream]] that was used to construct the DID document according to the rules in section [DID Document from KERI Events](#did-document-from-keri-events).
1. If the DID parameter `versionId` (see section [Support for `versionId`](#support-for-versionid)) was used when resolving the `did:webs` DID, and if the DID Resolution process was successful, then this corresponding DID document metadata property is guaranteed to be equal to the value of the DID parameter.

Example:

Expand All @@ -53,16 +35,11 @@ Example:

#### Use of `nextVersionId`

This DID document metadata property indicates the next version of the DID document after the version that has been
resolved.
The `nextVersionId` DID document metadata property indicates the next version of the DID document after the version that has been resolved.

In the case of `did:webs`, this is defined to be the sequence number (i.e. the `s` field) of
the next event in the [[ref: KERI event stream]] after the last one that was used to construct the DID document
according to the rules in section [DID Document from KERI Events](#did-document-from-keri-events).

This DID document metadata property is only present if the DID parameter `versionId`
(see section [Support for `versionId`](#support-for-versionid)) was used when resolving the `did:webs` DID, and
if the value of that DID parameter was not the sequence number of the last event in the [[ref: KERI event stream]].
1. `did:webs` `nextVersionId` is defined to be the sequence number (i.e. the `s` field) of the next event in the [[ref: KERI event stream]] after the last one that was used to construct the DID document according to the rules in section [DID Document from KERI Events](#did-document-from-keri-events).
1. This DID document metadata property is only present if the DID parameter `versionId`
(see section [Support for `versionId`](#support-for-versionid)) was used when resolving the `did:webs` DID, and if the value of that DID parameter was not the sequence number of the last event in the [[ref: KERI event stream]].

Example:

Expand All @@ -83,18 +60,14 @@ Example:

#### Use of `equivalentId`

This DID document metadata property indicates other DIDs that refer to the same subject and are logically equivalent
to the DID that has been resolved. It is similar to the `alsoKnownAs` DID document property (see section
[Also Known As](#also-known-as)), but it has even stronger semantics, insofar as the logical equivalence is
guaranteed by the DID method itself.
The `equivalentId` DID document metadata property indicates other DIDs that refer to the same subject and are logically equivalent to the DID that has been resolved. It is similar to the `alsoKnownAs` DID document property (see section [Also Known As](#also-known-as)), but it has even stronger semantics, insofar as the logical equivalence is guaranteed by the DID method itself.

In the case of `did:webs`, this metadata property SHOULD contain a list of the controller AID [[ref: designated aliases]] `did:webs` DIDs that differ
in the domain name and/or port portion of the [[ref: method-specific identifier]]
1. The `did:webs` `equivalentId` metadata property SHOULD contain a list of the controller AID [[ref: designated aliases]] `did:webs` DIDs that differ
in the [[ref:host]] and/or port portion of the [[ref: method-specific identifier]]
but share the same AID. Also see section [[ref:AID controlled identifiers]].
1. `equivalentId` depends on the controller AIDs array of [[ref: designated aliases]]. A `did:webs` identifier MUST not verify unless it is found in the `equivalentId` metadata that corresponds to the [[ref: designated aliases]].

Note that [[ref:AID controlled identifiers]] like `did:web` and `did:keri` identifiers with the same AID are not listed in `equivalentId` because they do not have the same DID method. A `did:web` identifier with the same domain and AID does not have the same security characteristics as the `did:webs` identifier. Conversely, a `did:keri` identifier with the same AID has the same security characterisitcs but not the same dependence on the web. For these reasons, they are not listed in `equivalentId`.

`equivalentId` depends on the controller AIDs array of [[ref: designated aliases]]. A `did:webs` identifier is not valid unless it is found in the `equivalentId` metadata that corresponds to the [[ref: designated aliases]].
> Note that [[ref:AID controlled identifiers]] like `did:web` and `did:keri` identifiers with the same AID are not listed in `equivalentId` because they do not have the same DID method. A `did:web` identifier with the same domain and AID does not have the same security characteristics as the `did:webs` identifier. Conversely, a `did:keri` identifier with the same AID has the same security characterisitcs but not the same dependence on the web. For these reasons, they are not listed in `equivalentId`.
Example:

Expand All @@ -114,4 +87,4 @@ Example:
]
}
}
```
```

0 comments on commit f6177aa

Please sign in to comment.