Skip to content

Add onboarding guides, interactive explorer, and spec template - #677

Open
chongkan wants to merge 10 commits into
w3c:mainfrom
chongkan:onboarding-guide
Open

Add onboarding guides, interactive explorer, and spec template#677
chongkan wants to merge 10 commits into
w3c:mainfrom
chongkan:onboarding-guide

Conversation

@chongkan

@chongkan chongkan commented Mar 13, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Summary

  • ONBOARDING.md — 10-step journey from "I want to create a DID method" to registered + reviewed, with links to every repo, spec, and process involved
  • REPO-MAP.md — Ecosystem repository map across W3C, W3C-CCG, and DIF (40+ repos with status, supersession chains)
  • specs/TEMPLATE.md — Standardized 14-section Markdown template for method specifications (8 required, 3 recommended, 3 optional)
  • specs/README.md — Top 10 best-documented methods as reference examples, why Markdown over HTML/ReSpec
  • explorer.html — Interactive single-file tool with 4 tabs: Catalogue (225 methods, filters, sorting), Ecosystem (gap analysis, maturity ladder, opportunity heatmap), Self-Assessment (4-step wizard with overlap detection), Requirements Matrix (grades, gaps)
  • data/ — Structured JSON: methods-registry.json (225 methods), use-cases.json (18 use cases), requirements.json (22 requirements with tiers)

Live Preview

https://chongkan.github.io/did-extensions/explorer.html

Motivation

Addresses #676 — new method authors face fragmented documentation across 40+ repos and frequently mistake registration for certification. These guides consolidate the ecosystem into a clear path and the explorer makes the catalogue actionable.

Then for the Ecosystem Tab, the motivation is to help contributors, existing method maintainers and new comers, get an idea of what has already been build, how they built it, te be able to map the spec and requirements to the technologies and architectures used yo resolve those by others.

image image

This is Use Case coverage stats by All the Methods
image

Requirements Coverage, again across all methods

image image image

For Self Assessment, the form helps with properly mapping the new Did Method to existing paths, OR, allows to add a new use case, This is important in order to have future methods included in the stats, without having to manually adapt the basic legacy json and manually extract its data IF it contain any data. -- Some methods in the registry currently barely have information on the spec .

image

The form helps with assessing the requirements, maps and with providing pertaining information needed for the rest of the community to understand what the other methods do, how they do it etc.

image

The Overlap detection is for identifying other methods that cover specific requirements, both for evaluating possible reusability or for checking out how they do it.

image image

Finally, for existing methods. it helps them identify gaps and areas of improvement.

I think it also helos the Working Group identify those gaps as well for the entire catalogue. e.g. identify what use cases are lacking coverage or effort and which are over covered etc.

image

Test plan

  • explorer.html loads and all 4 tabs render correctly
  • Self-Assessment wizard validates required fields and blocks incomplete submissions
  • Catalogue filters, sorting, and pagination work with 225 methods
  • Gap analysis dashboard renders underserved use cases and weak requirements
  • tooling/validate-extended.js passes on all data files
  • No broken relative links in Markdown files

chongkan added 9 commits March 14, 2026 00:08
@chongkan
Add onboarding guide, repo map, naming convention, and cross-references
a8ff6e6 
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

Signed-off-by: Eduardo Chongkan <e.chongkan@gmail.com>
@chongkan
Add interactive method explorer, self-assessment form, and CI validation
073ba2c 
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.

Signed-off-by: Eduardo Chongkan <e.chongkan@gmail.com>
@chongkan
Add Markdown spec template and require in-repo specifications
eecd56c 
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

Signed-off-by: Eduardo Chongkan <e.chongkan@gmail.com>
@chongkan
Explorer: catalogue-first tabs, gap analysis dashboard, maturity fixes
0402380 
- 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

Signed-off-by: Eduardo Chongkan <e.chongkan@gmail.com>
@chongkan
Schema.org-based DID taxonomy examples + fix opportunity matrix
0193ef4 
- Add schema-did-method.jsonld: 6 methods (web, webvh, key, sns, ethr, peer)
  typed as schema:SoftwareApplication with CRUD as schema:Action subtypes,
  anchor instruments, extends/calls composition relationships
- Add schema-taxonomy-comparison.md: side-by-side vs Hernan's Clusters model
- Fix opportunity matrix: counts now scoped to relevant methods (≥50% use case
  coverage) instead of all L1+ methods globally. Empty cells for non-required
  requirements. Added Relevant + Gaps summary columns.

Signed-off-by: Eduardo Chongkan <e.chongkan@gmail.com>
@chongkan
Add top margin to detail sections for visual breathing room
d82688c 
Signed-off-by: Eduardo Chongkan <e.chongkan@gmail.com>
@chongkan
Coverage matrix: red X for unmet requirements instead of dim dot
8ced8c8 
Signed-off-by: Eduardo Chongkan <e.chongkan@gmail.com>
@chongkan
Fix misaligned requirement descriptions in detail overlay
afb7d50 
reqTechs R-keys in methods-registry.json use a different numbering
than requirements.json (e.g., registry R15 = "Post-quantum" but
requirements.json R15 = "Service Endpoint Support"). Fix by:
- Show req.description from requirements.json as primary text
- Remove approach/techs display from reqTechs (unreliable keys)
- Remove partial (P) indicator from global matrix (same issue)
- Show clear "Gap: not covered" for unmet requirements

Signed-off-by: Eduardo Chongkan <e.chongkan@gmail.com>
@chongkan
Compact overlap display + remove partial noise from use case gaps
a8b14f3 
- Overlap section: one row per shared requirement with methods comma-separated
- Removed "You add" language from overlap cards
- Review tab overlap: single-line comma-separated method list
- Use case gaps: replaced noisy "188 partial" with best partial coverage %

Signed-off-by: Eduardo Chongkan <e.chongkan@gmail.com>
@chongkan chongkan mentioned this pull request Mar 14, 2026
Open
@chongkan
Add Save/Restore progress to Self-Assessment form
8d43ddd 
Persists all form state (use case, assessments, inputs, spec links,
current step) to localStorage. Restore button with saved date appears
in the context bar when prior progress exists.

Signed-off-by: Eduardo Chongkan <e.chongkan@gmail.com>
This was referenced Mar 14, 2026
Open
Open
@ottomorac ottomorac added the pending-did-wg-discussion To be discussed with the DID working group. label Jul 13, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@msporny msporny Awaiting requested review from msporny msporny is a code owner
@apuchitnis apuchitnis Awaiting requested review from apuchitnis apuchitnis is a code owner
@stenreijers stenreijers Awaiting requested review from stenreijers stenreijers is a code owner
@gatemezing gatemezing Awaiting requested review from gatemezing gatemezing is a code owner
@adam-burns adam-burns Awaiting requested review from adam-burns adam-burns is a code owner
@Steffytan Steffytan Awaiting requested review from Steffytan Steffytan is a code owner
@MizukiSonoko MizukiSonoko Awaiting requested review from MizukiSonoko MizukiSonoko is a code owner
@rajivrajani rajivrajani Awaiting requested review from rajivrajani rajivrajani is a code owner
@genaris genaris Awaiting requested review from genaris genaris is a code owner
@ajile-in ajile-in Awaiting requested review from ajile-in ajile-in is a code owner
@KDean-Dolphin KDean-Dolphin Awaiting requested review from KDean-Dolphin KDean-Dolphin is a code owner
@wip-abramson wip-abramson Awaiting requested review from wip-abramson wip-abramson is a code owner
@ottomorac ottomorac Awaiting requested review from ottomorac ottomorac is a code owner
@swcurran swcurran Awaiting requested review from swcurran swcurran is a code owner

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

pending-did-wg-discussion To be discussed with the DID working group.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@chongkan @ottomorac