From faa5a168ad3322f6dbc6f38dc90287816cb77240 Mon Sep 17 00:00:00 2001 From: Jan Christoph Ebersbach Date: Tue, 3 Sep 2024 18:33:00 +0200 Subject: [PATCH] feat: convert traits into JSON Schema #3 --- generate-markdown-table.nu | 5 ++ schemas/traits.json | 103 +++++++++++++++++++++++++++++++++++++ spec/spec.md | 38 +++++++------- 3 files changed, 128 insertions(+), 18 deletions(-) create mode 100755 generate-markdown-table.nu create mode 100644 schemas/traits.json diff --git a/generate-markdown-table.nu b/generate-markdown-table.nu new file mode 100755 index 0000000..1cf96e1 --- /dev/null +++ b/generate-markdown-table.nu @@ -0,0 +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| + {Trait: $"($properties | get $c | get title)", Definition: ($properties | get $c | get description) } +} | to md diff --git a/schemas/traits.json b/schemas/traits.json new file mode 100644 index 0000000..a601eed --- /dev/null +++ b/schemas/traits.json @@ -0,0 +1,103 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "https://identity.foundation/did-traits/schmeas/traits.json", + "title": "DID Traits", + "type": "object", + "properties": { + "name": { + "type": "string", + "title": "DID Method Name", + "description": "DID Method Name, see https://w3c.github.io/did-core/#did-syntax.", + "pattern": "^[a-z0-9]+$" + }, + "url": { + "type": "string", + "title": "DID Specification URL.", + "description": "DID Specification URL.", + "format": "uri" + }, + "deactivatable": { + "type": "boolean", + "title": "Deactivatable", + "description": "DID Documents can be deactivated / deleted." + }, + "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." + }, + "globally": { + "type": "boolean", + "title": "Globally resolvable", + "description": "DIDs can be resolved globally, i.e. the current DID document can be resolved globally from every point as opposed to a DID that just exists in a local context." + }, + "history": { + "type": "boolean", + "title": "History available", + "description": "Previous versions of DID document are available and can be looked up." + }, + "immutable": { + "type": "boolean", + "title": "Immutable History", + "description": "Changes to DID Documents are persisted in an immutable data structure, e.g. a DLT." + }, + "human-readable": { + "type": "boolean", + "title": "Human-readable", + "description": "DID can be read and remembered by humans, e.g. `did:web:example.com:me`." + }, + "pre-rotation": { + "type": "boolean", + "title": "Key Pre-Rotation", + "description": "Cryptographic keys can be pre-rotated to combat key loss and attacks by quantum computers." + }, + "modifiable": { + "type": "boolean", + "title": "Modifiable", + "description": "DID Documents can be modified." + }, + "self-certification": { + "type": "boolean", + "title": "Self-Certification", + "description": "The initial DID Document is securely derived from the DID itself, e.g. `did:key`." + }, + "self-creation": { + "type": "boolean", + "title": "Self-Creation", + "description": "DID Document is generative / derived from the DID without having to access any external system, e.g. any `did:key` DID can be derived from the initial public key." + }, + "fees": { + "type": "boolean", + "title": "Explicit Fees", + "description": "Creation, modification or deletion of identifiers trigger transaction fees, e.g. blockchain-based DID methods often require transaction fees." + }, + "hosting": { + "type": "boolean", + "title": "Hosting", + "description": "What kind of hosting is require? None, centralized, decentralized.." + }, + "rotatable": { + "type": "boolean", + "title": "Rotatable", + "description": "The DID method supports rotation of the keys to control the DID (worth calling this out, in addition to pre-rotation, as many methods do not support) - 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-sig": { + "type": "boolean", + "title": "Multi-sig", + "description": "The method supports multiple DID controllers, with multiple key signatures required to update or deactivate the DID - Comment by Juan: same-- 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.." + }, + "globally_dereferenceable": { + "type": "boolean", + "title": "Globally dereferenceable", + "description": "The DID method supports extensible DID URLs to external resources or to specific versions of the DID Document. - Comment by Juan: split into 3 diff ones: service-specific DID URL support, ?versionTime= support, and ?versionId= support . a surprising number of methods support 1 or 2 but not all 3!." + }, + "publicly_accessible": { + "type": "boolean", + "title": "Publicly Accessible", + "description": "The DID method has a functional Universal Resolver AND Universal Registrar driver - Comment by Juan: should there be some kind of maintenance requirement or stalebot caveat?." + } + }, + "required": [ + "name" + ] +} diff --git a/spec/spec.md b/spec/spec.md index 0ef601e..4a229f6 100644 --- a/spec/spec.md +++ b/spec/spec.md @@ -61,24 +61,26 @@ TODO ## Traits -| Trait | Description | -| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Deactivatable | DID Documents deactivated / deleted | -| Enumerable | All DIDs of this method can be enumerated, i.e. a public registry like a DLT exists that references all existing DIDs | -| Globally resolvable | DIDs can be resolved globally, i.e. the current DID document can be resolved globally from every point as opposed to a DID that just exists in a local context | -| History available | Previous versions of DID document are available and can be looked up | -| Immutable History | Changes to DID Documents are persisted in an immutable data structure, e.g. a DLT | -| Human-readable | DID can be read and remembered by humans, e.g. `did:web:example.com:me` | -| Key Pre-Rotation | Cryptographic keys can be pre-rotated to combat key loss and attacks by quantum computers | -| Modifiable | DID Documents can be modified | -| Self-Certification | The initial DID Document is securely derived from the DID itself, e.g. `did:key` | -| Self-Creation | DID Document is generative / derived from the DID without having to access any external system, e.g. any `did:key` DID can be derived from the initial public key | -| Explicit Fees | Creation, modification or deletion of identifiers trigger transaction fees, e.g. blockchain-based DID methods often require transaction fees | -| Hosting | What kind of hosting is require? None, centralized, decentralized. | -| Globally dereferenceable | The DID method supports extensible DID URLs to external resources or to specific versions of the DID Document. - Comment by Juan: split into 3 diff ones: service-specific DID URL support, ?versionTime= support, and ?versionId= support . a surprising number of methods support 1 or 2 but not all 3! | -| Rotatable | The DID method supports rotation of the keys to control the DID (worth calling this out, in addition to pre-rotation, as many methods do not support) - 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-sig | The method supports multiple DID controllers, with multiple key signatures required to update or deactivate the DID - Comment by Juan: same-- 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. | -| Publicly Accessible | The DID method has a functional Universal Resolver AND Universal Registrar driver - Comment by Juan: should there be some kind of maintenance requirement or stalebot caveat? | +Table generated from JSON Schema: https://identity.foundation/did-traits/schmeas/traits.json + +| Trait | Definition | +| ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Deactivatable | DID Documents can be deactivated / deleted. | +| Enumerable | All DIDs of this method can be enumerated, i.e. a public registry like a DLT exists that references all existing DIDs. | +| Globally resolvable | DIDs can be resolved globally, i.e. the current DID document can be resolved globally from every point as opposed to a DID that just exists in a local context. | +| History available | Previous versions of DID document are available and can be looked up. | +| Immutable History | Changes to DID Documents are persisted in an immutable data structure, e.g. a DLT. | +| Human-readable | DID can be read and remembered by humans, e.g. `did:web:example.com:me`. | +| Key Pre-Rotation | Cryptographic keys can be pre-rotated to combat key loss and attacks by quantum computers. | +| Modifiable | DID Documents can be modified. | +| Self-Certification | The initial DID Document is securely derived from the DID itself, e.g. `did:key`. | +| Self-Creation | DID Document is generative / derived from the DID without having to access any external system, e.g. any `did:key` DID can be derived from the initial public key. | +| Explicit Fees | Creation, modification or deletion of identifiers trigger transaction fees, e.g. blockchain-based DID methods often require transaction fees. | +| Hosting | What kind of hosting is require? None, centralized, decentralized.. | +| Rotatable | The DID method supports rotation of the keys to control the DID (worth calling this out, in addition to pre-rotation, as many methods do not support) - 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-sig | The method supports multiple DID controllers, with multiple key signatures required to update or deactivate the DID - Comment by Juan: same-- 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.. | +| Globally dereferenceable | The DID method supports extensible DID URLs to external resources or to specific versions of the DID Document. - Comment by Juan: split into 3 diff ones: service-specific DID URL support, ?versionTime= support, and ?versionId= support . a surprising number of methods support 1 or 2 but not all 3!. | +| Publicly Accessible | The DID method has a functional Universal Resolver AND Universal Registrar driver - Comment by Juan: should there be some kind of maintenance requirement or stalebot caveat?. | ## Traits by Identifier