From f6177aac2553dfcf1228a86106ddb48e181a8484 Mon Sep 17 00:00:00 2001 From: Lance Date: Fri, 2 Feb 2024 08:13:36 -0500 Subject: [PATCH] separated did metadata normative/informative statements (#128) * separated did metadata normative/informative statements per our previous discussions --------- Signed-off-by: 2byrds <2byrds@gmail.com> --- spec/appendix.md | 6 +++++ spec/did_metadata.md | 59 ++++++++++++-------------------------------- 2 files changed, 22 insertions(+), 43 deletions(-) diff --git a/spec/appendix.md b/spec/appendix.md index e1b04cf..6b225ba 100644 --- a/spec/appendix.md +++ b/spec/appendix.md @@ -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. diff --git a/spec/did_metadata.md b/spec/did_metadata.md index eb8b5e0..d7725d3 100644 --- a/spec/did_metadata.md +++ b/spec/did_metadata.md @@ -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: @@ -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: @@ -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: @@ -114,4 +87,4 @@ Example: ] } } -``` +``` \ No newline at end of file