Portable Web Spaces 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 12. Resources and Blobs plus the baseline authorization profile (5. Authorization, [PWS-AUTHZ]).

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 -- plus the service description through which a client learns which versions and tiers the server speaks. 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, and the server-side validation that the encrypted-collection profile [PWS-EC] builds on -- advertised server-wide in the service description's features array and, per Space, 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. Space Controller DID Method Registry, C. Policy Type Registry, E. Reserved Path Segment Registry, F. Encryption Scheme Registry, and H. Error Type Registry (each of which also carries an inline "This appendix is normative." banner). The remaining appendices -- I. Goals and Requirements and J. 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). PWS reads are authorized too, so the header is required on the GET just as on the PUT. How that invocation is constructed is defined by the baseline authorization profile, [PWS-AUTHZ], and its fully expanded form -- with the Digest, Capability-Invocation, and Signature headers spelled out -- is shown once in the worked example there. Producing that signature requires a conformant PWS 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 E. 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 E.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).

A server MUST implement at least one authorization profile listed in the table below. It MUST list every profile it implements in the service description's specs member, under the profile's identifier (see 8.2 Service Description Data Model). The members of a profile's version entry are defined by the profile.

The PWS Authorization Profile [PWS-AUTHZ] is the baseline. A server conformant to the Minimal profile of 2.4 Scope and Conformance Profiles MUST implement it, so that the Minimal profile is implementable from this document and [PWS-AUTHZ] alone. A server MAY implement further profiles. Registering a profile adds a row to this table.

Every authorization profile meets the following contract:

• Private by default. Absent a policy that grants otherwise, only the Space's controller, or a party the controller has authorized through the profile, may perform any operation on the Space or on anything in it. Reads are authorized just as writes are.
• The Space controller is the root of trust. Every authorized operation traces back to the Space's controller, see 5.2 Space controller and the Root of Trust.
• Actions and targets. A profile defines how a credential names the operation a request performs and the resource it acts on. The baseline names them by the uppercase HTTP method and the full request URL (see Capability Invocation in [PWS-AUTHZ]), the same terms this specification's own operation sections use.
• Policies broaden, and only broaden. A profile consults the effective policy only after any credential the request carries, under the evaluation contract of 5.4 Access Control Policies.
• Maximum privacy. A request that lacks sufficient privilege for an existing target is answered as if the target did not exist, see 6. Error Handling. A profile reports its failures with the kinds of H. Error Type Registry.

Conceptually, the space's controller serves as the root of trust and authorization for any operations on the space or its collections or resources. That is, any operation requiring an authorization MUST provide a chain of proof all the way to the space controller. The forms that proof takes (a credential the controller signs directly, one the controller delegated to another agent, or a matching access control policy) are defined by the authorization profile; for the baseline, see the Root of Trust section of [PWS-AUTHZ].

Space controllers MUST be in the form of a DID.

For minimal compatibility, all PWS implementations MUST support the did:key DID Method, using the Multikey encoding of Ed25519 elliptic curve keys, as specified in the Multikey section of the CID spec as the space controller.

A Space controller MAY use a DID method other than did:key, provided the method is listed in the B. Space Controller DID Method Registry. Support for every method other than did:key is OPTIONAL. A server refuses a controller whose DID method it does not support with invalid-request-body (400), whether at creation or on an update (see 9.1.2 Create Space Errors and 10.3 Update (or Create by Id) Space operation).

To set access control policy for a space, use the linkset property.

Example (fetching a space's link set):

GET /space/81246131-69a4-45ab-9bff-9c946b59cf2e/linkset HTTP/1.1
Host: example.com
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://w3id.org/pws#policy": [
        {
          "href": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/policy",
          "type": "application/json"
        }
      ]
    }
  ]
}

Example (fetching a specific policy document from the link set):

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

Capabilities answer the question "does the caller hold a credential that grants this action?" Access control policies answer the complementary question "does this target grant this action to callers in general (or to a named set of principals)?" Policies are how a controller makes a target public-readable (or, in future profiles, shares it with a list of people or groups) without having to issue a capability to each caller.

A policy is a JSON document with a required type property, stored at the /policy auxiliary resource of a Space, Collection, or Resource and discoverable via the policy relation in the linkset (see 13.1 Space Linkset and 13.2 Collection Linkset).

Evaluation contract:

• Capability first, policy second. A request is first checked against any capability invocation it carries. The effective policy is consulted only as a fallback, and it can only broaden access -- a policy never denies a caller who presents a valid capability.
• Fail-closed. An absent policy, or a policy whose type an implementation does not recognize, grants nothing. The recognized types are those of C. Policy Type Registry.
• Most-specific-wins inheritance. The effective policy for a target is the one set at the most specific level that has a policy document: a Resource policy overrides a Collection policy, which overrides a Space policy.
• Access kind. For policy evaluation, the request method is reduced to a coarse access kind: GET (and HEAD) is a read; POST, PUT, and DELETE are a write.

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

A server MUST support [RFC9110] conditional requests to provide optimistic concurrency control on every Resource write path. This mechanism prevents 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 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 server derives it is a server-side concern.

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 MUST evaluate the precondition atomically with the write, so that two concurrent writers cannot both observe the same prior version and both succeed. 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 F.4 Key Epochs) would otherwise silently clobber one another:

• The 11.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 11.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 10.2 Read Space operation response includes an ETag header over the object's monotonic version, the 10.3 Update (or Create by Id) Space operation request MAY carry If-Match or If-None-Match: *, and a server 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 10.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. A server implementing the Collection management operations MUST maintain it and MUST support both preconditions, on the same baseline terms as a Resource's validator, and it covers configuration and annotation writes alike; see 11.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 -- 9.2 List Spaces Operation, 10.5 List All Collections operation, and 11.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.

A server MUST include a Link header [RFC8288] with the service link relation [RFC5023] on every response it sends, whose target is the service description's URL. This includes error responses (a maximum-privacy "not found" for an unauthorized request still carries the header), the 308 redirects to a canonical path, and responses to HEAD and OPTIONS. The header is static and server-wide, so it reveals nothing about the existence of any Space, Collection, or Resource.

Link: <https://example.com/pws/service>; rel="service"

The service relation is chosen over the service-desc and service-doc pair of [RFC8631] because this specification defines a single machine-readable document and no separate human-readable one; [RFC8631] section 3.3 recommends service for exactly that case.

Because the primary consumers are browser-hosted clients on other origins, two CORS requirements apply:

• A server MUST include Access-Control-Expose-Headers: Link on every response, so that a cross-origin client can read the Link header.
• A server MUST serve the service description with Access-Control-Allow-Origin: *, since it is fetched anonymously and cross-origin.

The discovery flow is therefore two requests from any PWS URL a client has come across (a link to a shared Resource, a public Collection, a service endpoint in a DID document):

1. HEAD the URL. The response status does not matter; the client reads the Link header's service target.
2. GET that target (see 8.4 Read Service Description operation).

A DID document's service endpoint MAY point at the service description itself, in which case a client skips the first step. The service type for that entry is not yet specified.

The service description is also linked from the 13.1 Space Linkset and the 13.2 Collection Linkset under the same service relation, as a convenience for a client that already holds a Space. Those links are secondary: a client that can read a linkset is already speaking a layout.

A response with no service link comes from a server that predates this document, which was introduced in v0.5. A client MUST treat such a server as speaking v0.4.

The service description is a JSON object with the following members:

• url (required) - The service description's own canonical URL, so that a copy of the document (from a cache, or a DID document) can be refetched.
• specs (required) - An object whose keys are specification identifiers and whose values are arrays of version entries, one per version of that specification the server implements. A specification is listed at every version the server speaks, so a server can serve two route tables during a transition and a client can pick the newest it understands.
• instance (optional) - An object identifying the deployed software, for operators who choose to disclose it. See 8.3 Instance Disclosure for its members and the trade-off.

Every URL in the service description MUST be absolute. The document is self-contained: nothing in it is resolved against the URL it was fetched from.

Specification identifiers. The key of a specs entry is the persistent identifier that the specification declares for itself in its own text, which is not the same as its current document location. A specification that declares no identifier cannot be advertised. Clients compare keys as opaque strings, with no URL normalization: a trailing slash or a scheme difference is a different key. The version is never part of the key; the key names the specification family, and the version entries under it carry the versions.

This specification's identifier is https://w3id.org/pws.

Version entries. A version entry is a JSON object describing one version of one specification. Its members are defined by the specification the key names. Two members are common to every entry:

• version (required) - The specification version, as a bare major.minor string such as "0.5". The patch level never changes the wire contract and is not carried.
• url (optional) - The URL of the specification document at exactly this version, for a reader who wants the text. A version-frozen location (a dated snapshot or a tag) is preferred over a "latest" URL, which stops describing the version once the specification moves on.

An entry means the server conforms to that version's required profile. What else the entry advertises is the owning specification's business: endpoint URLs, optional sections it also implements, supported algorithms. An optional section that has an endpoint of its own is advertised by a URL member, and its absence means the section is not supported; a feature token is used only for an affordance with no URL of its own. This keeps the service description the root of the URL graph: with no fixed path for anything at the server level, a client learns every server-level URL from here. A companion specification defines the tokens (if any) of its own version entry's features array; this specification does not enumerate them.

This specification's version entry. A version entry under https://w3id.org/pws carries, in addition to version and url:

• spaces (optional) - The absolute URL of the Spaces Repository (see 9. Spaces Repositories). Absent when the server does not implement it.
• features (optional) - An array of feature tokens naming the OPTIONAL sections of this specification the server implements, beyond the Minimal profile: the vocabulary is open and additive, a client MUST ignore tokens it does not recognize, and MUST treat an absent token (or an absent array) as "not supported". The tokens are those of the profile table in 2.4 Scope and Conformance Profiles.

An authorization profile's version entry. A server lists every authorization profile it implements under the profile's own identifier (see 5.1 Authorization Profiles), and the profile defines its entry's members. The baseline profile's entry, under https://w3id.org/pws/authz-profile, carries the signature algorithms and delegation-proof cryptosuites the server accepts; see the Service Description Entry section of [PWS-AUTHZ]. The example below shows one.

The instance member identifies the software serving the document. It is OPTIONAL, its presence is the operator's choice, and a client MUST NOT gate any behavior on it: what a client acts on is specs. Its members:

• name (optional) - The software's name, such as the project name of a reference implementation.
• version (optional) - The software's release version. Disclosing an exact patch level is NOT RECOMMENDED; see below.
• source (optional) - The absolute URL of the software's source code. A deployment under a license that requires offering source to network users can satisfy that requirement here.
• homepage (optional) - The absolute URL of the software's project page.

The members follow the software object of NodeInfo, the most widely deployed vocabulary for this purpose, with source in place of its repository.

Two practices pull in opposite directions here, and this specification takes no side beyond the default above. Server-hardening guidance (for example, the OWASP Application Security Verification Standard's requirement that responses not expose detailed version information of system components) says to withhold software versions, because mass scanners and exploit kits select targets by matching an exact version string against a known-vulnerable release. Federated ecosystems (Fediverse NodeInfo, Matrix) routinely advertise software and version, because interop debugging across many independent implementations and an ecosystem-wide vulnerability response both depend on knowing who runs what.

Two facts specific to this specification narrow the gap. The specs member already fingerprints a server by the versions and features it speaks, so withholding the software name buys less than it does for a web server behind a generic page. And a server's conformance behavior identifies its implementation to any client that cares to probe. What instance adds is the cheap path: a scanner keying on a version string. Omitting version, or carrying only its major component, removes that path while keeping name, source, and homepage for debugging and license compliance.

GET on the URL named by the service link returns the service description as application/json. The operation requires no authorization. The response SHOULD be cacheable (Cache-Control and an ETag), so that a client re-checking a host pays a revalidation rather than a fetch.

Example discovery from a Resource URL the client holds:

HEAD /pws/space/81246131-69a4-45ab-9bff-9c946b59cf2e/messages/hello-world HTTP/1.1
Host: example.com

Response (the Resource is private, so the unauthorized request is "not found"; the Link header is present regardless):

HTTP/1.1 404 Not Found
Link: <https://example.com/pws/service>; rel="service"
Access-Control-Expose-Headers: Link

Example service description request and response:

GET /pws/service HTTP/1.1
Host: example.com
Accept: application/json

Response:

HTTP/1.1 200 OK
Content-Type: application/json
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: Link
Cache-Control: public, max-age=3600
ETag: "a1b2c3"
Link: <https://example.com/pws/service>; rel="service"

{
  "url": "https://example.com/pws/service",
  "specs": {
    "https://w3id.org/pws": [
      {
        "version": "0.5",
        "url": "https://w3c-ccg.github.io/wallet-attached-storage-spec/v0.5/",
        "spaces": "https://example.com/pws/spaces/",
        "features": ["listing", "collection-management", "space-management",
                     "linksets", "policy", "backends", "quotas",
                     "created-by"]
      },
      {
        "version": "0.4",
        "url": "https://w3c-ccg.github.io/wallet-attached-storage-spec/v0.4/",
        "spaces": "https://example.com/pws/spaces/",
        "features": ["listing", "collection-management", "space-management",
                     "linksets", "policy", "backends", "quotas"]
      }
    ],
    "https://w3id.org/pws/authz-profile": [
      {
        "version": "0.1",
        "url": "https://w3c-ccg.github.io/wallet-attached-storage-spec/authz-profile/",
        "signatureAlgorithms": ["EdDSA"],
        "zcapCryptosuites": ["eddsa-jcs-2022"]
      }
    ],
    "https://w3id.org/pws/encrypted-collections": [
      {
        "version": "0.1",
        "url": "https://w3c-ccg.github.io/wallet-attached-storage-spec/ec/",
        "features": ["blinded-index-query", "governed-history-logs"]
      }
    ]
  },
  "instance": {
    "name": "was-teaching-server",
    "source": "https://github.com/interop-alliance/was-teaching-server"
  }
}

The server above serves the v0.4 and v0.5 route tables together during the transition described in 2.1 Version History and Roadmap.

A client reads the service description before its first structural request to a server and applies these rules:

• A key it does not recognize is ignored.
• A version entry without a version member is ignored.
• For each key, the client uses the highest version it understands.
• If no entry under https://w3id.org/pws names a version the client understands, the server is incompatible and the client MUST stop rather than guess a layout. The same applies to a document that is not valid JSON, or that lacks url or specs.
• If no entry names an authorization profile the client implements (see 5.1 Authorization Profiles), the server is likewise incompatible: the client has no way to sign a request the server would accept.
• A response with no service link means v0.4 (see 8.1 Discovering the Service Description).

How often a client re-reads the document is a client policy. A client that gates a security-relevant behavior on an advertised affordance (for example, publishing only to a host that enforces a verification rule) SHOULD re-check before relying on it again, since a host can stop advertising an affordance it once did.

This specification changes in two ways, and the service description distinguishes them.

Additive change (a new optional endpoint, a new feature token, a new error kind, a new query profile, a new reserved segment) is advertised through the registries in the appendices and through features. A client that does not know the addition keeps working, because unknown tokens are ignored and absent means not supported.

Incompatible change (an existing URL changing meaning, a member changing type, a required behavior being removed) takes a new specification version, and the new version is advertised as a new version entry. A server MAY list the old and the new version together during a transition, and a client picks the newest it understands.

Versions never appear in URL paths. A PWS URL is a capability target and a long-lived identity: it is what a delegation chain is rooted on and what a client stores to find a Resource again. A version segment in the path would bind every delegation chain to a protocol version and would turn every version bump into a re-delegation of every capability. The version lives in the service description, and a layout change keeps the old URLs meaningful for as long as the server lists the old version.

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 Delegation in [PWS-AUTHZ]). This is how the root of trust is initially set up (see 5.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 every space the requester is authorized to see, whatever its type.

• Each entry in items MUST carry the space's id, url, and type. The type value is the same array as the type of the space's Metadata object (see 10.1 Space Metadata Data Model), so a client can tell spaces apart by type without reading each one.

• No query parameter selects which types are listed. The listing depends only on what 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/",
      "type": ["Space"]
    }
  ]
}

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 E.1 Space-level reserved endpoints). It is what 10.2 Read Space operation returns and what 10.3 Update (or Create by Id) Space operation writes; the Space URL itself is the container of the Space's Collections (see 10.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 E. 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.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. A server that records it says so with the created-by feature token (see below).
• 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 9.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 E.1 Space-level reserved endpoints.
• backends (optional) - An array of Backend description objects (see 14.1 Backend Data Model), the backends the Space serves. It is the same listing as GET /space/{space_id}/backends (see 14.2 Space Backends Available), carried on the Metadata object so that a reader learns it without a second request. It is read-only: a server MUST ignore a backends supplied in a request body. A server without pluggable backends (see 14. Backends) omits it.

A server that records createdBy on every Resource, Collection, and Space created under a capability invocation MUST advertise the created-by token in its version entry's features array (see 8.2 Service Description Data Model). A server that advertises created-by MUST record createdBy on each of them. A client MUST NOT assume attribution on a server that does not advertise the token. A client feature that depends on attribution refuses to run on such a server rather than reading an absent createdBy as anonymous.

The Space Metadata object therefore splits in two. Its user-writable members are type and name. Its server-derived members are createdBy, url, linkset, and backends. controller is neither: the creating invocation sets it and only the controller rewrites it. That split is the rule an import honours: restoring an archived Space Metadata object writes type and name, leaves the server-derived members to the server, and does not touch controller (see E.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 10.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 12.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. Updating an existing Space's Metadata object MUST be authorized by a root capability invoked directly by the Space's controller; a delegated capability never authorizes this write, whatever its allowedAction (see #the-container-rule). Creating a Space at this URL follows the create-by-id rule below instead.
• 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 9.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 9.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 10.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.2.1 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: a root capability invoked directly by the space's controller, or a delegated capability whose invocationTarget is exactly this Space's URL and whose allowedAction is exactly ['DELETE'] -- the Space-delete exception to the container rule, see #the-container-rule
• 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 11.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 C. Policy Type Registry) 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.4 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 E.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 11.5 List Collection operation).

Because the meta segment occupies the {resource_id} position, meta is a reserved Resource id (see E. 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 E.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 11.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) - An object naming the requester (an app, service, or agent) this collection was provisioned for. It is named for the ActivityStreams 2.0 generator term (the party that generated an object). It is the client-asserted identity axis of 12.8.1 Writer attribution: writerId and createdBy. It is client-supplied, persisted, and writable by the Space controller on create and on update, in contrast to the server-observed, read-only createdBy. An update that carries generator replaces the whole stored object. An update that omits it keeps the stored value, so a controller can backfill the property onto collections that predate it. The contrast with createdBy 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 rather than the requester's. Only the controller is in a position to name the requester it provisioned the collection for. Every member of generator is an assertion by the controller, not a server-verified fact. A server MUST NOT verify, compute, or default any member, and MUST NOT use any member as an input to authorization. A present generator that is not an object, that lacks id, or that carries a member not defined below is an invalid-request-body error. Its members:

  • id (required when generator is present) - The did of the requester. A server MAY separately record that this did has been observed invoking a delegated capability on the collection. That is 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 id as exactly a controller assertion. An empty or non-did-shaped value is an invalid-request-body error.
  • origin (optional) - The Web origin (its ASCII serialization, e.g. https://app.example.com) the id did was bound to when the collection was provisioned. It is present when the requester was bound to a Web origin. A requester with no browser-attested origin (a mobile app, a server-side service, a command-line agent) has none to record. A provisioning exchange in which the user's agent authenticates a 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 id preserves that fact, and gives a reader a human-readable attribution label without further lookups. 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.
  • url (optional) - The requester's canonical URL, when the provisioning exchange identified the requester by URL rather than by origin alone. Several applications may share one origin, and the origin cannot tell them apart. The URL serves as the same attribution label without further lookups, one level finer than origin. When url is present, origin MUST be present too. The value MUST be an absolute URL with the http or https scheme, its origin MUST equal origin, and it MUST NOT carry a query or a fragment. A value that fails any of these is an invalid-request-body error.
  • name (optional) - A human-readable display label for the requester. It lets a reader show the requester by name without further lookups. Like every other member it is the controller's assertion, and a reader MUST NOT treat it as the requester's verified identity. A present value that is not a non-empty string is an invalid-request-body error.

• 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 11.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-PWS 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 F. 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 F. 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 F. Encryption Scheme Registry. On the edv scheme, the descriptor MAY additionally carry the key-epoch public references, currentEpoch and epochs (see F.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 F.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 [PWS-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 server whose PWS-EC version entry advertises governed-history-logs (see 8.2 Service Description Data Model), 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 11.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 G. 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 F.4.2 The blinding-key member), carries in each envelope's indexed member, and queries through the blinded-index profile (see G.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 12.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 G.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 12.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 10.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 F.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 10.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 E.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 12.8.1 Writer attribution: writerId and createdBy does not apply at this level.

On a Collection that declares an encryption descriptor (see F. 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 [PWS-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": {
    "id": "did:key:z6MkfriqYRX3JBqzsbVbKuBUxDR2nsjLTu6AbrxJZAmFmXWb",
    "origin": "https://app.example.com",
    "url": "https://app.example.com/notes/",
    "name": "Notes"
  },
  "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 11.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 11.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 11.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 E.1 Space-level reserved endpoints.

• Requires appropriate authorization: a root capability invoked directly by the space's controller. Exception: a delegated capability MAY authorize this write when the invoked capability's invocationTarget is the Space's own canonical (trailing-slash) URL, rather than the Collection container URL, the Collection Metadata URL, or a Resource URL -- the Collection-metadata exception to the container rule, see #the-container-rule.

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 11.7 Collection Governing History Log). An update that omits plaintext leaves the stored member untouched (see its member definition), and so does an update that omits generator. 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 11.1 Collection Metadata Data Model is the first governed member, under the resource log profile of [PWS-EC]; see 11.7.6 The first governed member: encryption.

Support is OPTIONAL and discoverable. A server that implements the sub-resource advertises governed-history-logs in its PWS-EC version entry's features array (see 8.2 Service Description Data Model). A server without the affordance 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 E.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 (11.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 12.8 Resource Metadata Data Model), and the stored bytes are returned verbatim on reads (see 12.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 11.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 11.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 11.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 12.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 12.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 12.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 12.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 E.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 E.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 11.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 12.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 12.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 11.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 12.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 was last written. A write of the user-writable metadata does not change it (see 12.10 Update Resource Metadata Operation).
• 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 12.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. A server that records it says so with the created-by feature token (see 10.1 Space Metadata Data Model).

This metadata model does not mandate a stored etag / version property as such; a Resource's version is always exposed as an HTTP ETag validator, per 7.2 Conditional Requests.

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 12.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 F.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 content (see 12.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, 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. Every content write or delete either declares the writer's own label or clears the stored one. One that declares no Writer-Id clears the stored value, since attribution to a bygone writer is worse than no attribution at all. An Update Resource Metadata request does not change the label, because the label describes the content write, not the metadata write.

On a Collection that declares an encryption descriptor (see F. 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, 11.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).

One other top-level member is also writable. 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 F.4 Key Epochs).

The Resource's writerId label is not writable here. It names the writer of the Resource's content, so this operation leaves the stored label as it is (see 12.8.1 Writer attribution: writerId and createdBy).

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

This operation writes the Metadata object only. It does not change the Resource's stored representation, so a server MUST NOT change the Resource's updatedAt or the ETag validator of the Resource itself in response to it. The Metadata object's own ETag changes with each such write.

Unlike the 12.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

The space linkset resource (one of the E.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://w3id.org/pws#policy) - A link to the /space/{space_id}/policy resource, which contains a set of links to access control policy documents.
• backends-available (https://w3id.org/pws#backends-available) - A link to the /space/{space_id}/backends "Backends Available" resource.
• quotas relation (https://w3id.org/pws#quotas) - A link to the /space/{space_id}/quotas per-backend storage quota report (see 15. Quotas).
• service relation ([RFC5023]) - A link to the service description (see 8.1 Discovering the Service Description).
• /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://w3id.org/pws#policy": [
        {
          "href": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/policy",
          "type": "application/json"
        }
      ],
      "https://w3id.org/pws#backends-available": [
        {
          "href": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/backends",
          "type": "application/json"
        }
      ],
      "https://w3id.org/pws#quotas": [
        {
          "href": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/quotas",
          "type": "application/json"
        }
      ],
      "service": [
        {
          "href": "https://example.com/service",
          "type": "application/json"
        }
      ]
    }
  ]
}

The collection linkset resource (one of the E.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://w3id.org/pws#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://w3id.org/pws#backend) - A link to the detailed /space/{space_id}/{collection_id}/backend "Backend Selected for this collection" resource.
• quota relation (https://w3id.org/pws#quota) - A link to the /space/{space_id}/{collection_id}/quota storage quota report for this collection (see 15. Quotas).
• service relation ([RFC5023]) - A link to the service description (see 8.1 Discovering the Service Description).
• /space/{space_id}/{collection_id}/query - (Optional) Query operations within a collection, discriminated by a request-body profile (see G. 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://w3id.org/pws#policy": [
        {
          "href": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/messages/policy",
          "type": "application/json"
        }
      ],
      "https://w3id.org/pws#backend": [
        {
          "href": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/messages/backend",
          "type": "application/json"
        }
      ],
      "https://w3id.org/pws#quota": [
        {
          "href": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/messages/quota",
          "type": "application/json"
        }
      ],
      "service": [
        {
          "href": "https://example.com/service",
          "type": "application/json"
        }
      ]
    }
  ]
}

A Backend description object advertises a backend's identity, who operates it, and its persistence, so that clients can select a suitable backend for each Collection (and so that storage management UIs can present meaningful choices to users). Quota constraints on a backend are reported separately, in the Quota report (see 15. Quotas).

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

Note that client-side encryption is deliberately not a backend property: 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 property of the backend. Concretely, this signal is the Collection's optional encryption descriptor (see 11.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.

Every backend on which a Collection may be created honors the conditional writes of 7.2 Conditional Requests; this holds regardless of what persistence primitives the underlying storage engine offers, since the server mediates every write.

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",
    "persistence": "durable"
  },
  {
    "id": "dropbox",
    "name": "Dropbox",
    "managedBy": "external",
    "persistence": "durable"
  },
  {
    "id": "edv",
    "name": "Encrypted Data Vault",
    "managedBy": "server",
    "persistence": "durable"
  }
]

Each collection has an optional backend property that is set during its creation (see 11.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 uppercase HTTP method names (GET, POST, PUT, DELETE, the action vocabulary of [PWS-AUTHZ]) 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 H. 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.