Wallet Attached Storage v0.5

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, C. Reserved Path Segment Registry, D. Encryption Scheme Registry, and G. Error Type Registry (each of which also carries an inline "This appendix is normative." banner). The remaining appendices -- H. Goals and Requirements and I. 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 C. Reserved Path Segment Registry) but does not yet define an operation for; a server MUST NOT repurpose a reserved path. A method the server does not implement at a reserved endpoint is answered with 405 Method Not Allowed; see C.4 Methods at Reserved Endpoints.

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 a container's Metadata object, whose update operation replaces the whole object -- so two concurrent recipient changes to a key-epoch roster (see D.4 Key Epochs) would otherwise silently clobber one another:

• The 10.3 Read Collection Metadata operation response includes an ETag header -- a strong validator over the object's metaVersion (the same quoted form Resources use).
• The 10.4 Update (or Create by Id) Collection operation request MAY carry If-Match. A server implementing the operation 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.
• That request MAY instead carry If-None-Match: *, the create-if-absent form, which succeeds only when the Collection does not exist. Two clients that both read the object, find the Collection absent, and PUT a create would otherwise let the loser's full replacement overwrite the winner's (replacing, for example, its backend selection with the loser's).
• If-Match is opt-in: an unconditional PUT remains valid (and remains last-writer-wins). Recipient-management clients MUST use If-Match.

The Space Metadata object carries the same validator, on the same terms: the 9.2 Read Space operation response includes an ETag header over the object's monotonic version, the 9.3 Update (or Create by Id) Space operation request MAY carry If-Match or If-None-Match: *, and a server advertising the conditional-writes feature MUST evaluate either atomically with the write and reject a failed precondition with precondition-failed (412). The Create Space and Update Space responses carry the new ETag. The create-if-absent form is what lets two clients provisioning the same Space at once resolve the race at the server: the loser's replacement PUT would otherwise rewrite the winner's type array, which a server accepts at creation only (see 9.1 Space Metadata Data Model).

A Collection's metaVersion is independent of every Resource's validator: writing a Resource never advances it, and writing the Metadata object never advances a Resource's. Unlike the Resource-level validators it is not gated on the conditional-writes backend feature -- a server implementing the Collection management operations MUST maintain it and MUST support both preconditions -- and it covers configuration and annotation writes alike; see 10.1.1 Versioning.

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": []
}

A Space's description is its Metadata object, addressable at the reserved meta path segment under the Space URL (one of the C.1 Space-level reserved endpoints). It is what 9.2 Read Space operation returns and what 9.3 Update (or Create by Id) Space operation writes; the Space URL itself is the container of the Space's Collections (see 9.5 List All Collections operation).

Because the meta segment occupies the {collection_id} position, meta is a reserved Collection id: creating a Collection with the id meta is a reserved-id conflict (see C. Reserved Path Segment Registry).

PUT is not defined at the Space URL itself; the replacement write is a PUT of this object. A server MUST answer a PUT at the Space URL with 405 Method Not Allowed.

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). See B. Space Controller DID Method Registry for the DID methods a controller may use.

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 itself, in canonical (trailing-slash) form. Added by the server, used in the Space Metadata object as well as the 8.2 List Spaces Operation result. The Metadata object's own URL is this value followed by meta.
• 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 C.1 Space-level reserved endpoints.

A server that supports conditional writes (see 7.2 Conditional Requests) also keeps a server-managed version validator for each Space Metadata object: an opaque strong validator that changes on every write of the object and is never reused after the Space is deleted. It is not a member of the Space Metadata object; it is surfaced only as the ETag header of the Read Space response and of the Create Space and Update Space responses, and consumed only through the If-Match and If-None-Match: * preconditions of the Update (or Create by Id) Space operation.

• Returns the 9.1 Space Metadata Data Model for the specified space id
• Requires appropriate authorization (root zcap invoked by the space's controller, or a zcap granting permission to read a particular space)
• On a server supporting conditional writes, the response includes an ETag header over the Space Metadata object's version, for use with If-Match on a subsequent update (see 7.2 Conditional Requests); a request carrying an If-None-Match that covers it is answered 304 Not Modified with the ETag and no body (see 7.1 Caching)

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/meta HTTP/1.1
Host: example.com
Accept: application/json
Authorization: ...

HTTP/1.1 200 OK
Content-type: application/json
ETag: "z3fkq.2"

{
  "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"
}

A PUT of a Space's Metadata object is a full replacement of that object, and creates the Space when none exists under that id. The client specifies the id of the Space in the request URL.

• 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 Metadata 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.

A new controller written by an update is subject to the same method acceptance as one set at creation (see B. Space Controller DID Method Registry), plus the promotion rule of 5.1.2.2 Setting a controller to an optional DID method: a proposed controller of an optional method MUST resolve and verify before it is stored, and a server MAY admit such controllers only through this operation.

The request MAY carry a precondition (see 7.2 Conditional Requests): If-Match: "<etag>" performs the update only if the Space Metadata object's current ETag matches it, and If-None-Match: * performs the write only if no Space exists under that id yet. A server that supports conditional writes MUST evaluate the precondition atomically with the write, after authorization, and answer a failed one with precondition-failed (412). Both are opt-in: an unconditional PUT remains valid and remains last-writer-wins. A client that creates a Space it has just read as absent SHOULD send If-None-Match: * and, on a 412, re-read the Space instead of treating the response as a failure. The success response carries the Metadata object's new ETag.

PUT /space/81246131-69a4-45ab-9bff-9c946b59cf2e/meta 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/
ETag: "z3fkq.1"

PUT /space/81246131-69a4-45ab-9bff-9c946b59cf2e/meta 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
ETag: "z3fkq.2"

• 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 projection of the Collection's Metadata object (see 10.1 Collection Metadata Data Model). 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/ 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/",
  "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
    }
  ]
}

A Collection's description is its Metadata object, addressable at the reserved meta path segment under the Collection URL (one of the C.2 Collection-level reserved endpoints). It holds everything recorded about the Collection: what it is called, how its Resources are stored and whether they are client-side encrypted, who created it, and whatever annotations the user keeps on it. The Collection URL itself is the container of the Collection's Resources (see 10.5 List Collection operation).

Because the meta segment occupies the {resource_id} position, meta is a reserved Resource id (see C. Reserved Path Segment Registry). A GET or PUT at this path is always a Collection metadata operation, so no Resource is ever addressed at the id meta. Methods this specification does not define at this path (DELETE in particular) are not Resource operations either; see C.4 Methods at Reserved Endpoints for how a server answers them. The same meta segment also roots the Collection's governing history log, a separate sub-resource at meta/log with operations and a validator of its own (see 10.7 Collection Governing History Log).

PUT is not defined at the Collection URL itself; the replacement write is a PUT of this object. A server MUST answer a PUT at the Collection URL with 405 Method Not Allowed.

Reading and writing this object are part of the OPTIONAL Collection management group (see 2.6 API Summary): on a server where Collections are pre-configured or implicit, they are not implemented, and such a server SHOULD answer requests to this path with an unsupported-operation (501) error.

Writable properties:

• 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 when the Collection is created, defaults to the value { "id": "default" }. An update that omits the member keeps the stored selection (see 10.4 Update (or Create by Id) Collection operation). 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 D. 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's Metadata object 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), provided no plaintext member is present (the two are mutually exclusive; see plaintext below), 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 D. 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 D. Encryption Scheme Registry. On the edv scheme, the descriptor MAY additionally carry the key-epoch public references, currentEpoch and epochs (see D.4 Key Epochs), which let several readers hold per-reader keys and let reader removal rotate the collection key, and the blinding-key reference hmac (see D.4.2 The blinding-key member), which distributes the key under which a client blinds the attributes it indexes for the blinded-index query profile. These members contain only public key identifiers and wrapped-key ciphertext. As with the rest of the descriptor, the server stores them opaquely. A server that recognizes the scheme validates their shape, enforces a small set of server-side invariants on the epoch members (epochs is append-only, currentEpoch never moves backwards), holds the hmac member permanent once present, and interprets nothing else. Client-side profiles built on epochs (such as [WAS-EC]) require the epoch 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. On a backend advertising governed-history-logs, the descriptor MAY instead be governed by the Collection's history log: the server then derives it from the log's head entry, stamps a history member on the served value, and refuses a direct write of it with an encryption-history-log-governed error; see 10.7 Collection Governing History Log.

• plaintext (optional) - An object declaring the server-side processing the server may apply to this collection's Resources. It is the counterpart of encryption: the two members describe the two ways a server may treat what it stores, and a Collection's Metadata object MUST NOT carry both. The exclusion is by presence. An empty plaintext object still excludes encryption, and a server MUST reject a create or update whose resulting object would carry both with an invalid-request-body error. A Collection carrying neither member is a plaintext collection with no server-side processing declared. Unlike the set-once encryption, plaintext is updatable for the collection's life: a supplied object replaces the stored one, an update that omits the member leaves the stored one untouched, and {} is the empty state (present, declaring nothing). A plaintext value that is not an object is an invalid-request-body error. Its one member in this version is indexes:

  • indexes (optional) - An array naming the attributes the server extracts from stored Resources and indexes for query profiles that read plaintext (see E. Query Profile Registry). This is server-side plaintext indexing: the server reads the stored values. It is distinct from the client-blinded indexes of an encrypted collection, which the client computes under the descriptor's hmac key (see D.4.2 The blinding-key member), carries in each envelope's indexed member, and queries through the blinded-index profile (see E.2 blinded-index profile). Each entry is an object { "name": ..., "source": ..., "unique": ... }, or a bare string as shorthand for { "name": "<string>", "source": "content" }:

    • name - The attribute name. Required, a non-empty string, and unique across the array regardless of source, since queries refer to an attribute by name alone.
    • source (optional) - Where the attribute is read from: content (the default) reads the top-level member of that name from a JSON Resource's stored content; custom reads it from the custom object of the Resource's Metadata (see 11.8 Resource Metadata Data Model), which is how a Blob Resource becomes queryable. Any other value is an invalid-request-body error.
    • unique (optional) - A boolean, false when absent. When true, the attribute's (name, value) pair is a uniqueness claim within the collection: a server MUST reject a Resource write whose extracted value is already held by a different Resource in the same collection with an id-conflict error, under the same authorization-first and atomicity rules as unique blinded attributes (see E.2 blinded-index profile, Unique blinded attributes). A Resource re-asserting its own value never self-conflicts. A server MUST also reject an update that adds unique: true for an attribute whose already-stored Resources violate it, with an id-conflict error, leaving the stored declaration unchanged.

    Declaring a content-sourced entry is the collection's opt-in to the server parsing its JSON Resource content on write. A malformed indexes array (not an array, an entry that is neither a non-empty string nor an object with a non-empty string name, a non-boolean unique, or a duplicate name) is an invalid-request-body error. Adding or removing an entry is a declaration change only: a server MUST NOT require the already-stored Resources to be rewritten for the change to take effect.

• custom (optional) - A JSON object holding the user's annotations, with the same shape as the Resource-level custom (see 11.8 Resource Metadata Data Model): an optional human-readable name and an optional tags object of string-valued annotations. A Collection with no annotations set MAY omit custom or report it as {}. A Collection therefore has two name slots. The top-level name above is server-visible plaintext and is what listings report; custom.name is supplementary. On an encrypted Collection the two trade places: a client SHOULD leave the plaintext name unpopulated, so that a listing defaulting a missing name to the id reveals nothing (see 9.5 List All Collections operation), and custom.name inside the encrypted envelope is then the only name the Collection has.

• epoch (optional) - The key-epoch id this object's custom envelope was encrypted under (see D.4 Key Epochs), declared by the writer and stored opaquely; the server never computes or verifies it. Its omission rule deliberately inverts the Resource-level one: an omitted epoch on a write of this object clears the stored value, where at Resource level it is preserved. The Resource-level epoch describes the content write, which a write of this object does not touch, so preserving it there is correct; here the only thing epoch can describe is the custom envelope itself, which every write replaces wholesale, so a preserved value would misdescribe the new envelope. A client writing to an encrypted Collection therefore re-declares epoch each time.

Properties automatically added by the server, and read-only: a server MUST ignore any of them supplied in a request body.

• createdAt (optional) - The [RFC3339] date-time at which the Collection was created.
• updatedAt (optional) - The [RFC3339] date-time at which this Metadata object was last modified.
• 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 Metadata Data Model): recorded on the first write, preserved by later writes, and OPTIONAL.
• url - A relative URL to the collection itself, in canonical (trailing-slash) form. Added by the server, used in this object as well as the List Collections operations result. This object's own URL is that value followed by meta.
• 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 C.2 Collection-level reserved endpoints.

There is no writerId member. A Collection's Metadata object 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 D. 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 every other member of this object stays 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. On an encrypted Collection a present custom MUST be either a conforming envelope or an empty object; an empty object clears the stored annotations. Omitting custom clears them too, exactly as on a plaintext Collection, because a PUT of this object is a full replacement. That is the same omission-clears rule epoch follows.

Example Metadata object of a plaintext Collection (JSON representation):

{
  "id": "73WakrfVbNJBaAmhQtEeDv",
  "url": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/73WakrfVbNJBaAmhQtEeDv/",
  "type": ["Collection"],
  "name": "Verifiable Credentials Collection",
  "createdAt": "2026-06-10T09:12:00Z",
  "updatedAt": "2026-06-12T13:25:00Z",
  "createdBy": "did:key:z6MkpBMbMaRSv5nsgifRAwEKvHHoiKDMhiAHShTFNmkJNdVW",
  "generator": "did:key:z6MkfriqYRX3JBqzsbVbKuBUxDR2nsjLTu6AbrxJZAmFmXWb",
  "generatorOrigin": "https://app.example.com",
  "linkset": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/73WakrfVbNJBaAmhQtEeDv/linkset",
  "custom": {
    "tags": { "project": "demo" }
  }
}

A Collection is added to a Space by POSTing its Metadata object (see 10.1 Collection Metadata Data Model) to the Space. The client can specify the id of the Collection in the body. 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/ 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/ 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/

• Returns the 10.1 Collection Metadata Data Model for the specified Collection
• 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
• The response includes an ETag header over the object's metaVersion, for use with If-Match on a subsequent update (see 7.2 Conditional Requests); a request carrying an If-None-Match that covers it is answered 304 Not Modified with the ETag and no body (see 7.1 Caching)
• On a Collection governed by its history log, the encryption member is derived from the log's head entry and carries a history member naming the log (see 10.7 Collection Governing History Log)

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

HTTP/1.1 200 OK
Content-type: application/json
ETag: "3"

{
  "id": "73WakrfVbNJBaAmhQtEeDv",
  "url": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/73WakrfVbNJBaAmhQtEeDv/",
  "type": ["Collection"],
  "name": "Verifiable Credentials Collection",
  "createdAt": "2026-06-10T09:12:00Z",
  "updatedAt": "2026-06-12T13:25:00Z",
  "createdBy": "did:key:z6MkpBMbMaRSv5nsgifRAwEKvHHoiKDMhiAHShTFNmkJNdVW",
  "linkset": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/73WakrfVbNJBaAmhQtEeDv/linkset",
  "backend": { "id": "default" },
  "custom": {
    "tags": { "project": "demo" }
  }
}

A PUT of a Collection's Metadata object is a full replacement of that object, and creates the Collection when none exists under that id. The client specifies the id of the Collection in the request URL; it MUST NOT collide with the list of C.1 Space-level reserved endpoints.

Full replacement means that a writable member the request omits is cleared, so a client that wants to change one member reads the object, edits it, and writes it back. Some members qualify that rule. The server-managed members are read-only: a server MUST ignore createdAt, updatedAt, createdBy, url, and linkset in a request body, so that a read-modify-write roundtrip needs no stripping. On a Collection whose encryption descriptor is governed by its history log, the server derives that member from the log's head and refuses a direct write of it (see 10.7 Collection Governing History Log). An update that omits plaintext leaves the stored member untouched (see its member definition). And an update that omits backend MUST keep the stored backend selection. Clearing it would repoint the Collection at the default backend. The Resources already stored in the selected backend would become unreachable, and later writes would land elsewhere. Only a create that omits backend is assigned the default.

The request MAY carry a precondition (see 7.2 Conditional Requests): If-Match: "<etag>" performs the write only if the object's current ETag matches it, and If-None-Match: * performs the write only if the Collection does not exist yet. A failed precondition is precondition-failed (412); an unconditional PUT remains last-writer-wins. The success response carries the object's new ETag.

PUT /space/81246131-69a4-45ab-9bff-9c946b59cf2e/73WakrfVbNJBaAmhQtEeDv/meta 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
Location: https://example.com/space/81246131-69a4-45ab-9bff-9c946b59cf2e/73WakrfVbNJBaAmhQtEeDv/
ETag: "1"

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

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

HTTP/1.1 204 No Content
ETag: "2"

• 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"
    }
  ]
}

A Collection MAY carry one governing history log: an append-only, client-written log that the server stores at the sub-path /space/{space_id}/{collection_id}/meta/log and from whose head entry the server derives a member of the Collection's Metadata object. The clients that share the Collection write the log and read it. The server stores it, checks a minimal line contract on every write, and serves the derived member to every reader. Which members a log governs, what an entry is beyond its state, and how a reader verifies the log are defined by a governing profile, not by this specification. The encryption descriptor of the 10.1 Collection Metadata Data Model is the first governed member, under the resource log profile of [WAS-EC]; see 10.7.6 The first governed member: encryption.

Support is OPTIONAL and discoverable. A backend that implements the sub-resource advertises the governed-history-logs token in its Backend description (see 14.1 Backend Data Model). A server without the feature serves a client-written member instead, so a producer MUST consult the token before choosing which form to write. A server that does not implement the sub-resource SHOULD return an unsupported-operation (501) error for requests to its path, and MUST NOT treat them as Resource operations (the path lies under the reserved meta segment; see C.2 Collection-level reserved endpoints).

"history": {
  "method": "<the genesis entry's parameters.method>",
  "resource": "<the absolute URL of the log>"
}

The body of a write is the whole log. A client appends by sending the stored bytes verbatim followed by the new line, under an If-Match precondition carrying the validator of the log it read. A client creates the log, and so declares the Collection governed, with If-None-Match: *. A client MUST carry one of the two preconditions on every write. A server evaluates the precondition it is given atomically with the write. On a Collection that already carries a log, a server MUST also check, atomically with the write, that the body fast-forwards the stored log: the stored bytes verbatim followed by exactly one new line. A body the stored log is not a prefix of (a stale read, or a rewritten prefix) MUST be refused with a precondition-failed error (412), whether or not the write carries If-Match; a body that extends the stored bytes by no line or by several MUST be refused with an invalid-request-body error (400). A write capability can therefore add to a log but not erase or rewrite it. The server also checks the line contract and, for a governed encryption descriptor, the head-state transition (10.7.6 The first governed member: encryption). It verifies nothing inside an appended entry: a bad proof or a broken hash link is a chain break that a verifying reader detects under the governing profile.

PUT /space/81246131-69a4-45ab-9bff-9c946b59cf2e/73WakrfVbNJBaAmhQtEeDv/meta/log HTTP/1.1
Host: example.com
Content-Type: text/jsonl
If-None-Match: *
Authorization: ...

{"versionId":"1-...","versionTime":"2026-09-07T10:00:00Z","parameters":{"method":"resource-log:0.1","scid":"z..."},"state":{"type":"WasEpochConfiguration","scheme":"edv","currentEpoch":"urn:uuid:8d3f...","epochs":[...]},"proof":[...]}

HTTP/1.1 204 No Content
ETag: "z3fkq.1"

"encryption": {
  "type": "WasEpochConfiguration",
  "scheme": "edv",
  "currentEpoch": "urn:uuid:8d3f...",
  "epochs": [...],
  "history": {
    "method": "resource-log:0.1",
    "resource": "https://example.com/space/81246131-69a4-45ab-9bff-9c946b59cf2e/73WakrfVbNJBaAmhQtEeDv/meta/log"
  }
}

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).

Server-generated documents. API documents generated by the server -- Metadata objects, listings, quota reports -- 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 C.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 C.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.1 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.

  On a plaintext Collection, a custom value that is not a JSON object, or a name or tags member that does not have the shape described above, is an invalid-request-body error. On an encrypted Collection, custom is validated as an envelope instead (see below).

• epoch (optional) - The key-epoch id this Resource's content was encrypted under (see D.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 D. 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. An empty custom object is accepted as well and clears the stored value, and so does an omitted custom, here as on a plaintext Collection. 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 ({}); both forms clear on an encrypted Collection too.

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 D.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 C. Reserved Path Segment Registry).

Chunk writes and deletes are invisible to the changes query profile (see E.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 C.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 C.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 E. 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 E. Query Profile Registry).
  • blinded-index-query - the backend serves the blinded-index profile of the query endpoint (see E. 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 and serves it on metadata, listing, and feed reads, i.e. the server affordances D.4 Key Epochs requires beyond the conditional writes on a Collection's Metadata object that every implementation of the Collection management operations supports (see 10.1.1 Versioning). Clients gate recipient-management UX on this token.
  • governed-history-logs - the backend stores a Collection's governing history log at its meta/log sub-resource and derives the governed member of the Collection's Metadata object from the log's head (see 10.7 Collection Governing History Log). A producer consults this token to learn whether to write the log or the member itself.

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 Metadata Data Model): a non-secret declaration any authorized reader discovers from the Collection's Metadata object, 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 Metadata 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 G. 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.