Wallet Attached Storage v0.3

Initial use cases that are motivating this work:

• Sharing of W3C Verifiable Credentials from mobile credential wallets, as well as document sharing in general
• Serving as standardized storage (and a point of sync and interop) for multiple Verifiable Credential wallets.
• Enabling data portability and service provider interoperability for user-controlled social networking
• Enabling the "bring your own storage" architecture pattern of web app development
• Providing data storage and authorization frameworks for Agentic AI

This specification represents a layered and modular approach to storage, combining core features and optional extension points.

The layers below describe conformance tiers. Each tier adds optional capability on top of the one before it, so an implementer can stop at any tier and still be conformant. The normative body, by contrast, is organized container-first (outermost to innermost: Spaces Repositories, Spaces, Collections, then Resources), which is convenient as a reference but is the reverse of the tiers. If you're new to the spec, scan the profile table below for the conformance tiers, then walk through 2.5 Quickstart: Your First Request to watch a request succeed. The core tier is just 11. Resources and Blobs plus 5.1 WAS Authorization Profile v0.1.

Each tier stacks on the one above it. The Minimal profile is a permissioned key/value CRUD API built from simple HTTP verbs and delegatable capability-based authorization -- enough, on its own, to read and write any resource (text, structured document, or binary blob) without collection or space management.Listing, Collection and Space management will feel familiar to anyone who has used a GUI front end for a database or file system. Multi-tenant support lets a provider host many Spaces on one server. The Extensions tier layers on optional features -- an access-policy resource, user-writable metadata (for example, "tags" on binary files), a Space export endpoint, pluggable 14. Backends, query, quotas, client-side encryption (via Encrypted Data Vaults), replication, and versioning -- discovered through the linkset feature-detection mechanism (from [RFC9264]; see 13. Linksets).

Normative status. Section back-placement does not imply informative status. Everything from 2. Introduction through 15. Quotas is normative, as are the appendices A. Pagination, B. Reserved Path Segment Registry, C. Encryption Scheme Registry, and F. Error Type Registry (each of which also carries an inline "This appendix is normative." banner). The remaining appendices -- G. Goals and Requirements and H. IANA Considerations -- are informative. Optionality is orthogonal to normativity: many normative sections describe OPTIONAL endpoint groups, but a server that implements them MUST follow the stated requirements.

Step 1: Write. PUT a JSON document to a resource path under a collection. A 204 No Content confirms the write:

PUT /space/81246131-69a4-45ab-9bff-9c946b59cf2e/messages/hello-world HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: ...

{"message":"hi"}

HTTP/1.1 204 No Content

Step 2: Read. GET the same path to retrieve what you just stored:

GET /space/81246131-69a4-45ab-9bff-9c946b59cf2e/messages/hello-world HTTP/1.1
Host: example.com
Accept: application/json
Authorization: ...

HTTP/1.1 200 OK
Content-type: application/json

{"message":"hi"}

(The Authorization: ... placeholder stands for a signed zCap invocation). WAS reads are authorized too, so the header is required on the GET just as on the PUT. How that invocation is constructed is defined in 5.1.3 Performing Authorized API Calls, and its fully expanded form -- with the Digest, Capability-Invocation, and Signature headers spelled out -- is shown once in the worked example within that section. Producing that signature requires a conformant WAS client: it is an Ed25519 did:key capability invocation, not something you can hand-write with curl.

To go beyond a single pre-existing Space -- to create your own Space, or delegate access to others -- see the conformance-profile table in 2.4 Scope and Conformance Profiles and the full endpoint map in 2.6 API Summary.

API summary at a glance.

Unless otherwise specified by the controller, all operations require authorization. This can be overridden by the controller via the (optional) /policy endpoints. Hosting "public-read" resources, such as HTML files for websites, or media files you can link to via <img src="">, is a common use case.

The endpoints below divide into a Core profile that every conformant server implements, and Optional extensions grouped by feature. Each row links to the section that defines its operation. Rows marked Reserved name a path this specification anchors (see B. Reserved Path Segment Registry) but does not yet define an operation for; a server MUST NOT repurpose a reserved path.

Space, Collection, and Resource identifiers used in this specification are required to have the following properties.

1. URL-safety - All characters in a given identifier MUST be URL-safe.
2. Uniqueness - All identifiers MUST be unique within a given container. That is: Space ids (denoted by {space_id} in URL templates) MUST be unique within a given server, Collection ids (denoted by {collection_id} in URL templates) MUST be unique within a given Space, and Resource ids (denoted by {resource_id} in URL templates) MUST be unique within a given Collection.

Identifier length limits are currently left to the implementer. However, implementations SHOULD limit identifier length to their appropriate use case.

Identifier format constraints are currently left to the implementer. Common identifier formats include:

• Random IDs (either UUIDv4 with hyphens or using a compact encoding). Not recommended for extremely high throughput use cases, since the clients or servers that are generating them might be limited by available device entropy.
• Semi-random Time-sortable IDs (UUIDv7). Useful for cases involving logs, histories, feeds, and other situations where sorting by time is desirable.
• Content-based IDs (CIDs). Useful for data deduplication use cases.
• Human-readable IDs. Some use cases might require human-readable identifiers (for example, a user hosting a blog in their space might want meaningful collection and resource IDs such as /posts/2020-01-01-hello-world).

Like many authorization specifications, the WAS Authorization Profile tries to address opposing tensions. On the one hand, to cover the full range of use cases, it needs to be delegatable, revocable, secure, flexible, and thus capability-based. On the other hand, for ease of implementation and adoption, and for maximum developer usability, the profile must make the most common operations as simple and friction-free as possible.

To that end, the profile offers the following layered mechanisms.

1. Root Access: For basic admin CRUD operations, use the space's controller DID directly to sign API calls with HTTP Signatures.
2. Public Read: For the common "public read" use case (the typical web publishing workflow, where a site or a file is shared for anyone to access via an HTTP GET), use the simple { "type": "PublicCanRead" } WAS Authorization syntax, see below.
3. Advanced Delegatable Capabilities ("anyone with the link..." style): Use zCaps Authorization Capabilities v0.3
4. Policy Based Access Control (including the familiar "share with this list of people or groups" style): Use the space's linkset property to point to a linkset that includes a URL to an access control policy document.

PUT /space/81246131-69a4-45ab-9bff-9c946b59cf2e/photos/sunset.png HTTP/1.1
Host: example.com
Content-Type: image/png
Digest: mh=uEiCPO-qYr-z0GYV5F75-N1l8Rhjv4xIkKZsnbTZeZ7emSA
Capability-Invocation: zcap id="urn:zcap:root:https%3A%2F%2Fexample.com%2Fspace%2F81246131-69a4-45ab-9bff-9c946b59cf2e%2Fphotos%2Fsunset.png",action="PUT"
Authorization: Signature keyId="did:key:z6MkpBMbMaRSv5nsgifRAwEKvHHoiKDMhiAHShTFNmkJNdVW#z6MkpBMbMaRSv5nsgifRAwEKvHHoiKDMhiAHShTFNmkJNdVW",
  headers="(key-id) (created) (expires) (request-target) host capability-invocation content-type digest",
  signature="6GoRQ+rW69wBhNyERkafAXEZXZArezHvGRNUWC0HNI4Ss1xAiiMHdayS5aA2R6hLuYRNw6h9J9eCmQVMuHE1Bw==",
  created="1758150502",expires="1758151102"

...binary PNG bytes...

{
  "@context": "https://w3id.org/zcap/v1",
  "id": "urn:zcap:root:https%3A%2F%2Fexample.com%2Fspace%2F81246131-69a4-45ab-9bff-9c946b59cf2e%2Fmessages%2Fhello-world",
  "invocationTarget": "https://example.com/space/81246131-69a4-45ab-9bff-9c946b59cf2e/messages/hello-world",
  "controller": "did:key:z6MkpBMbMaRSv5nsgifRAwEKvHHoiKDMhiAHShTFNmkJNdVW"
}

{
  "@context": "https://w3id.org/zcap/v1",
  "id": "urn:uuid:6c9f3a1e-2b4d-4f8a-9c1e-7d2b3a4c5e6f",
  "parentCapability": "urn:zcap:root:https%3A%2F%2Fexample.com%2Fspace%2F81246131-69a4-45ab-9bff-9c946b59cf2e%2Fmessages%2F",
  "invocationTarget": "https://example.com/space/81246131-69a4-45ab-9bff-9c946b59cf2e/messages/",
  "controller": "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK",
  "allowedAction": ["GET"],
  "expires": "2026-12-31T23:59:59Z",
  "proof": { "...": "delegation proof signed by the parent capability's controller" }
}

GET /space/81246131-69a4-45ab-9bff-9c946b59cf2e/linkset HTTP/1.1
Host: example.com
Accept: application/linkset+json
Authorization: ...

HTTP/1.1 200 OK
Content-type: application/linkset+json

{
  "linkset": [
    {
      "anchor": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e",
      "https://wallet.storage/spec#policy": [
        {
          "href": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/policy",
          "type": "application/json"
        }
      ]
    }
  ]
}

GET /space/81246131-69a4-45ab-9bff-9c946b59cf2e/policy HTTP/1.1
Host: example.com
Authorization: ...

HTTP/1.1 200 OK
Content-type: application/json

{ "type": "PublicCanRead" }

{ "type": "PublicCanRead" }

WAS relies on ordinary [RFC9111] HTTP caching and defines no caching layer of its own. On the read side, a Resource's strong ETag validator (see 7.2 Conditional Requests) drives standard validation: a GET carrying If-None-Match: "<etag>" yields 304 Not Modified when the Resource is unchanged. Servers SHOULD emit ETag (and MAY emit Last-Modified) on GET/HEAD responses, and SHOULD mark responses to non-idempotent operations as non-cacheable (for example, Cache-Control: no-store).

Servers and backends MAY support [RFC9110] conditional requests to provide optimistic concurrency control on writes. This mechanism helps prevent the "lost update" problem, where two clients that both read version N of a Resource each write version N+1 and the second silently clobbers the first. A backend that supports this advertises the conditional-writes feature in its Backend description (see 14.1 Backend Data Model); a client SHOULD use these preconditions only against a backend that advertises support.

When supported, a Resource carries a strong ETag validator that changes whenever its stored content changes. Servers SHOULD return the ETag on GET/HEAD responses. The validator is opaque to clients: how a backend derives it is a server-side concern (see 14.1 Backend Data Model).

A state-changing request (PUT or DELETE) MAY carry a precondition:

• If-Match: "<etag>" -- perform the write only if the Resource's current ETag matches it (an "update-if-unchanged"). If it does not match, the server MUST NOT perform the write and MUST respond with precondition-failed (412).
• If-None-Match: * -- perform the write only if the Resource does not yet exist (a "create-if-absent"). If it already exists, the server MUST NOT perform the write and MUST respond with precondition-failed (412).

A server that supports conditional writes MUST evaluate the precondition atomically with the write, so that two concurrent writers cannot both observe the same prior version and both succeed; how a backend achieves this atomicity is a server-side concern (see 14.1 Backend Data Model). A client recovers from a 412 by re-reading the current Resource, re-applying its change on top of the new version, and retrying.

As with id-conflict, a server MUST verify the caller's authorization before evaluating a precondition, so a 412 is only ever observed by a caller already authorized to write the target; an under-authorized caller receives the merged not-found (404) instead, per the maximum-privacy rule in 6. Error Handling.

The mechanism extends to the Collection Description itself, whose update operation replaces the whole description -- so two concurrent recipient changes to a key-epoch roster (see C.4 Key Epochs) would otherwise silently clobber one another:

• The Get Collection Description response includes an ETag header -- a strong validator over the description's monotonic version (the same quoted form Resources use).
• The Update Collection request MAY carry If-Match. A server advertising the key-epochs feature MUST evaluate it atomically with the write and reject a stale validator with a precondition-failed error (412). The Update and Create responses carry the new ETag.
• If-Match is opt-in: an unconditional PUT remains valid (and remains last-writer-wins). Recipient-management clients MUST use If-Match.

The Collection Metadata object carries a validator of its own on the same pattern, mutually independent of both the Collection Description's and every Resource's: its metaVersion changes only on Collection metadata writes, never on a Collection Description update or a Resource write (and vice versa). Like the Collection Description validator, it is not gated on the conditional-writes backend feature: a server implementing the Collection metadata endpoints MUST maintain it and MUST support If-Match and If-None-Match: * on the 10.9 Update Collection Metadata Operation, evaluated atomically with the write. A Metadata object that has never been written has no validator, and If-None-Match: * succeeds exactly then.

A 412 arises only from an explicit If-Match / If-None-Match precondition header. It is deliberately distinct from the header-less 409 conflict kinds -- id-conflict (a POST create whose chosen id is already taken) and reserved-id -- which describe a conflict with current state where the client stated no precondition. Conditional requests are the versioned, header-driven concurrency mechanism; the 409 kinds are not.

The list operations -- 8.2 List Spaces Operation, 9.5 List All Collections operation, and 10.5 List Collection operation -- MAY paginate their responses, returning one page of items at a time using the cursor-based profile defined in Appendix A. Pagination. Pagination is OPTIONAL: a server that returns every item in a single response is conformant, and a client MUST be prepared for either behavior.

To create a Space:

• Perform an authorized Create Space operation that includes a Proof of (cryptographic material) Possession via a mechanism such as HTTP Signatures.

• If no id is provided, it will be generated by the storage server.

• A controller DID MUST be provided in the request body, and the request MUST be authorized by that DID.

  • If no controller is provided, the server MUST return an HTTP 400 error response
  • The capability invocation MUST be authorized by the body's controller: either signed directly by the controller DID (the common case), or signed by another DID presenting a valid, unexpired delegation chain rooted in the controller (see 5.1.5.2 Delegation). This is how the root of trust is initially set up (see 5.1.2 Space controller and the Root of Trust for more details).
  • The delegated form supports creating a Space on behalf of its eventual controller: for example, a provisioning service that handles payment or onboarding can be delegated a POST capability for /spaces/ by the user, and create a Space that the user's DID controls from the start. What is never acceptable is installing a controller that has authorized nothing at all: that would let anyone bind arbitrary DIDs to Spaces without their consent -- squatting meaningful ids "in their name", or burning per-controller onboarding allowances such as "one free Space per controller".

• (Optional, out of scope) A given storage provider MAY impose additional requirements to create a Space for a given controller, such as:

  • a Verifiable Credential representing a pre-arranged onboarding coupon
  • a proof of payment
  • a proof of membership in an organization

POST /spaces/ HTTP/1.1
Host: example.com
Accept: application/json
Content-type: application/json
Authorization: ...

{
  "type": ["Space"],
  "name": "Example space #1",
  "controller": "did:key:z6MkpBMbMaRSv5nsgifRAwEKvHHoiKDMhiAHShTFNmkJNdVW"
}

HTTP/1.1 201 Created
Content-type: application/json
Location: https://example.com/space/81246131-69a4-45ab-9bff-9c946b59cf2e

{
  "id": "81246131-69a4-45ab-9bff-9c946b59cf2e",
  "type": ["Space"],
  "name": "Example space #1",
  "controller": "did:key:z6MkpBMbMaRSv5nsgifRAwEKvHHoiKDMhiAHShTFNmkJNdVW"
}

• Requires appropriate authorization (root zcap invoked by the controller of one or more spaces, or a zcap granting permission to read a one or more spaces)

• Lists only the spaces the requester is authorized to see

• MAY be paginated (see A. Pagination)

GET /spaces/ HTTP/1.1
Host: example.com
Accept: application/json
Authorization: ...

HTTP/1.1 200 OK
Content-type: application/json

{
  "url": "/spaces/",
  "totalItems": 1,
  "items": [
    {
      "id": "81246131-69a4-45ab-9bff-9c946b59cf2e",
      "url": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e"
    }
  ]
}

HTTP/1.1 200 OK
Content-type: application/json

{
  "url": "/spaces/",
  "totalItems": 0,
  "items": []
}

Space properties:

• id - A unique identifier for a space at a given server. Created by the server if not provided. Note: the {space_id} template parameter used in URL templates in this spec MUST match that space's id property. See 4. Identifiers for additional constraints.
• type - An array of strings, MUST include the type Space. The array SHOULD be lexically sorted so that the object has a canonical, stable serialization (useful for hashing or signing).
• name (optional) - An arbitrary human-readable name for the space. Does not have to be unique.
• controller - A cryptographic identifier (a did) of the entity that is authorized to perform operations on the space (or to delegate authorization to other entities)

Space properties automatically added by the server:

• createdBy (optional) - The did of the party whose capability invocation created the space. It is recorded on the first write and preserved unchanged by later writes, so it names the creator rather than the last writer. It is read-only: a server MUST ignore a createdBy supplied in a request body. createdBy is distinct from controller -- under delegated provisioning (see 5.1.2 Space controller and the Root of Trust) the party that creates a space need not be the party that controls it. Recording it is OPTIONAL, so a client MUST treat an absent createdBy as "not recorded" rather than as an assertion that the space has no creator.
• url - A relative URL to the space's description resource. Added by the server, used in the Space Description object as well as the 8.2 List Spaces Operation result.
• linkset - A relative URL to a resource which contains a set of links to auxiliary resources (such as to access control policy documents). See section 13.1 Space Linkset. Note that this is one of the B.1 Space-level reserved endpoints.

• Requires appropriate authorization (root zcap invoked by the space's controller, or a zcap granting permission to read a particular space)
• Returns the details for the specified space id
• Only includes the resources the requester is authorized to see

The format of the response is determined based on content negotiation; application/json is the REQUIRED baseline (see 11.3 Content Types and Representations).

GET /space/81246131-69a4-45ab-9bff-9c946b59cf2e HTTP/1.1
Host: example.com
Accept: application/json
Authorization: ...

HTTP/1.1 200 OK
Content-type: application/json

{
  "id": "81246131-69a4-45ab-9bff-9c946b59cf2e",
  "url": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e",
  "type": ["Space"],
  "name": "Example space #1",
  "controller": "did:key:z6MkpBMbMaRSv5nsgifRAwEKvHHoiKDMhiAHShTFNmkJNdVW",
  "createdBy": "did:key:z6MkpBMbMaRSv5nsgifRAwEKvHHoiKDMhiAHShTFNmkJNdVW",
  "linkset": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/linkset"
}

When creating or modifying a Space via PUT, the client specifies the id of the Space.

• Requires appropriate authorization (root zcap invoked by the space's controller, or a zcap granting permission to write to a particular space)
• Allows the client to update the following fields:
  • name
  • controller

The controller property in the request body is the proposed value, not the root of trust for the request. When the Space already exists, the capability invocation MUST be verified against the Space's currently stored controller: only the current controller (or its delegate) may update the Space, including transferring it by writing a new controller. The body's controller participates in verification only when the PUT creates the Space -- there is no stored controller yet, so, as with 8.1 Create Space operation, the invocation MUST be authorized by the body's controller: signed by it directly, or presented with a valid, unexpired delegation chain rooted in it (violations are controller-mismatch, as for POST). A server that verifies an update against the body's controller reopens the takeover described under 8.1.2 Create Space Errors: any caller could seize an existing Space by PUTting its id with themselves as the controller.

A server that records createdBy (see 9.1 Space Data Model) sets it only on the PUT that creates the Space, to the did of the party that invoked the capability -- which is not necessarily the body's controller. On a PUT that updates an existing Space, the stored createdBy is preserved, so transferring the Space by writing a new controller does not rewrite its creator.

PUT /space/81246131-69a4-45ab-9bff-9c946b59cf2e HTTP/1.1
Host: example.com
Accept: application/json
Content-type: application/json
Authorization: ...

{
  "id": "81246131-69a4-45ab-9bff-9c946b59cf2e",
  "type": ["Space"],
  "name": "Example space #1",
  "controller": "did:key:z6MkpBMbMaRSv5nsgifRAwEKvHHoiKDMhiAHShTFNmkJNdVW"
}

HTTP/1.1 201 Created
Content-type: application/json
Location: https://example.com/space/81246131-69a4-45ab-9bff-9c946b59cf2e

PUT /space/81246131-69a4-45ab-9bff-9c946b59cf2e HTTP/1.1
Host: example.com
Content-type: application/json
Accept: application/json
Authorization: ...

{
  "id": "81246131-69a4-45ab-9bff-9c946b59cf2e",
  "type": ["Space"],
  "name": "Newly renamed space #1",
  "controller": "did:key:z6MkpBMbMaRSv5nsgifRAwEKvHHoiKDMhiAHShTFNmkJNdVW"
}

HTTP/1.1 204 No Content

• Requires appropriate authorization (root zcap invoked by the space's controller, or a zcap granting permission to write to a particular space)
• Deletes the space and all the data (collections and resources) contained in it
• This operation is idempotent

DELETE /space/81246131-69a4-45ab-9bff-9c946b59cf2e HTTP/1.1
Host: example.com
Accept: application/json
Authorization: ...

HTTP/1.1 204 No Content

• Returns the list of all Collections in a Space (that the requester has permission to access)
• Requires appropriate authorization
  • For example, when using zCaps for authorization, the request must be signed by the space's controller, or invoke a delegated capability that allows the GET action
• Since Collection's name property is optional, default it to be the same value as id when name is missing. (The name is intended to drive UIs, so defaulting to id simplifies consuming client logic.)
• Each listed item carries the Collection's id, url, and name. A server MAY additionally surface a public member on each item: a boolean indicating whether a PublicCanRead access control policy (see 5.1.7 Access Control Policies) is attached to that Collection. It is surfaced inline so that a listing consumer need not issue one policy probe per item to learn whether the Collection is publicly readable. A server that surfaces public MUST include it on every item in the listing, expressing false explicitly rather than omitting it, so that a client can distinguish "not public" from "the server does not surface the flag". Consistent with the fail-closed rule of the policy evaluation contract, a policy whose type the server does not recognize MUST be reported as "public": false. When public is absent from a listing, a client falls back to probing each Collection's policy (see 5.1.7 Access Control Policies).
• MAY be paginated (see A. Pagination)

GET /space/81246131-69a4-45ab-9bff-9c946b59cf2e/collections/ HTTP/1.1
Host: example.com
Accept: application/json
Authorization: ...

HTTP/1.1 200 OK
Content-type: application/json

{
  "url": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/collections/",
  "totalItems": 2,
  "items": [
    {
      "id": "example",
      "url": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/example",
      "name": "Example Collection",
      "public": false
    },
    {
      "id": "73WakrfVbNJBaAmhQtEeDv",
      "url": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/73WakrfVbNJBaAmhQtEeDv",
      "name": "73WakrfVbNJBaAmhQtEeDv",
      "public": true
    }
  ]
}

Collection properties (user-writable):

• id - A unique collection identifier (within a given space). Created by the server if not provided. Note: the {collection_id} template parameter used in URL templates in this spec MUST match that collection's id property. See 4. Identifiers for additional constraints.
• type - An array of strings, MUST include the type Collection. As with a Space's type, the array SHOULD be lexically sorted for a canonical, stable serialization.
• name (optional) - An arbitrary human-readable name for the collection. Does not have to be unique.
• generator (optional) - The did of the application this collection was provisioned for, named for the ActivityStreams 2.0 generator term (the application that generated an object). It is the client-asserted identity axis of 11.8.1 Writer attribution: writerId and createdBy: client-supplied, persisted, and writable by the Space controller on create and on update -- updatable so that a controller can backfill the property onto collections that predate it -- in contrast to the server-observed, read-only createdBy. The contrast is the reason the property exists: under delegated provisioning the party whose capability invocation creates the collection is the user's agent (a wallet), so createdBy records the user's did, never the application's, and only the controller is in a position to name the application it provisioned the collection for. generator is an assertion by the controller, not a server-verified fact: a server MUST NOT verify, compute, or default it, and MUST NOT use it as an input to authorization. A server MAY separately record that the generator did has been observed invoking a delegated capability on the collection -- corroboration on the same evidentiary footing as createdBy (server-observed use, not verified identity). Either way, any reader other than the controller (a delegated consumer of a shared collection, a reader of a world-readable one) MUST treat generator as exactly a controller assertion. A present but empty or non-did-shaped value is an invalid-request-body error.
• generatorOrigin (optional) - The Web origin (its ASCII serialization, e.g. https://app.example.com) the generator did was bound to when the collection was provisioned. A provisioning exchange in which the user's agent authenticates the requesting application by origin (for example a browser-attested credential-handler exchange) establishes an origin binding the storage server is never a party to; stamping the origin beside generator preserves that fact and gives a reader a human-readable attribution label without further lookups. Same footing as generator in every other respect: controller-asserted, writable by the Space controller on create and update, never verified or defaulted by the server. A present value that is not the ASCII serialization of a Web origin (a URL carrying a path, query, or fragment; the empty string) is an invalid-request-body error. generatorOrigin SHOULD NOT be present without generator.
• backend (optional) - An object describing the storage backend selected for this collection. If not specified, defaults to the value { "id": "default" }. The backend object's id property MUST be from the list of 14.2 Space Backends Available for the given space. If an unavailable (unsupported) backend is specified, the server MUST throw an error. See section 14. Backends for more details.
• encryption (optional) - A non-secret descriptor declaring that this collection's Resources are client-side encrypted, and naming the scheme. The value is an object with a required string scheme and an optional positive-integer version (e.g. { "scheme": "edv", "version": 1 } for the EDV-over-WAS scheme); an absent version means 1, and an absent descriptor means the collection is a plaintext collection -- its Resources are stored as the client sent them, with no client-side encryption envelope. The version names the version of the scheme's wire format as registered in the C. Encryption Scheme Registry, so a scheme's envelope profile can evolve without ambiguity about which shape a given collection stores; it is an opaque registry key with a total order, not a semantic version. The server MUST NOT interpret the descriptor beyond validating its shape -- it never holds key material and stores the descriptor opaquely. Its purpose is discovery: any authorized reader (including a delegated consumer that did not create the collection) learns from the Collection Description that the collection is encrypted, and decrypts with its own keys. The descriptor is set-once, version-monotonic: a server MUST allow declaring it on a collection that lacks one (e.g. migrating a pre-existing collection), and MUST accept a re-declaration of the standing values (including an explicit "version": 1 on a descriptor that had omitted it) as an idempotent no-op, but MUST reject (with an encryption-immutable error) any attempt to change the scheme, decrease or remove the version, or clear the descriptor, on an existing collection, since that would corrupt the already-stored encrypted Resources. On a collection whose stored descriptor carries an explicit "version": 1, an update whose descriptor omits version counts as an attempt to remove it and is rejected under this rule, though because an absent version means 1, a server MAY instead accept such an update as an idempotent re-declaration of the standing value. Under either reading, the standing version survives unchanged. Raising the version is permitted (subject to the recognition rule in C. Encryption Scheme Registry): subsequent writes are validated against the new profile, while already-stored Resources are unaffected. See section 14. Backends (client-side encryption note) for the rationale. A server that recognizes the declared scheme and version enforces them structurally on write -- rejecting any non-envelope body so plaintext can never be stored in an encrypted Collection; see C. Encryption Scheme Registry. On the edv scheme, the descriptor MAY additionally carry the key-epoch public references, currentEpoch and epochs (see C.4 Key Epochs), which let several readers hold per-reader keys and let reader removal rotate the collection key. These fields contain only public keys and wrapped-key ciphertext; as with the rest of the descriptor, the server stores them opaquely and validates only their shape and a small set of integrity rails. Client-side profiles built on epochs (such as [WAS-EC]) require these members from the descriptor's creation onward; the server-side optionality here exists because key management is out of this specification's scope, and is not a license for such a profile's clients to operate an epoch-less descriptor.

Collection properties automatically added by the server:

• createdBy (optional) - The did of the party whose capability invocation created the collection, on the same terms as a Space's createdBy (see 9.1 Space Data Model): recorded on the first write, preserved by later writes, read-only, and OPTIONAL.
• url - A relative URL to the collection's description resource. Added by the server, used in the Collection Description object as well as the List Collections operations result.
• linkset - A relative URL to a resource which contains a set of links to auxiliary resources (such as to access control policy documents). See section 13.2 Collection Linkset. Note that this is one of the B.2 Collection-level reserved endpoints.

Each Collection also has an associated Metadata object, distinct from this Collection Description -- server-managed properties (optional timestamps and createdBy) plus user-writable ones (name and tags, nested under custom) -- addressable at the reserved meta path segment under the Collection URL. See 10.7 Collection Metadata Data Model.

Example collection (JSON representation):

{
  "id": "73WakrfVbNJBaAmhQtEeDv",
  "url": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/73WakrfVbNJBaAmhQtEeDv",
  "type": ["Collection"],
  "name": "Verifiable Credentials Collection",
  "createdBy": "did:key:z6MkpBMbMaRSv5nsgifRAwEKvHHoiKDMhiAHShTFNmkJNdVW",
  "generator": "did:key:z6MkfriqYRX3JBqzsbVbKuBUxDR2nsjLTu6AbrxJZAmFmXWb",
  "generatorOrigin": "https://app.example.com",
  "linkset": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/73WakrfVbNJBaAmhQtEeDv/linkset"
}

When a Collection is created via a POST, the client can specify the id of the Collection. If the id is not specified, one is auto-generated by the server and returned as part of the Location response header.

POST /space/81246131-69a4-45ab-9bff-9c946b59cf2e/collections/ HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: ...

{
  "name": "Verifiable Credentials Collection",
  "type": ["Collection"]
}

HTTP/1.1 201 Created
Content-type: application/json
Location: https://example.com/space/81246131-69a4-45ab-9bff-9c946b59cf2e/21f81693-f4a3-4caa-b81c-b663d6e1e3ae

POST /space/81246131-69a4-45ab-9bff-9c946b59cf2e/collections/ HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: ...

{
  "id": "credentials",
  "name": "Verifiable Credentials Collection",
  "type": ["Collection"],
  "backend": { "id": "default" }
}

HTTP/1.1 201 Created
Content-type: application/json
Location: https://example.com/space/81246131-69a4-45ab-9bff-9c946b59cf2e/credentials

When creating or modifying a Collection via PUT, the client specifies the id of the Collection. This Collection id MUST NOT collide with the list of B.1 Space-level reserved endpoints.

PUT /space/81246131-69a4-45ab-9bff-9c946b59cf2e/73WakrfVbNJBaAmhQtEeDv HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: ...

{
  "id": "73WakrfVbNJBaAmhQtEeDv",
  "name": "Verifiable Credentials Collection",
  "type": ["Collection"],
  "backend": { "id": "default" }
}

HTTP/1.1 201 Created

• Returns the Collection description object
• Requires appropriate authorization
  • For example, when using zCaps for authorization, the request must be signed by the space's controller, or invoke a delegated capability that allows the GET action
• On a backend advertising the key-epochs feature, the response includes an ETag header over the description's version, for use with If-Match on a subsequent update (see 7.2 Conditional Requests)

GET /space/81246131-69a4-45ab-9bff-9c946b59cf2e/73WakrfVbNJBaAmhQtEeDv HTTP/1.1
Host: example.com
Accept: application/json
Authorization: ...

HTTP/1.1 200 OK
Content-type: application/json

{
  "id": "73WakrfVbNJBaAmhQtEeDv",
  "url": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/73WakrfVbNJBaAmhQtEeDv",
  "name": "Verifiable Credentials Collection",
  "type": ["Collection"],
  "linkset": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/73WakrfVbNJBaAmhQtEeDv/linkset",
  "backend": { "id": "default" }
}

• Returns the list of Collection resources
• Requires appropriate authorization
  • For example, when using zCaps for authorization, the request must be signed by the space's controller, or invoke a delegated capability that allows the GET action
• MAY be paginated (see A. Pagination); the example below shows a single unpaginated page, and the paginated example that follows shows the next link and cursor continuation.

GET /space/81246131-69a4-45ab-9bff-9c946b59cf2e/73WakrfVbNJBaAmhQtEeDv/ HTTP/1.1
Host: example.com
Accept: application/json
Authorization: ...

HTTP/1.1 200 OK
Content-type: application/json

{
  "id": "73WakrfVbNJBaAmhQtEeDv",
  "url": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/73WakrfVbNJBaAmhQtEeDv",
  "name": "Example JSON Documents Collection",
  "type": ["Collection"],
  "totalItems": 2,
  "items": [
    {
      "id": "321efd4e-23cb-497c-aaee-7bd26e66d39e",
      "url": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/73WakrfVbNJBaAmhQtEeDv/321efd4e-23cb-497c-aaee-7bd26e66d39e",
      "contentType": "application/json"
    },
    {
      "id": "3943c87f-b617-44bc-ba75-8de2b16c3640",
      "url": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/73WakrfVbNJBaAmhQtEeDv/3943c87f-b617-44bc-ba75-8de2b16c3640",
      "contentType": "application/json"
    }
  ]
}

GET /space/81246131-69a4-45ab-9bff-9c946b59cf2e/73WakrfVbNJBaAmhQtEeDv/?limit=2 HTTP/1.1
Host: example.com
Accept: application/json
Authorization: ...

HTTP/1.1 200 OK
Content-type: application/json

{
  "id": "73WakrfVbNJBaAmhQtEeDv",
  "url": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/73WakrfVbNJBaAmhQtEeDv",
  "name": "Example JSON Documents Collection",
  "type": ["Collection"],
  "items": [
    {
      "id": "321efd4e-23cb-497c-aaee-7bd26e66d39e",
      "url": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/73WakrfVbNJBaAmhQtEeDv/321efd4e-23cb-497c-aaee-7bd26e66d39e",
      "contentType": "application/json"
    },
    {
      "id": "3943c87f-b617-44bc-ba75-8de2b16c3640",
      "url": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/73WakrfVbNJBaAmhQtEeDv/3943c87f-b617-44bc-ba75-8de2b16c3640",
      "contentType": "application/json"
    }
  ],
  "next": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/73WakrfVbNJBaAmhQtEeDv/?limit=2&cursor=eyJhZnRlciI6IjM5NDNjODdmLWI2MTctNDRiYy1iYTc1LThkZTJiMTZjMzY0MCJ9"
}

GET /space/81246131-69a4-45ab-9bff-9c946b59cf2e/73WakrfVbNJBaAmhQtEeDv/?limit=2&cursor=eyJhZnRlciI6IjM5NDNjODdmLWI2MTctNDRiYy1iYTc1LThkZTJiMTZjMzY0MCJ9 HTTP/1.1
Host: example.com
Accept: application/json
Authorization: ...

HTTP/1.1 200 OK
Content-type: application/json

{
  "id": "73WakrfVbNJBaAmhQtEeDv",
  "url": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/73WakrfVbNJBaAmhQtEeDv",
  "name": "Example JSON Documents Collection",
  "type": ["Collection"],
  "items": [
    {
      "id": "9c7b2e51-0d4a-4c2f-8b3e-1f6a5d8e7c90",
      "url": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/73WakrfVbNJBaAmhQtEeDv/9c7b2e51-0d4a-4c2f-8b3e-1f6a5d8e7c90",
      "contentType": "application/json"
    }
  ]
}

Each Collection has an associated Metadata object of its own, addressable at the reserved meta path segment under the Collection URL (one of the B.2 Collection-level reserved endpoints). Because that segment occupies the {resource_id} position, meta is a reserved Resource id: creating a Resource with the id meta is a reserved-id conflict (see B. Reserved Path Segment Registry). A GET or PUT at this path is therefore always the Collection metadata operation, never a Resource operation; the reserved-id rejection arises where a Resource id is supplied explicitly, as in a POST body's id. Methods this specification does not define at this path (DELETE in particular) are not Resource operations either: a server MAY answer them with 405 Method Not Allowed, or -- treating the request as a Resource operation on a reserved id -- with a reserved-id (409) error, but MUST NOT let them act on a stored Resource. The Collection metadata endpoints are OPTIONAL on the same terms as the Resource-level ones; a server that does not implement them SHOULD return an unsupported-operation (501) error for requests to these paths.

The object mirrors the 11.8 Resource Metadata Data Model: server-managed properties at the top level, user-writable properties nested under custom, and epoch as a writable sibling of custom. The differences follow from what a Collection is -- a container, not a document. There are no contentType and size properties, because those describe a stored representation and a Collection has none.

Server-managed properties (all OPTIONAL):

• createdAt (optional) - The [RFC3339] date-time at which the Metadata object was first written. It describes the Metadata object, not the Collection: a Collection may exist long before its metadata is first written, so createdAt here can postdate the Collection's creation by arbitrarily long.
• updatedAt (optional) - The [RFC3339] date-time at which the Metadata object was last modified.
• createdBy (optional) - The did of the party whose capability invocation created the Collection, on the same terms as the createdBy of the 10.1 Collection Data Model (it is the same value, surfaced here so a metadata read is self-contained). Unlike the timestamps, it describes the Collection rather than the Metadata object, and it is present (when recorded at all) from the Collection's creation onward.

User-writable properties:

• custom (optional) - A JSON object holding the user-writable properties, with the same shape as the Resource-level custom: an optional human-readable name and an optional tags object of string-valued annotations. A Metadata object with no user-writable properties set MAY omit custom or report it as {}. A Collection therefore has two name slots: the name of the 10.1 Collection Data Model is server-visible plaintext and is what listings report, while custom.name here is supplementary -- except on an encrypted Collection, where a client SHOULD leave the Description's plaintext name unpopulated (a listing that defaults a missing name to the id then reveals nothing; see 9.5 List All Collections operation) and custom.name, inside the encrypted envelope, is the only name the Collection has.
• epoch (optional) - The key-epoch id this Metadata object's custom envelope was encrypted under (see C.4 Key Epochs), declared by the writer as a top-level member of an Update Collection Metadata request and stored opaquely; the server never computes or verifies it. Its omission rule deliberately inverts the Resource-level one: an omitted epoch on a Collection metadata write clears the stored value (at Resource level it is preserved). The Resource-level epoch property describes the content write, which a metadata write does not touch, so preserving it is correct; here the only thing epoch can describe is the custom envelope itself, which every metadata write replaces wholesale, so a preserved value would misdescribe the new envelope. A client writing to an encrypted Collection therefore re-declares epoch on every metadata write.

There is no writerId member: Collection metadata is configuration maintained by the Space controller, not replicated per-revision content, so the attribution machinery of 11.8.1 Writer attribution: writerId and createdBy does not apply at this level.

On a Collection that declares an encryption descriptor (see C. Encryption Scheme Registry), custom is stored encrypted, exactly as at Resource level: its value is an envelope of the Collection's declared scheme, validated structurally on write (rejecting a plaintext custom with an encryption-scheme-mismatch) and never decrypted by the server, while the server-managed properties and epoch remain plaintext. This is what gives an encrypted Collection a client-encrypted display name and tags, and a discoverable, conditionally-writable home for profile-level configuration such as the [WAS-EC] blinded-index schema. One consequence: on an encrypted Collection every metadata write MUST carry a conforming envelope as its custom, so the plaintext clearing convention (a PUT with no custom; see 10.7.2 Lifecycle) is unavailable -- the cleared state is instead an envelope encrypting an empty object.

As at Resource level, a PUT to the Collection's /meta endpoint is a full replacement of the Metadata object's custom object: the stored custom object is replaced by the one in the request body, so any user-writable property omitted from it is cleared (and, on a plaintext collection, a request body with no custom property clears them all).

The only other writable top-level member is epoch, whose omission clears the stored stamp (see the 10.7 Collection Metadata Data Model for the rule and its rationale -- this is the inverse of the Resource-level behavior). There is no writerId member at this level.

Server-managed properties are not affected by this operation; a server MUST ignore any top-level properties other than custom and epoch present in the request body (so that a client may read the Metadata object, modify it, and PUT it back without first stripping the server-managed properties).

A PUT to a Collection's /meta does not create anything: a Metadata object cannot exist apart from its Collection, so a PUT to the /meta path of a nonexistent Collection returns a not-found (404) error.

PUT /space/81246131-69a4-45ab-9bff-9c946b59cf2e/73WakrfVbNJBaAmhQtEeDv/meta HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: ...

{
  "custom": {
    "name": "Verifiable Credentials Collection",
    "tags": { "project": "demo" }
  }
}

HTTP/1.1 204 No Content
ETag: "3"

A unit of data, in transit or at rest. (As described in the W3C FileAPI: Blob Interface).

Blob properties:

• byte stream
• size - length of the byte stream in bytes
  • Note: Although size can be derived from bytes, it's useful to be able to have it up front (for the receiving system to decide to reject an upload based on quota / exceeding max size, etc).
• type (from the IANA mime type registry) - If not specified, defaults to application/octet-stream

When a Blob is stored as a Resource, its type and size are reported as the contentType and size properties of the Resource's Metadata object (see 11.8 Resource Metadata Data Model), and the stored bytes are returned verbatim on reads (see 11.3 Content Types and Representations).

A resource is a named (addressable) Blob stored in a given collection, with metadata. The data model is derived from W3C FileAPI: File Interface, but with the addition of a few crucial properties.

In similar storage systems, a resource is called "File", "Object", "Document", "Row", "Graph", and so on.

Resource properties:

• id - A unique identifier for a resource for a given collection. Created by the server if not provided. Note: the {resource_id} template parameter used in URL templates in this spec MUST match that resource's id property (as returned by the 10.5 List Collection operation).
• name - (optional) - Human-readable name for the resource, useful for building user interfaces for browsing collection contents.
• type (optional) - An array of strings describing the resource. Unlike Space and Collection, no specific type value is required of a Resource.
• url (optional) - A relative URL (provided by the server when listing resources via the 10.5 List Collection operation)
• contentType (optional) - The MIME type of the default representation of the resource (provided by the server when listing resources via the 10.5 List Collection operation)
• Each Resource also has an associated Metadata object -- server-managed properties (contentType, size, optional timestamps) plus user-writable ones (name and tags, nested under custom) -- addressable at the reserved /meta path segment under the Resource URL. See 11.8 Resource Metadata Data Model.

A Resource has exactly one current representation: the stored bytes plus the content type they are stored under. Every successful write (POST or PUT) replaces that representation entirely -- including replacing a representation previously stored under a different content type. Servers are not required to store, convert between, or negotiate multiple representations of a Resource.

Writing. A Resource write request MUST carry a Content-Type header; a server MUST reject a write without one with a missing-content-type (400) error. The request body is interpreted according to its content type:

• JSON -- a content type of application/json, or any type with a +json structured-syntax suffix [RFC6839] (for example, application/ld+json), is stored as a JSON document.
• Raw binary (support REQUIRED) -- any other content type is stored as an opaque byte stream (see 11.1 Blob Data Model), verbatim, under the supplied content type. Clients with no more specific type SHOULD use application/octet-stream.
• Multipart upload (support OPTIONAL) -- a server MAY additionally accept multipart/form-data [RFC7578] uploads (the HTML form workflow). The request MUST contain exactly one file part; that part supplies the stored bytes, and its own content type (not multipart/form-data) becomes the stored content type. Because a write targets a single Resource, there is no batch form: a server MUST reject a multipart request with no file part, or with more than one, with an invalid-request-body (400) error.

Reading. A GET returns the current representation, verbatim, with the stored content type as the response Content-Type. Because Resources are single-representation, the request's Accept header is advisory: a server MAY ignore it, and MUST NOT reject a Resource read for lack of an acceptable representation (no 406 Not Acceptable) -- the stored representation is always the answer. A HEAD request returns the same headers without the body; the response Content-Type and Content-Length correspond to the contentType and size properties of the Resource's Metadata object (see 11.8 Resource Metadata Data Model).

Description objects. API documents generated by the server -- Space and Collection descriptions, listings, quota reports, Metadata objects -- MUST be available as application/json. Linkset documents use application/linkset+json [RFC9264], and error responses use application/problem+json [RFC9457] (see 6. Error Handling). Other representations of these documents (negotiated via Accept) MAY be offered in addition to, never instead of, the JSON baseline.

A read returns the Resource's single stored representation, with the stored content type; see 11.3 Content Types and Representations for content type and Accept header handling (including the HEAD variant).

GET /space/81246131-69a4-45ab-9bff-9c946b59cf2e/messages/hello-world HTTP/1.1
Host: example.com
Accept: application/json

HTTP/1.1 200 OK
Content-type: application/json

{"message":"hi"}

When creating or modifying a Resource via PUT, the client specifies the id of the Resource. This Resource id MUST NOT collide with the list of B.2 Collection-level reserved endpoints.

PUT /space/81246131-69a4-45ab-9bff-9c946b59cf2e/messages/hello-world HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: ...

{"message":"hi"}

HTTP/1.1 204 No Content

PUT /space/81246131-69a4-45ab-9bff-9c946b59cf2e/messages/hello-world HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: ...

{"message":"no I've changed my mind"}

HTTP/1.1 204 No Content

PUT /space/81246131-69a4-45ab-9bff-9c946b59cf2e/photos/sunset.png HTTP/1.1
Host: example.com
Content-Type: image/png
Digest: mh=uEiCPO-qYr-z0GYV5F75-N1l8Rhjv4xIkKZsnbTZeZ7emSA
Authorization: ...

...binary PNG bytes...

HTTP/1.1 204 No Content

Each Resource has an associated Metadata object, addressable at the reserved /meta path segment under the Resource URL (one of the B.3 Resource-level reserved endpoints). The metadata endpoints are OPTIONAL; a server that does not implement them SHOULD return an unsupported-operation (501) error for requests to /meta paths. (A Collection has a Metadata object of its own, at the reserved meta segment under the Collection URL; see 10.7 Collection Metadata Data Model.)

The Metadata object is a JSON document containing two groups of properties:

• Server-managed properties appear at the top level of the Metadata object. They are maintained by the server as a side effect of Resource write operations and are read-only: the 11.10 Update Resource Metadata Operation cannot change them.
• User-writable properties are nested under the custom property and are set by the client via the 11.10 Update Resource Metadata Operation. Keeping them in their own object makes the writable surface explicit and leaves the top level free for future server-managed properties.

Server-managed properties (contentType and size are REQUIRED in every Metadata object; the timestamps and createdBy are OPTIONAL):

• contentType - The MIME type of the stored representation of the Resource, recorded from the Content-Type header of the request that last wrote the Resource's content (application/octet-stream if none was provided). The same value is reported in 10.5 List Collection operation results and as the Content-Type header of GET/HEAD responses for the Resource itself.
• size - The length in bytes of the stored representation of the Resource (see the size property of the 11.1 Blob Data Model).
• createdAt (optional) - The [RFC3339] date-time at which the Resource was created.
• updatedAt (optional) - The [RFC3339] date-time at which the Resource's content or user-writable metadata was last modified.
• createdBy (optional) - The did of the party whose capability invocation created the Resource. It is recorded on the first write and preserved unchanged by later writes, so it names the creator rather than the last writer -- in a Collection written by several delegated agents, createdBy and the party responsible for the current content need not be the same. Like the other server-managed properties it is read-only: it cannot be set through the 11.10 Update Resource Metadata Operation. Recording it is OPTIONAL, so a client MUST treat an absent createdBy as "not recorded" rather than as an assertion that the Resource has no creator.

User-writable properties:

• custom (optional) - A JSON object holding the user-writable properties below. A Metadata object with no user-writable properties set MAY omit custom or report it as {}.
  • name (optional) - A human-readable name for the Resource. This is the same name property defined in the 11.2 Resource Data Model.
  • tags (optional) - A JSON object of application-defined annotations. Keys are strings chosen by the application; values SHOULD be strings, so that tags stay cheap to index and filter on. Applications that need richer structured metadata SHOULD store it as a Resource in its own right rather than in tags.
• epoch (optional) - The key-epoch id this Resource's content was encrypted under (see C.4 Key Epochs). Declared by the writer via the Key-Epoch header on a content write or a top-level epoch member on an Update Resource Metadata request, and stored opaquely. The server never computes or verifies it. epoch is a sibling field alongside custom, since on an encrypted Collection custom is the opaque envelope and is replaced wholesale by every metadata write. An omitted epoch on a metadata write preserves the stored value; a content write without the header clears it.
• writerId (optional) - An opaque label naming the writing agent that produced the Resource's current revision (see 11.8.1 Writer attribution: writerId and createdBy for its semantics, its deliberate separation from createdBy, and its privacy considerations). The writer declares it, via the Writer-Id header on a content write or a delete, or a top-level writerId member on an Update Resource Metadata request, and the server stores it verbatim. The value is not verified, and it MUST NOT be an input to any authorization decision. Like epoch, it is a sibling of custom rather than part of it. Unlike epoch, whose stamp describes the content write, writerId describes the latest revision whichever operation produced it: every write either declares the writer's own label or clears the stored one. A write that declares no writerId clears the stored value, since attribution to a bygone writer is worse than no attribution at all.

On a Collection that declares an encryption descriptor (see C. Encryption Scheme Registry), the user-writable custom object is stored encrypted: its value is an envelope of the Collection's declared scheme (the same envelope profile used for a Resource's content). The server-managed top-level properties (contentType, size, the timestamps, and createdBy) remain plaintext -- the server needs them for listings, GET/HEAD headers, quotas, and, in the case of createdBy, because it is the very identity the server authenticated on the creating write. The server validates the custom envelope structurally on write (rejecting a plaintext custom with an encryption-scheme-mismatch) and never decrypts it; a client holding the keys decrypts custom back to { name, tags, ... } after reading. Because the server cannot read an encrypted name, 10.5 List Collection operation summaries for an encrypted Collection carry no name.

A Resource's Metadata object is created and deleted together with the Resource itself: it comes into existence (with only server-managed properties) when the Resource is created and is removed when the Resource is deleted. There is no DELETE /meta operation; to clear the user-writable properties, send a PUT with an empty custom object ({ "custom": {} }) or an empty body object ({}).

A PUT to the /meta endpoint is a full replacement of the Metadata object's custom object: the stored custom object is replaced by the one in the request body, so any user-writable property omitted from it is cleared (and a request body with no custom property clears them all).

Two other top-level members are also writable, each with its own omission behavior. A request MAY carry epoch to set the Resource's key-epoch stamp; a request that omits it preserves the stored stamp, because the stamp describes the content write, not the metadata write (see C.4 Key Epochs). A request MAY carry writerId to declare the writing agent's attribution label; a request that omits it clears the stored label (see 11.8.1 Writer attribution: writerId and createdBy). The label is cleared rather than preserved because a metadata write is itself a revision, and on an encrypted Collection it replaces the custom envelope wholesale, so keeping a previous writer's label would misattribute it.

Server-managed properties are not affected by this operation; a server MUST ignore any top-level properties other than custom, epoch, and writerId present in the request body (so that a client may read the Metadata object, modify it, and PUT it back without first stripping the server-managed properties).

Unlike the 11.6 Update (or Create By Id) Resource Operation, a PUT to /meta does not create anything: a Metadata object cannot exist apart from its Resource, so a PUT to the /meta path of a nonexistent Resource returns a not-found (404) error.

PUT /space/81246131-69a4-45ab-9bff-9c946b59cf2e/messages/hello-world/meta HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: ...

{
  "custom": {
    "name": "Hello World greeting",
    "tags": { "project": "demo", "status": "draft" }
  }
}

HTTP/1.1 204 No Content

A single chunk is addressed in member form (no trailing slash), and a Resource's chunk set is listed in container form (trailing slash), following the trailing-slash convention in 2.2 Reading This Document:

• PUT / GET / HEAD / DELETE /space/{space_id}/{collection_id}/{resource_id}/chunks/{index} -- store, read, head, and delete a single chunk.
• GET /space/{space_id}/{collection_id}/{resource_id}/chunks/ -- list the Resource's chunks.

As elsewhere, a request to the non-canonical variant of either form is redirected to the canonical one with 308 Permanent Redirect (which, unlike a 302, requires the client to replay the same method and body): a GET of the member-form chunks container without its trailing slash redirects to the trailing-slash form, and a member PUT (or other member method) carrying a trailing slash redirects to the no-slash form.

The {index} path segment MUST be a canonical non-negative decimal integer: a single 0, or a digit run with no leading zero, no sign, and no non-digit characters (so 0, 1, 42 are valid; 01, +1, -1, 1e3, 1.0 are not). A server MUST reject a non-canonical index with an invalid-id (400) error. Requiring a canonical spelling keeps each chunk addressable at exactly one URL.

A Resource's chunks are bound to the Resource. Deleting the parent Resource (see 11.7 Delete Resource Operation) MUST cascade-delete all of its chunks; there is no way to leave chunks behind a deleted Resource. A Resource's chunks are carried alongside its content by a Space export and restored by the matching import (the export reserved segment; see B. Reserved Path Segment Registry).

Chunk writes and deletes are invisible to the changes query profile (see D.1 changes profile): storing or deleting a chunk affects only the chunk's own ETag validator and MUST NOT advance the parent Resource's position in the feed, and the feed enumerates Resources only, never chunks. A client replicating a chunked Resource MUST therefore finish the write by updating the parent Resource's own content (its manifest; see 11.6 Update (or Create By Id) Resource Operation) after its chunks are stored: that final Resource write is what surfaces the change to replicating readers. A client that mutates a Resource purely through its chunks never appears on the feed.

Chunk operations use the same authorization model as every other operation in this specification (see 5. Authorization): writes (PUT, DELETE) are capability-only, while reads (GET, HEAD, and the container listing) are capability-or-policy. A chunk write's capability invocationTarget MUST be the chunk's own full URL (member form), and the listing's the chunks/ container URL -- the same exact-match target rule that governs every WAS URL (see target). For a read, the governing access-control policy is the parent Resource's: a chunk exposes a fragment of the same content the Resource holds, so whoever may read the Resource may read its chunks, and the maximum-privacy not-found rule (see 6. Error Handling) applies to a chunk exactly as to the Resource.

The space linkset resource (one of the B.1 Space-level reserved endpoints), located at /space/{space_id}/linkset contains a set of links to auxiliary resources and extension points:

• policy relation (https://wallet.storage/spec#policy) - A link to the /space/{space_id}/policy resource, which contains a set of links to access control policy documents.
• backends-available (https://wallet.storage/spec#backends-available) - A link to the /space/{space_id}/backends "Backends Available" resource.
• quotas relation (https://wallet.storage/spec#quotas) - A link to the /space/{space_id}/quotas per-backend storage quota report (see 15. Quotas).
• /space/{space_id}/query - Reserved for cross-space query operations.

Example space linkset resource request and response:

GET /space/81246131-69a4-45ab-9bff-9c946b59cf2e/linkset HTTP/1.1
Accept: application/linkset+json
Authorization: ...

Response:

HTTP/1.1 200 OK
Content-type: application/linkset+json

{
  "linkset": [
    {
      "anchor": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e",
      "https://wallet.storage/spec#policy": [
        {
          "href": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/policy",
          "type": "application/json"
        }
      ],
      "https://wallet.storage/spec#backends-available": [
        {
          "href": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/backends",
          "type": "application/json"
        }
      ],
      "https://wallet.storage/spec#quotas": [
        {
          "href": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/quotas",
          "type": "application/json"
        }
      ]
    }
  ]
}

The collection linkset resource (one of the B.2 Collection-level reserved endpoints), located at /space/{space_id}/{collection_id}/linkset contains a set of links to auxiliary resources and extension points:

• The policy relation (https://wallet.storage/spec#policy) - A link to the /space/{space_id}/{collection_id}/policy resource, which contains a set of links to access control policy documents.
• backend relation (https://wallet.storage/spec#backend) - A link to the detailed /space/{space_id}/{collection_id}/backend "Backend Selected for this collection" resource.
• quota relation (https://wallet.storage/spec#quota) - A link to the /space/{space_id}/{collection_id}/quota storage quota report for this collection (see 15. Quotas).
• /space/{space_id}/{collection_id}/query - (Optional) Query operations within a collection, discriminated by a request-body profile (see D. Query Profile Registry).

Example collection linkset resource request and response:

GET /space/81246131-69a4-45ab-9bff-9c946b59cf2e/messages/linkset HTTP/1.1
Accept: application/linkset+json
Authorization: ...

Response:

HTTP/1.1 200 OK
Content-type: application/linkset+json

{
  "linkset": [
    {
      "anchor": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/messages",
      "https://wallet.storage/spec#policy": [
        {
          "href": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/messages/policy",
          "type": "application/json"
        }
      ],
      "https://wallet.storage/spec#backend": [
        {
          "href": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/messages/backend",
          "type": "application/json"
        }
      ],
      "https://wallet.storage/spec#quota": [
        {
          "href": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/messages/quota",
          "type": "application/json"
        }
      ]
    }
  ]
}

A Backend description object advertises a backend's identity and features so that clients can select a suitable backend for each Collection (and so that storage management UIs can present meaningful choices to users).

Backend description properties:

• id (required) - A unique backend identifier (within a given space). The id default is conventionally used for the server-assigned default backend. See 4. Identifiers for additional constraints.
• name (optional) - An arbitrary human-readable name for the backend. Does not have to be unique.
• managedBy (optional) - Who operates the backend. One of:
  • server - configured and operated server-side (for example, the server's filesystem or database backends). This is the default if unspecified.
  • external - a "Bring Your Own Storage" provider registered by the client (for example, a connected Dropbox account).
• storageMode (optional) - An array of storage modalities the backend supports. This specification defines two values: document (structured JSON resources) and blob (opaque binary byte streams). Advertising modalities up front prevents mismatches, such as attempting to store a multi-gigabyte binary file on a JSON-only document store. If unspecified, clients SHOULD assume both modalities are supported.
• persistence (optional) - Either durable (the engine stores data on persistent media, e.g. disk, and it survives a restart) or volatile (the engine stores data in memory, e.g. a RAM-backed cache tier, and data may not survive a restart). Defaults to durable. Note that this is a technical property of the storage engine, deliberately distinct from any administrative data-retention rules (see the editor's note on lifecycle configuration below).
• features (optional) - An array of feature tokens advertising optional server affordances the backend provides beyond the baseline read/write API, so that clients can gate behavior on what the backend actually does. The vocabulary is open and additive: a client MUST ignore tokens it does not recognize, and MUST treat an absent token (or an absent features array) as "not supported" rather than assuming a default. Tokens this specification defines:
  • conditional-writes - the backend enforces If-Match / If-None-Match write preconditions (see 7.2 Conditional Requests).
  • changes-query - the backend serves the changes profile of the query endpoint (see D. Query Profile Registry).
  • blinded-index-query - the backend serves the blinded-index profile of the query endpoint (see D. Query Profile Registry).
  • chunked-streams - the backend supports chunk addressing for large blobs (see 12. Chunked Resources).
  • key-epochs - the backend persists the Resource epoch stamp, serves it on metadata/listing/feed reads, and enforces conditional Collection Description writes (ETag / If-Match), i.e. the server affordances C.4 Key Epochs requires. Clients gate recipient-management UX on this token.

Each token names something the server must actively do. Note that client-side encryption is deliberately not a backend feature: an encrypted document is opaque client-encrypted JSON that any document-capable backend stores faithfully with no server cooperation, and whether a given Collection is encrypted varies per Collection on the very same backend. Encryption is therefore a property of a Collection's data (signaled at the Collection level and held in the client's keys), not a capability of the backend. Concretely, this signal is the Collection's optional encryption descriptor (see 10.1 Collection Data Model): a non-secret declaration any authorized reader discovers from the Collection Description, while the keys stay in the client.

A backend that advertises conditional-writes takes on the server-side half of the client contract in 7.2 Conditional Requests. It MAY derive the ETag from an internal monotonic version counter (such as an Encrypted Data Vault document sequence); the validator is opaque to clients. It MUST evaluate a write's If-Match / If-None-Match precondition atomically with the write (for example, under a per-Resource lock), so that two concurrent writers cannot both observe the same prior version and both succeed. An in-process per-Resource lock satisfies this for a single-instance server only; a horizontally-scaled deployment needs to coordinate the check-and-write across instances (e.g. an atomic compare-and-swap on the stored version or a shared lock).

The list of backends registered on a Space is discoverable via the backends-available relation in the linkset (see 13.1 Space Linkset).

Example request:

GET /space/81246131-69a4-45ab-9bff-9c946b59cf2e/backends HTTP/1.1
Accept: application/json
Authorization: ...

Example success response:

HTTP/1.1 200 OK
Content-type: application/json

[
  {
    "id": "default",
    "name": "Server Filesystem",
    "managedBy": "server",
    "storageMode": ["document", "blob"],
    "persistence": "durable"
  },
  {
    "id": "dropbox",
    "name": "Dropbox",
    "managedBy": "external",
    "storageMode": ["blob"],
    "persistence": "durable"
  },
  {
    "id": "edv",
    "name": "Encrypted Data Vault",
    "managedBy": "server",
    "storageMode": ["document", "blob"],
    "persistence": "durable",
    "features": ["conditional-writes", "blinded-index-query", "chunked-streams"]
  }
]

Each collection has an optional backend property that is set during its creation (see 10.1 Collection Data Model). If not specified, it is assumed to have the id of default. The selected backend is discoverable via the backend relation in the collection's linkset (see 13.2 Collection Linkset).

Returns the storage report for a Space, grouped by backend, and is discoverable via the quotas relation in the Space's linkset (see 13.1 Space Linkset). Each entry in the backends array carries:

• id, name, managedBy - identifying properties from the corresponding Backend description object (see 14.1 Backend Data Model).
• state - the backend's current condition, one of: ok, near-limit, over-quota, or unreachable.
• usageBytes - total bytes consumed on this backend by this Space.
• limit - an object with capacityBytes and an isUnlimited boolean (when isUnlimited is true, capacityBytes MAY be omitted).
• constraints (optional) - operational constraints such as maxUploadBytes, the largest single upload the backend accepts.
• restrictedActions - an array of actions (uppercase HTTP verbs, the same vocabulary as the WAS Authorization Profile, see 5.1.5 Authorization Actions and the Root Capability) currently unavailable on this backend. For example, a full backend reports ["POST", "PUT"] while still permitting reads and deletes.
• measuredAt - when the usage numbers were measured. For external ("Bring Your Own Storage") backends, the server proxies the provider's reported numbers, which may be cached or stale; measuredAt lets clients judge freshness independently of the report's top-level respondedAt.

Example request:

GET /space/81246131-69a4-45ab-9bff-9c946b59cf2e/quotas HTTP/1.1
Accept: application/json
Authorization: ...

Example success response:

HTTP/1.1 200 OK
Content-type: application/json

{
  "respondedAt": "2026-06-12T13:25:00Z",
  "backends": [
    {
      "id": "default",
      "name": "Server Filesystem",
      "managedBy": "server",
      "state": "ok",
      "usageBytes": 524288000,
      "limit": { "capacityBytes": 10737418240, "isUnlimited": false },
      "restrictedActions": [],
      "measuredAt": "2026-06-12T13:25:00Z"
    },
    {
      "id": "dropbox",
      "name": "Dropbox",
      "managedBy": "external",
      "state": "near-limit",
      "usageBytes": 314572800,
      "limit": { "capacityBytes": 367001600, "isUnlimited": false },
      "constraints": { "maxUploadBytes": 157286400 },
      "restrictedActions": [],
      "measuredAt": "2026-06-12T13:24:45Z"
    }
  ]
}

With the include=collections query parameter, each backend entry additionally carries a usageByCollection array, giving storage-manager applications a full breakdown in a single request while keeping the hot-path payload lean:

HTTP/1.1 200 OK
Content-type: application/json

{
  "respondedAt": "2026-06-12T13:25:00Z",
  "backends": [
    {
      "id": "default",
      "name": "Server Filesystem",
      "managedBy": "server",
      "state": "ok",
      "usageBytes": 524288000,
      "limit": { "capacityBytes": 10737418240, "isUnlimited": false },
      "restrictedActions": [],
      "measuredAt": "2026-06-12T13:25:00Z",
      "usageByCollection": [
        { "id": "credentials", "usageBytes": 419430400 },
        { "id": "inbox", "usageBytes": 104857600 }
      ]
    }
  ]
}

Returns the storage report for a single Collection, scoped to that Collection's backend (the entry has the same shape as a backends array entry, with usageBytes reflecting only this Collection's consumption). It is discoverable via the quota relation in the Collection's linkset (see 13.2 Collection Linkset).

Not all backends support per-collection accounting. Where unsupported, the server returns an unsupported-operation (501) error.

Errors (see F. Error Type Registry for canonical examples):

• not-found (404) -- the Space or Collection does not exist, or the caller is not authorized to read the quota report.
• unsupported-operation (501) -- the Collection's backend does not support per-collection quota accounting.