From ef6ce4a7ffcc57b568ddd6fc8ac69860db3b5609 Mon Sep 17 00:00:00 2001 From: Jan Christoph Ebersbach Date: Thu, 21 Nov 2024 10:12:05 +0100 Subject: [PATCH] feat(schemas): rework trait descriptions and property names --- generate-markdown-table.nu | 2 +- schemas/traits.json | 60 +++++++-------- spec/spec.md | 146 ++++++++++++++++++------------------- 3 files changed, 103 insertions(+), 105 deletions(-) diff --git a/generate-markdown-table.nu b/generate-markdown-table.nu index 1cf96e1..1caa0fb 100755 --- a/generate-markdown-table.nu +++ b/generate-markdown-table.nu @@ -1,5 +1,5 @@ #!/usr/bin/env nu let properties = open ./schemas/traits.json | $in.properties -$properties | columns | filter {|c| $c != "name" and $c != "url"} | each {|c| +$properties | columns | filter {|c| $c != "name"} | each {|c| {Trait: $"($properties | get $c | get title)", Definition: ($properties | get $c | get description) } } | to md diff --git a/schemas/traits.json b/schemas/traits.json index f86c7d8..0e5bbf5 100644 --- a/schemas/traits.json +++ b/schemas/traits.json @@ -13,97 +13,97 @@ "modifiable": { "type": "boolean", "title": "Modifiable", - "description": "DID Documents can be modified." + "description": "DID Documents are modifiable, see https://w3c.github.io/did-core/#method-operations." }, "service_endpoints": { "type": "boolean", "title": "Service Endpoints", - "description": "Service endpoints can be added to DID Documents." + "description": "Service endpoints are modifiable, see https://w3c.github.io/did-core/#services." }, "deactivatable": { "type": "boolean", "title": "Deactivatable", - "description": "DID Documents can be deactivated." + "description": "DIDs are deactivatable, see https://w3c.github.io/did-core/#method-operations." }, "deletable": { "type": "boolean", "title": "Deletable", - "description": "DID Documents can be deleted." + "description": "DID method's capability to permanently remove a DID and its associated DID document from the underlying system, rendering the identifier and its historical metadata irrecoverable." }, "fees": { "type": "boolean", "title": "Explicit Fees", - "description": "Creation, modification or deletion of identifiers require a transaction fee, e.g. blockchain-based DID methods often require transaction fees." + "description": "Indicates whether a DID method imposes mandatory transactional costs for creating, updating, or deactivating identifiers. These fees are typically associated with blockchain or distributed ledger-based methods, where computational resources and network consensus mechanisms necessitate economic compensation. " }, "self-certifying": { "type": "boolean", "title": "Self-Certifying", - "description": "DID and the initial DID Document are cryptographically bound to one another, e.g. `did:key`." + "description": "DID method where the cryptographic material used to generate the DID is embedded within the identifier itself, creating an inherent and verifiable cryptographic binding between the DID, its initial DID document, and the associated cryptographic keys. This approach eliminates the need for external verification infrastructure, as the identifier's authenticity can be cryptographically validated through its own intrinsic key material." }, "rotatable_keys": { "type": "boolean", "title": "Rotatable Keys", - "description": "The DID method supports rotation of keys to control the DID." + "description": "Verification methods are modifiable, allowing cryptographic keys can be replaced or updated, see https://w3c.github.io/did-core/#verification-methods." }, - "pre-rotatable_keys": { + "pre-rotation_of_keys": { "type": "boolean", - "title": "Pre-Rotatable Keys", - "description": "Cryptographic keys can be pre-rotated to combat key loss and attacks by quantum computers. - Comment by Juan: one thing working with the KERI WG at DIF taught me was that there are like 10 different capabilities/flows that people refer to when they mean rotation. rotation in case of key exfiltration? manual rotation by controller? regular/automated rotation NOT requiring manual controller intervention?" + "title": "Pre-rotation of Keys", + "description": "Cryptographic mechanism that enables a DID controller to securely commit to a future key rotation without revealing the actual replacement public key. This technique creates a verifiable, one-way commitment to the next cryptographic key pair, preventing malicious actors who compromise the current private key from arbitrarily rotating to a new key of their choosing." }, "modifiable_multi-sig": { "type": "boolean", "title": "Multi-Signature Modifiable", - "description": "The method supports multiple DID controllers, with multiple key signatures required to update or deactivate the DID. - Comment by Juan: threshold versus multisig goes all the way back to christopher allan's BTC pre-DID research and some of the oldest did-wg megathreads, worth picking carefully a definition. joe andreiu probably has something detailed written up about this somewhere.." + "description": "A DID method that supports distributed control of a decentralized identifier through a cryptographic mechanism requiring multiple independent signatures to authorize critical identity operations such as updating or deactivating the DID." }, "human-readable": { "type": "boolean", "title": "Human-readable", - "description": "DIDs are human-readable, e.g. `did:web:example.com:me`." + "description": "A DID method's ability to generate identifiers that are cognitively accessible and memorable to humans, typically incorporating meaningful, domain-specific, or intuitive components." }, "enumerable": { "type": "boolean", "title": "Enumerable", - "description": "All DIDs of this method can be enumerated, i.e. a public registry like a DLT exists that references all existing DIDs." + "description": "A DID method where all identifiers within the system can be comprehensively discovered and listed through a publicly accessible registry, typically implemented using a distributed ledger technology (DLT) or similar transparent infrastructure." }, - "locally_resolvable": { + "resolvable_locally": { "type": "boolean", "title": "Locally Resolvable", - "description": "DID documents can be resolved in an ephameral local context, e.g. `did:peer`." + "description": "A DID method where identifiers and their associated DID documents are valid only within a specific, transient local context." }, - "globally_resolvable": { + "resolvable_globally": { "type": "boolean", "title": "Globally Resolvable", - "description": "DID documents can be resolved globally." + "description": "A DID method where identifiers can be resolved from any network location, enabling universal access to the associated DID document across diverse computational environments and geographic boundaries." }, - "documents": { + "hosted_documents": { "type": "boolean", - "title": "Documents Hosting", - "description": "Additional documents can be hosted with the DID Document and dereferenced via DID paths." + "title": "Document Hosting", + "description": "A DID method's capability to store and retrieve supplementary documents directly associated with the primary DID document through a standardized dereferencing mechanism using DID paths." }, "history": { "type": "boolean", "title": "DID Document History", - "description": "Previous versions of DID documents are available and can be dereferenced." + "description": "A DID method's capability to preserve and retrieve previous versions of a DID document, enabling comprehensive historical traceability of identity metadata and modifications." }, - "history_immutable": { + "history_signed": { "type": "boolean", - "title": "Immutable DID Document History", - "description": "Changes to DID Documents are persisted in an immutable data structure, e.g. a DLT." + "title": "Cryptograhpically signed DID Document History", + "description": "A DID method's capability to record all modifications to the DID document in an append-only, cryptographically verifiable data structure that prevents retroactive alteration or deletion of historical states." }, - "not_hosted": { + "hosted_not": { "type": "boolean", "title": "Not Hosted", - "description": "No hosting of DID Document required, e.g. ephameral `did:key` documents." + "description": "dID document is generated and verified entirely through cryptographic mechanisms, without requiring persistent storage or external hosting infrastructure." }, - "centrally_hosted": { + "hosted_centrally": { "type": "boolean", "title": "Centrally Hosted", - "description": "Hosted on a centralized service, e.g. a web server." + "description": "The DID document is stored and managed through a single, centralized service infrastructure, typically implemented using a web server or controlled repository." }, - "decentrally_hosted": { + "hosted_decentrally": { "type": "boolean", "title": "Decentrally Hosted", - "description": "Hosted on a decentralized service, e.g. a DLT." + "description": "the DID document is stored, managed, and resolved through a distributed infrastructure, typically implemented using decentralized ledger technologies (DLT) or peer-to-peer networks." } }, "required": [ diff --git a/spec/spec.md b/spec/spec.md index 8cfd996..afb14de 100644 --- a/spec/spec.md +++ b/spec/spec.md @@ -2,8 +2,7 @@ **Specification Status:** [Pre-Draft](https://github.com/decentralized-identity/org/blob/master/work-item-lifecycle.md) -**Latest Draft:** -[identity.foundation/did-traits](https://identity.foundation/did-traits) +**Latest Draft:** [identity.foundation/did-traits](https://identity.foundation/did-traits) **Ratified Versions:** @@ -13,12 +12,12 @@ -**Participate:** -~ [GitHub repo](https://github.com/decentralized-identity/did-traits) -~ [File a bug](https://github.com/decentralized-identity/did-traits/issues) -~ [Commit history](https://github.com/decentralized-identity/did-traits/commits/main) +**Participate:** ~ [GitHub repo](https://github.com/decentralized-identity/did-traits) ~ +[File a bug](https://github.com/decentralized-identity/did-traits/issues) ~ +[Commit history](https://github.com/decentralized-identity/did-traits/commits/main) -Except where otherwise noted, this work by the [Decentralized Identity Foundation](https://identity.foundation/) is licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0). +Except where otherwise noted, this work by the [Decentralized Identity Foundation](https://identity.foundation/) is +licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0). ## Abstract @@ -30,21 +29,20 @@ literature and specifications detailed in the [References](#references) section. ## Status of This Document -This is a draft specification being developed within the [Decentralized Identity -Foundation](https://identity.foundation) (DIF). Design work is ongoing, and participants are encouraged to open issues -or otherwise contribute at [the DIF-hosted github repository](https://github.com/decentralized-identity/did-traits), -whether as input to stable versions or as recommendations for future versions. +This is a draft specification being developed within the +[Decentralized Identity Foundation](https://identity.foundation) (DIF). Design work is ongoing, and participants are +encouraged to open issues or otherwise contribute at +[the DIF-hosted github repository](https://github.com/decentralized-identity/did-traits), whether as input to stable +versions or as recommendations for future versions. ## Terminology -[[def:Decentralized Identifiers, Decentralized Identifier, DID]] -~ Unique ID URI string and PKI metadata document format for describing the cryptographic keys and other fundamental PKI -values linked to a unique, user-controlled, self-sovereign identifier in a target system (i.e. blockchain, distributed -ledger). +[[def:Decentralized Identifiers, Decentralized Identifier, DID]] ~ Unique ID URI string and PKI metadata document format +for describing the cryptographic keys and other fundamental PKI values linked to a unique, user-controlled, +self-sovereign identifier in a target system (i.e. blockchain, distributed ledger). -[[def:Traits, Trait]] -~ A distinct, measurable characteristic of a Decentralized Identifier method that influences its behavior, capabilities, -or implementation requirements. +[[def:Traits, Trait]] ~ A distinct, measurable characteristic of a Decentralized Identifier method that influences its +behavior, capabilities, or implementation requirements. ## Structure of this Document @@ -60,37 +58,45 @@ This specification is organized into three main sections: methods based on their traits. This comparison enables implementers to evaluate and select DID methods that best match their requirements. -The specification references supporting literature and related specifications throughout these sections, with complete references provided at the end of the document. +The specification references supporting literature and related specifications throughout these sections, with complete +references provided at the end of the document. ## Definition of Traits +This section systematically defines the characteristics that distinguish and differentiate DID methods. While all DID +methods fundamentally support core operations for creating and retrieving DID documents, they exhibit diverse additional +traits that reflect their unique design. These traits have been identified through analysis of existing DID methods and +their real-world implementations. Each trait definition includes its name and description. + Table generated from JSON Schema: https://identity.foundation/did-traits/schemas/traits.json Contribute here: https://github.com/decentralized-identity/did-traits/blob/main/schemas/traits.json -| Trait | Definition | -| ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Modifiable | DID Documents can be modified. | -| Service Endpoints | Service endpoints can be added to DID Documents. | -| Deactivatable | DID Documents can be deactivated. | -| Deletable | DID Documents can be deleted. | -| Explicit Fees | Creation, modification or deletion of identifiers require a transaction fee, e.g. blockchain-based DID methods often require transaction fees. | -| Self-Certifying | DID and the initial DID Document are cryptographically bound to one another, e.g. `did:key`. | -| Rotatable Keys | The DID method supports rotation of keys to control the DID. | -| Pre-Rotatable Keys | Cryptographic keys can be pre-rotated to combat key loss and attacks by quantum computers. - Comment by Juan: one thing working with the KERI WG at DIF taught me was that there are like 10 different capabilities/flows that people refer to when they mean rotation. rotation in case of key exfiltration? manual rotation by controller? regular/automated rotation NOT requiring manual controller intervention? | -| Multi-Signature Modifiable | The method supports multiple DID controllers, with multiple key signatures required to update or deactivate the DID. - Comment by Juan: threshold versus multisig goes all the way back to christopher allan's BTC pre-DID research and some of the oldest did-wg megathreads, worth picking carefully a definition. joe andreiu probably has something detailed written up about this somewhere.. | -| Human-readable | DIDs are human-readable, e.g. `did:web:example.com:me`. | -| Enumerable | All DIDs of this method can be enumerated, i.e. a public registry like a DLT exists that references all existing DIDs. | -| Locally Resolvable | DID documents can be resolved in an ephameral local context, e.g. `did:peer`. | -| Globally Resolvable | DID documents can be resolved globally. | -| Documents Hosting | Additional documents can be hosted with the DID Document and dereferenced via DID paths. | -| DID Document History | Previous versions of DID documents are available and can be dereferenced. | -| Immutable DID Document History | Changes to DID Documents are persisted in an immutable data structure, e.g. a DLT. | -| Not Hosted | No hosting of DID Document required, e.g. ephameral `did:key` documents. | -| Centrally Hosted | Hosted on a centralized service, e.g. a web server. | -| Decentrally Hosted | Hosted on a decentralized service, e.g. a DLT. | -| Universal Resolver Driver | DID method has a functional Universal Resolver driver. | -| Universal Registrar Driver | DID method has a functional Universal Registrar driver. - Comment by Juan: should there be some kind of maintenance requirement or stalebot caveat? | + + +| Trait | Definition | +| ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Modifiable | DID Documents are modifiable, see https://w3c.github.io/did-core/#method-operations. | +| Service Endpoints | Service endpoints are modifiable, see https://w3c.github.io/did-core/#services. | +| Deactivatable | DIDs are deactivatable, see https://w3c.github.io/did-core/#method-operations. | +| Deletable | DID method's capability to permanently remove a DID and its associated DID document from the underlying system, rendering the identifier and its historical metadata irrecoverable. | +| Explicit Fees | Indicates whether a DID method imposes mandatory transactional costs for creating, updating, or deactivating identifiers. These fees are typically associated with blockchain or distributed ledger-based methods, where computational resources and network consensus mechanisms necessitate economic compensation. | +| Self-Certifying | DID method where the cryptographic material used to generate the DID is embedded within the identifier itself, creating an inherent and verifiable cryptographic binding between the DID, its initial DID document, and the associated cryptographic keys. This approach eliminates the need for external verification infrastructure, as the identifier's authenticity can be cryptographically validated through its own intrinsic key material. | +| Rotatable Keys | Verification methods are modifiable, allowing cryptographic keys can be replaced or updated, see https://w3c.github.io/did-core/#verification-methods. | +| Pre-rotation of Keys | Cryptographic mechanism that enables a DID controller to securely commit to a future key rotation without revealing the actual replacement public key. This technique creates a verifiable, one-way commitment to the next cryptographic key pair, preventing malicious actors who compromise the current private key from arbitrarily rotating to a new key of their choosing. | +| Multi-Signature Modifiable | A DID method that supports distributed control of a decentralized identifier through a cryptographic mechanism requiring multiple independent signatures to authorize critical identity operations such as updating or deactivating the DID. | +| Human-readable | A DID method's ability to generate identifiers that are cognitively accessible and memorable to humans, typically incorporating meaningful, domain-specific, or intuitive components. | +| Enumerable | A DID method where all identifiers within the system can be comprehensively discovered and listed through a publicly accessible registry, typically implemented using a distributed ledger technology (DLT) or similar transparent infrastructure. | +| Locally Resolvable | A DID method where identifiers and their associated DID documents are valid only within a specific, transient local context. | +| Globally Resolvable | A DID method where identifiers can be resolved from any network location, enabling universal access to the associated DID document across diverse computational environments and geographic boundaries. | +| Document Hosting | A DID method's capability to store and retrieve supplementary documents directly associated with the primary DID document through a standardized dereferencing mechanism using DID paths. | +| DID Document History | A DID method's capability to preserve and retrieve previous versions of a DID document, enabling comprehensive historical traceability of identity metadata and modifications. | +| Cryptograhpically signed DID Document History | A DID method's capability to record all modifications to the DID document in an append-only, cryptographically verifiable data structure that prevents retroactive alteration or deletion of historical states. | +| Not Hosted | dID document is generated and verified entirely through cryptographic mechanisms, without requiring persistent storage or external hosting infrastructure. | +| Centrally Hosted | The DID document is stored and managed through a single, centralized service infrastructure, typically implemented using a web server or controlled repository. | +| Decentrally Hosted | the DID document is stored, managed, and resolved through a distributed infrastructure, typically implemented using decentralized ledger technologies (DLT) or peer-to-peer networks. | ## JSON Schema Data Model @@ -110,10 +116,10 @@ like. | did:peer | | | | [`x`](#x) | | | | [`x`](#x) | [`x`](#x) | [`x`](#x) | | | did:dht | [`x`](#x) | [`x`](#x) | [`x`](#x) | [`x`](#x) | [`?`](#?) | | [`?`](#?) | [`x`](#x) | [`?`](#?) | [`?`](#?) | | | [did:webs](https://trustoverip.github.io/tswg-did-method-webs-specification/) | | | | | | | | | | | | -| did:indy | -| did:ebsi | -| did:cheqd | -| [did:iden3](https://github.com/iden3/did-iden3/tree/main) | +| did:indy | | | | | | | | | | | | +| did:ebsi | | | | | | | | | | | | +| did:cheqd | | | | | | | | | | | | +| [did:iden3](https://github.com/iden3/did-iden3/tree/main) | | | | | | | | | | | | ## Appendix @@ -142,39 +148,31 @@ like. ### Informative References -[[def:JSON Schema]] -~ [JSON Schema: A Media Type for Describing JSON Documents](https://json-schema.org/draft/2020-12/json-schema-core.html). -A. Wright, H. Andrews, B. Hutton, G. Dennis. Status: 28 January 2020. -Status: Internet-Draft. +[[def:JSON Schema]] ~ +[JSON Schema: A Media Type for Describing JSON Documents](https://json-schema.org/draft/2020-12/json-schema-core.html). +A. Wright, H. Andrews, B. Hutton, G. Dennis. Status: 28 January 2020. Status: Internet-Draft. ## Patent Policy The Decentralized Identity Foundation has adopted the W3C Patent Policy (2004), as detailed below: -- **Licensing Commitment.** Each contributor agrees to make available any of its - Essential Claims, as defined in the W3C Patent Policy (available at - http://www.w3.org/Consortium/Patent-Policy-20040205), under the W3C RF licensing - requirements Section 5 (http://www.w3.org/Consortium/Patent-Policy-20040205), as - if the contribution was contained in or associated with a W3C Recommendation. - -- **For Exclusion.** Prior to committing any code, bug reports, pull requests, or - other forms of contribution, a contributor may exclude Essential Claims from its - licensing commitments under this agreement by providing written notice of that - intent to DIF's Executive Director (and must received confirmation of receipt - for the exclusion to have effect). The Exclusion Notice for issued patents and - published applications must include the patent number(s) or title and - application number(s), as the case may be, for each of the issued patent(s) or - pending patent application(s) that the contributor wishes to exclude from the - licensing commitment set forth in Section 1 of this patent policy. If an issued - patent or pending patent application that may contain Essential Claims is not - set forth in the Exclusion Notice, those Essential Claims shall continue to be - subject to the licensing commitments under this agreement. The Exclusion Notice - for unpublished patent applications must provide either: (i) the text of the - filed application; or (ii) identification of the specific part(s) of the - contribution whose implementation makes the excluded claim an Essential Claim. - If (ii) is chosen, the effect of the exclusion will be limited to the identified - part(s) of the contribution. DIF's Executive Director will publish Exclusion - Notices. +- **Licensing Commitment.** Each contributor agrees to make available any of its Essential Claims, as defined in the W3C + Patent Policy (available at http://www.w3.org/Consortium/Patent-Policy-20040205), under the W3C RF licensing + requirements Section 5 (http://www.w3.org/Consortium/Patent-Policy-20040205), as if the contribution was contained in + or associated with a W3C Recommendation. + +- **For Exclusion.** Prior to committing any code, bug reports, pull requests, or other forms of contribution, a + contributor may exclude Essential Claims from its licensing commitments under this agreement by providing written + notice of that intent to DIF's Executive Director (and must received confirmation of receipt for the exclusion to have + effect). The Exclusion Notice for issued patents and published applications must include the patent number(s) or title + and application number(s), as the case may be, for each of the issued patent(s) or pending patent application(s) that + the contributor wishes to exclude from the licensing commitment set forth in Section 1 of this patent policy. If an + issued patent or pending patent application that may contain Essential Claims is not set forth in the Exclusion + Notice, those Essential Claims shall continue to be subject to the licensing commitments under this agreement. The + Exclusion Notice for unpublished patent applications must provide either: (i) the text of the filed application; or + (ii) identification of the specific part(s) of the contribution whose implementation makes the excluded claim an + Essential Claim. If (ii) is chosen, the effect of the exclusion will be limited to the identified part(s) of the + contribution. DIF's Executive Director will publish Exclusion Notices. ## Acknowledgements