Naming convention: verb/action model with composable method names - #678
Open
chongkan wants to merge 5 commits into
Open
Naming convention: verb/action model with composable method names#678chongkan wants to merge 5 commits into
chongkan wants to merge 5 commits into
Conversation
Implements all 5 suggestions from w3c#676: 1. ONBOARDING.md — step-by-step "New Method Author Guide" mapping the full journey from DID Core to registration, clarifying what each ecosystem resource provides (catalog vs evaluation vs conformance vs standardization) 2. REPO-MAP.md — comprehensive map of 40+ repositories across W3C, W3C-CCG, and DIF with supersession chains and current status 3. NAMING.md — descriptive method naming convention to improve developer clarity and reduce IP/trademark conflicts 4. data/cross-references.json — structured links between W3C requirements, rubric criteria, test suite sections, and registry directories 5. README.md — updated with clearer language distinguishing registration from evaluation/conformance/standardization, repository structure table, and links to all new resources
Interactive HTML dashboard (explorer.html):
- Registry tab: browse methods with requirements coverage, search/filter
- Self-Assessment tab: 4-step guided form
Step 1: Select use case (18 W3C use cases by category)
Step 2: Mark 22 requirements as covered/partial/uncovered with
explanations — live overlap detection against existing methods
Step 3: Method info with naming convention check and collision detection
Step 4: Review + generate JSON for PR submission
- Requirements Matrix tab: cross-reference coverage across methods
- Real-time overlap alerts suggest contributing to existing methods
or extending them via CODEX composability pattern
Data files (all name-based IDs, no sequential numbering):
- data/use-cases.json: 18 use cases with categories, actors, tags
- data/requirements.json: 22 requirements with tiers, questions
- data/method-template.json: blank template for new submissions
- data/examples/web.json: did:web fully assessed (reference example)
CI validation (tooling/validate-extended.js):
- Validates extended fields when present (non-breaking for existing)
- Name collision detection with auto-suffix suggestion
- Branded name warning (heuristic)
- Category, use case ID, requirement status validation
- Overlap detection against other methods with extended data
- Core requirement gap warnings
Addresses w3c#676 suggestions 1-5.
specs/TEMPLATE.md — standardized 14-section spec template:
8 required (abstract, use case, syntax, DID doc, CRUD, security,
privacy, references) + 3 recommended (trust model, interop,
rationale) + 3 optional (metadata, implementation, W3C coverage)
specs/README.md — template documentation with:
- Top 10 best-documented methods as reference examples
(did:sns, did:web, did:webvh, did:key, did:peer, did:dht,
did:ethr, did:ion, did:pkh, did:jwk)
- Directory structure guide (single-file vs multi-section)
- Markdown vs HTML/ReSpec comparison table
ONBOARDING.md — updated Step 4 and Step 8:
- Step 4: specs must be Markdown, hosted in specs/<method>/
- Step 8: use the Self-Assessment Form to generate JSON,
PR must include both methods/*.json and specs/<method>/spec.md
- specification field points to in-repo Markdown file
- Added spec template and best-documented methods to resources
- Catalogue tab is now default (first tab), Ecosystem second - L3 renamed from "Accepted" to "Under Review" (PR review state) - Maturity filter uses exact match instead of >= threshold - Default catalogue sort: top 5 by stars, rest by reqPct then stage - Stat cards toggle on/off with highlight + "Clear" button for filters - Requirements Matrix: grade column (A+/A/B/C/D/F) + gaps column - Matrix method headers: click name for detail, click header to sort - Ecosystem gap analysis: underserved use cases, weak requirements, regional coverage, stage distribution, opportunity heatmap matrix - Use cases data: added audience arrays for filtering
Rewrite NAMING.md to propose code-style naming for DID methods: - Method names as verbs/actions (like repo.method() in code) - Compound names for extends relationships (did:webvh extends did:web) - Calls relationships visible through naming (did:sns calls did:sol) - Self-check questions for method authors - Code analogies (Python class inheritance, dependency injection) - Links to interactive explorer for relationship visualization
chongkan
requested review from
KDean-Dolphin,
MizukiSonoko,
Steffytan,
adam-burns,
ajile-in,
apuchitnis,
gatemezing,
genaris,
msporny,
ottomorac,
rajivrajani,
stenreijers,
swcurran and
wip-abramson
as code owners
March 13, 2026 12:10
ottomorac
added
the
pending-did-wg-discussion
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Proposes a naming convention for DID methods based on verbs, actions, and composability — the same principles used in code (
repository.method(args)).Key ideas
did:webreads as "identity anchored to the web",did:keyas "identity from a key"extends:did:webvhclearly extendsdid:web(web + verifiable history), like class inheritancecallsrelationships:did:snsdescribes its function (naming service), not the underlying chain it delegates to (did:sol)What changes
NAMING.mdrewritten from a basic guideline into a composable naming model with:extends/callspatterns (new)Motivation
225 registered methods use inconsistent naming. Branded/opaque names (
did:v1,did:cel) tell developers nothing. Verb-based names make the ecosystem self-documenting and composition relationships visible at a glance.Relates to #676, #597, did-methods#10.
Test plan