Files
pages/docs/design/uri.md
T
Anya Tokugawa c1175d389f Implement Knowledge City platform, organizer and DAV integration
Capture accumulated application, UI, CLI, regression tests and design documentation changes, including task project mapping and default CalDAV list naming.

Keep deployment data, backups, local credentials and build artifacts out of Git. Move the Compose enrollment token to an ignored local environment file.
2026-09-27 14:44:43 +09:00

73 lines
3.6 KiB
Markdown

# URI Model
URI prefixes identify access surfaces, not object meaning. Semantic paths,
Page UUIDs, Revisions, and projections remain separate.
## Canonical namespaces
| Prefix | Purpose | Status |
| --- | --- | --- |
| `/...` | Language-neutral semantic Viewer path | active |
| `/e/-/...` | Editor for a semantic path | active |
| `/o/uuid:<uuid>` | Page/Object access by stable UUID | active |
| `/o/path:<path>` | Object resolver through a semantic path | active |
| `/r/history/<uuid>` | Revision history for a Page UUID | active |
| `/r/view/<revision-uuid>` | Immutable Revision view | active |
| `/r/diff/<before>/<after>` | Revision comparison | active |
| `/l/uuid:<uuid>` | Semantic path bindings for a Page UUID | active |
| `/v/...` | Explicit non-canonical projection | active |
| `/v/raw/path:/...` | Current Document payload selected through a semantic path | active |
| `/v/raw/uuid:<uuid>` | Current Document payload selected through a Page UUID | active |
| `/v/raw/rev:<revision-uuid>` | Immutable Document payload selected through a Revision | active |
| `/v/raw/asset:<type>:<name>` | Administrator authoring projection of the current mutable Asset HEAD | active |
| `/_/obj/sha256:<hash>` | Authorized immutable Document payload by content identity | active |
| `/_/api/...` | Internal/API surface | active |
| `/:/...` | System command and creation surface | active |
| `/-/...` | System configuration surface | active |
| `/s/...` | Delegated share projection | reserved |
| `/a/...` | Alias projection | reserved |
| `/u/{username}` | User profile and user-Wiki subtree | active |
| `/g/{groupname}` | Group profile and group-Wiki subtree | designed |
## Rules
Task CalDAV uses `/_/api/v1/caldav/tasks/` (private home/principal),
`/_/api/v1/caldav/tasks/default/` (fixed VTODO collection) and
`/_/api/v1/caldav/tasks/default/{name}.ics` (resource). These are not Wiki Paths
or VEVENT calendars. App credential management lives below
`/_/api/v1/extension/organizer.tasks/dav-credentials`.
See [scope and interoperability contract](ja/task-caldav.md).
1. `/...` is the canonical, language-neutral Viewer URL.
2. Editing and projection prefixes must not become Page identity.
3. `/e/foo` is legacy input and redirects to `/e/-/foo`.
4. UUID routes must remain valid after path rename or removal.
5. Revision routes address immutable Revision UUIDs.
6. Explicit language projection, when implemented, uses a non-canonical
namespace and must emit the semantic Viewer URL as canonical.
7. Binary media embedded by Viewer uses the `/v/raw/` projection. It accepts
an explicit internal address and must not invent a parallel `/raw/...`
semantic namespace.
8. `/u/` and `/g/` are reserved profile/Wiki namespaces before the semantic
catch-all. Their immediate `/_/` child is control space, not semantic Page
identity.
9. `/_/obj/sha256:<hash>` is reachable only when that Document is referenced
by a readable Path in the current Domain. The hash alone grants no access.
10. Raw and immutable Document responses expose Object, Revision, and Document
identities in `X-PagesWiki-Object-UUID`, `X-PagesWiki-Revision-UUID`, and
`X-PagesWiki-Document-SHA256`; clients must not infer one identity from
another or treat these descriptive headers as authorization.
## Internal address schemes
| Scheme | Identity |
| --- | --- |
| `path:` | Mutable semantic reachability |
| `uuid:` | Stable Page/Object identity |
| `rev:` | Immutable Revision identity |
| `sha256:` | Immutable Document content identity |
| `asset:` | Mutable authoring workspace |
The HTTP `/r/` namespace and internal `rev:` scheme are related but not
interchangeable strings.