feat(schemas): rework trait descriptions and property names

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: $"<a id=\"($c)\">($properties | get $c | get title)</a>", Definition: ($properties | get $c | get description) }
 } | to md

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": [