Docs/ontology and registry #749
Conversation
📝 WalkthroughWalkthroughThis PR comprehensively restructures documentation by adding new service pages (Registry, Ontology, Links), adding internal cross-links throughout existing documentation, updating terminology from UUID to W3ID-based references, and refreshing Docusaurus configuration with production URLs and branding changes. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~30 minutes Possibly related issues
Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/docs/Post Platform Guide/getting-started.md (1)
64-85:⚠️ Potential issue | 🟠 MajorFix the auth request body to use
w3idas the user identifier (and drop the eVault URL).The example shows
w3idas an eVault URL and also includesename. This conflicts with the signing/verification flow that identifies users byw3id(eName). Usew3idas the identifier and remove the redundantename. Based on learnings, the correct parameter name isw3idfor user identification.✅ Suggested doc correction
-{ - "ename": "@user.w3id", - "session": "abc123...", - "w3id": "https://evault.example.com/users/123", - "signature": "z..." -} +{ + "w3id": "@user.w3id", + "session": "abc123...", + "signature": "z..." +}- const { ename, session, signature } = req.body; + const { w3id, session, signature } = req.body; // Verify signature using signature-validator ... const verificationResult = await verifySignature({ - eName: ename, + eName: w3id, signature: signature, payload: session, registryBaseUrl: process.env.PUBLIC_REGISTRY_URL, }); - const user = await this.userService.findUser(ename); + const user = await this.userService.findUser(w3id);Also applies to: 76-99
🤖 Fix all issues with AI agents
In `@docs/docs/Post` Platform Guide/mapping-rules.md:
- Line 16: The examples are inconsistent: the top example uses "schemaId":
"global_schema_w3id" while later examples use UUIDs; update the examples that
set "schemaId" (the example occurrences that currently use
"550e8400-e29b-41d4-a716-446655440000") to match the W3ID format used in the
basic structure, or alternatively add a short clarifying sentence after the
basic structure explaining that "schemaId" may be either a W3ID (e.g.,
"global_schema_w3id") or a UUID and show both example variants; locate and edit
the example blocks that define schemaId to ensure consistent formatting or add
the explanatory note.
In `@docs/docs/W3DS` Protocol/Awareness-Protocol.md:
- Around line 28-29: The anchor link targeting fromGlobal is broken: update the
link target (currently pointing to /docs/Infrastructure/Web3-Adapter#fromGlobal)
by either adding a dedicated heading "fromGlobal" (e.g., create a `###
fromGlobal` section so the anchor exists) in the Web3-Adapter document where the
fromGlobal function is discussed, or change the reference to an existing,
specific section such as `#receiving-data-inbound` where fromGlobal is covered;
ensure the Markdown heading text matches the anchor slug so the link resolves.
🧹 Nitpick comments (2)
docs/docs/W3DS Protocol/Signature-Formats.md (1)
324-324: Consider clarifying "unique identifier" terminology.The change from "Create a UUID v4 for the namespace identifier" to "Create a unique identifier for the namespace" makes the terminology more generic. While this provides flexibility, it may leave readers uncertain about what format to use.
Consider either:
- Keeping the UUID v4 specificity if that's the expected format, or
- Adding a brief note about acceptable formats (e.g., "such as a UUID v4")
📝 Optional clarification
2. **Generate Namespace** - - Create a unique identifier for the namespace + - Create a unique identifier for the namespace (e.g., UUID v4)or, if any unique identifier is acceptable:
2. **Generate Namespace** - - Create a unique identifier for the namespace + - Create a globally unique identifier for the namespace (such as UUID v4 or similar)Also applies to: 329-329
docs/docs/W3DS Protocol/Authentication.md (1)
91-101: Align the reference snippet with the “session ID” terminology.The text avoids UUID wording, but the example still uses
uuidv4()andsession. Consider renaming tosessionIdand using a generic cryptographically secure generator (or add a short note that UUIDv4 is an acceptable 128‑bit session ID). This keeps terminology consistent and reduces reader confusion.💡 Possible doc tweak
- const session = uuidv4(); - const offer = `w3ds://auth?redirect=${url}&session=${session}&platform=blabsy`; + const sessionId = crypto.randomUUID(); // 128-bit session ID + const offer = `w3ds://auth?redirect=${url}&session=${sessionId}&platform=blabsy`;
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Fix all issues with AI agents
In `@docs/docusaurus.config.ts`:
- Around line 49-52: The docs configuration's editUrl is pointing to the wrong
repository; update the docs.editUrl string in docusaurus.config.ts to the
correct GitHub repository path for this project (replace
'https://github.com/MetaState-Prototype-Project/metastate/tree/main/docs/docs/'
with the proper repo URL for the current project) so the "Edit this page" links
resolve correctly; ensure the new URL points to the docs folder/branch used by
this site.
In `@docs/src/pages/index.tsx`:
- Around line 11-14: Normalize siteConfig.baseUrl to always end with a trailing
slash and avoid history.push on the homepage to prevent back-button loops: in
the useEffect referencing siteConfig.baseUrl and history.push, compute a safe
baseUrl (ensure it defaults to '/' and appends a '/' if missing), only run the
redirect when the current location pathname is the root (so you don't redirect
from nested pages), and use history.replace instead of history.push to perform
the navigation to `${baseUrl}docs/Getting%20Started/getting-started`; update
references to useEffect, siteConfig.baseUrl, and history.replace/history.push
accordingly.
| docs: { | ||
| sidebarPath: './sidebars.ts', | ||
| // Please change this to your repo. | ||
| // Remove this to remove the "edit this page" links. | ||
| editUrl: | ||
| 'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/', | ||
| editUrl: 'https://github.com/MetaState-Prototype-Project/metastate/tree/main/docs/docs/', | ||
| }, |
There was a problem hiding this comment.
Edit URL points to the wrong repository.
This appears to target a different repo name, which will break “Edit this page” links.
🔧 Proposed fix
- editUrl: 'https://github.com/MetaState-Prototype-Project/metastate/tree/main/docs/docs/',
+ editUrl: 'https://github.com/MetaState-Prototype-Project/prototype/tree/main/docs/docs/',📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| docs: { | |
| sidebarPath: './sidebars.ts', | |
| // Please change this to your repo. | |
| // Remove this to remove the "edit this page" links. | |
| editUrl: | |
| 'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/', | |
| editUrl: 'https://github.com/MetaState-Prototype-Project/metastate/tree/main/docs/docs/', | |
| }, | |
| docs: { | |
| sidebarPath: './sidebars.ts', | |
| editUrl: 'https://github.com/MetaState-Prototype-Project/prototype/tree/main/docs/docs/', | |
| }, |
🤖 Prompt for AI Agents
In `@docs/docusaurus.config.ts` around lines 49 - 52, The docs configuration's
editUrl is pointing to the wrong repository; update the docs.editUrl string in
docusaurus.config.ts to the correct GitHub repository path for this project
(replace
'https://github.com/MetaState-Prototype-Project/metastate/tree/main/docs/docs/'
with the proper repo URL for the current project) so the "Edit this page" links
resolve correctly; ensure the new URL points to the docs folder/branch used by
this site.
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In @.github/workflows/docusaurus.yml:
- Line 4: The workflow currently triggers on pull_request which allows the
deploy job to run for PRs; modify the deploy job (named "deploy" in the
docusaurus.yml) to skip runs on PR events by adding a job-level condition such
as checking the event name or branch (e.g., add an if condition like
github.event_name != 'pull_request' or require github.ref == 'refs/heads/main'
&& github.event_name == 'push') so deploy only runs on real pushes to the
production branch; apply the same guard to the other affected deploy-related
jobs referenced around the block noted (lines 39-57) to prevent accidental PR
deployments.
coodos
force-pushed
the
docs/ontology-and-registry
branch
from
81a7183 to
e197a8e
Compare
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@docs/docusaurus.config.ts`:
- Around line 23-28: The projectName value in the Docusaurus config is
incorrect; update the projectName symbol in the configuration (currently set to
'metastate') to 'prototype' so deploy scripts that rely on projectName (e.g.,
the GIT_USER yarn deploy flow referenced in docs/README.md) will target the
correct GitHub repo; leave organizationName unchanged and run a quick deploy
dry-run to confirm settings.
| // Production URL: hosted at docs.w3ds.metastate.foundation | ||
| url: 'https://docs.w3ds.metastate.foundation', | ||
| baseUrl: '/', | ||
|
|
||
| // GitHub pages deployment config. | ||
| // If you aren't using GitHub pages, you don't need these. | ||
| organizationName: 'MetaState-Prototype-Project', // Usually your GitHub org/user name. | ||
| projectName: 'MetaState-Prototype-Project.github.io', // Usually your repo name. | ||
| organizationName: 'MetaState-Prototype-Project', | ||
| projectName: 'metastate', |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Look for Docusaurus deploy / gh-pages usage and repo configuration
echo "=== Searching for deploy references ==="
rg -n "docusaurus deploy|gh-pages|npm run deploy|yarn deploy|pnpm deploy" --max-count=20
echo -e "\n=== Checking package.json for deploy scripts ==="
if [ -f "package.json" ]; then
cat package.json | jq '.scripts | select(.deploy or .gh)' 2>/dev/null || grep -A 5 -B 5 "deploy\|gh-pages" package.json || echo "No deploy scripts found"
fi
echo -e "\n=== Checking docs/package.json ==="
if [ -f "docs/package.json" ]; then
cat docs/package.json | jq '.scripts | select(.deploy or .gh)' 2>/dev/null || grep -A 5 -B 5 "deploy\|gh-pages" docs/package.json || echo "No deploy scripts found"
fi
echo -e "\n=== GitHub workflows related to docs ==="
if [ -d ".github/workflows" ]; then
find .github/workflows -name "*.yml" -o -name "*.yaml" | head -20
fi
echo -e "\n=== Repository name from git config ==="
git config --get remote.origin.url || echo "Not a git repo"Repository: MetaState-Prototype-Project/prototype
Length of output: 1398
🏁 Script executed:
#!/bin/bash
# Examine docusaurus.config.ts to see full context
echo "=== Full docusaurus.config.ts (first 50 lines) ==="
head -50 docs/docusaurus.config.ts
echo -e "\n=== Checking for baseUrl and deploying related config ==="
rg -n "baseUrl|organizationName|projectName|url:" docs/docusaurus.config.ts -A 1 -B 1Repository: MetaState-Prototype-Project/prototype
Length of output: 1993
🏁 Script executed:
#!/bin/bash
# Look for any GitHub Actions workflows that might handle docs deployment
echo "=== Looking for docs-related workflows ==="
find .github/workflows -type f \( -name "*.yml" -o -name "*.yaml" \) 2>/dev/null | while read file; do
echo "File: $file"
if grep -q "docs\|docusaurus\|gh-pages" "$file"; then
echo "--- Content ---"
cat "$file"
echo ""
fi
doneRepository: MetaState-Prototype-Project/prototype
Length of output: 1817
Update projectName to match the actual repository name.
Line 28 sets projectName to 'metastate', but the repository is prototype. While the GitHub workflow bypasses docusaurus deploy and uses GitHub Pages directly, the docs/README.md instructs users to run GIT_USER=<username> yarn deploy, which relies on these settings. Running the deploy script would attempt to push to the wrong repository. Change projectName to 'prototype'.
🤖 Prompt for AI Agents
In `@docs/docusaurus.config.ts` around lines 23 - 28, The projectName value in the
Docusaurus config is incorrect; update the projectName symbol in the
configuration (currently set to 'metastate') to 'prototype' so deploy scripts
that rely on projectName (e.g., the GIT_USER yarn deploy flow referenced in
docs/README.md) will target the correct GitHub repo; leave organizationName
unchanged and run a quick deploy dry-run to confirm settings.
| ### Human-facing viewer | ||
|
|
||
| - **GET /** — Renders a viewer page that lists schemas and supports search. Optional query `?q=...` filters by title or ID; `?schema=<id>` shows one schema. | ||
| - **GET /schema/:id** — Same viewer with a specific schema selected (permalink). |
There was a problem hiding this comment.
would be really nice if we had at least one example of each type somewhere. E.g., I have no idea from the top of my head how a "ledger" meta envelope may look like
There was a problem hiding this comment.
@nsergey82 for these examples I imagine the better place would be the ontology viewer and not the docs, as then the docs may start to get more bloated.
|
|
||
| The Registry enables clients and services to: | ||
|
|
||
| - **Resolve W3IDs** to service endpoints (eVault URIs, platform URLs) |
There was a problem hiding this comment.
not any w3ids, just the ename (according to out definitions)?
|
|
||
| - **Resolve W3IDs** to service endpoints (eVault URIs, platform URLs) | ||
| - **Obtain entropy** as signed JWTs for use in provisioning and other operations | ||
| - **Verify tokens** via a public JWK endpoint |
There was a problem hiding this comment.
does it actually verify tokens, or merely provide us with material needed for such verification on our side?
|
|
||
| ### GET /list | ||
|
|
||
| Returns all registered vault entries (ename, uri, evault) with URIs resolved (e.g. for health checks or discovery). No authentication required. |
There was a problem hiding this comment.
this is obviously one of the candidates for pagination, but also rate limiting
There was a problem hiding this comment.
pagination for this is being added
Description of change
Add docs for ontology and registry
Issue Number
closes #751
Type of change
Change checklist
Summary by CodeRabbit
Release Notes
Documentation
Site Updates
✏️ Tip: You can customize this high-level summary in your review settings.