链接式 Web 存储协议 1.0

LWS 协议定义了标准交互，某一方可通过这些交互向某些 代理提供某些资源。

• 被服务资源 - (可用资源？已发布 资源？) (UCS 中未 定义) 由服务公开的网络可访问实体，可使用本文档中定义的协议进行交互、 检索或操纵。
• 请求代理 - (UCS 中的实体) 发起请求以与可服务资源交互的实体 （例如客户端、用户或进程）。

资源管理者可以将被服务资源 保持为私有，可以使其对任何人公开可用，或者可以将其可见性限制到一组受约束的 请求代理。

• 身份验证 - 验证执行请求的代理身份的过程。
• 授权 - 确定代理是否有权访问特定 资源或执行一组操作之一的过程。
• 资源 管理者 - (UCS 中的控制者) 有权控制对被服务资源的访问的代理。

除标记为非规范性的章节外，本规范中的所有创作指南、图表、示例和注释均为非规范性内容。 本规范中的其他所有内容均为规范性内容。

本文档中的关键词 MAY、MUST、MUST NOT、OPTIONAL、RECOMMENDED、REQUIRED、SHOULD 和 SHOULD NOT 应按 BCP 14 [RFC2119] [RFC8174] 中的描述解释，且仅当它们像这里所示以全 大写形式出现时才如此解释。

LWS 服务器是一个 HTTP 服务器 [rfc9112]，它遵守 本规范中所有相关的“MUST”陈述。具体而言， 必须遵守本文档9. 操作中的相关规范性“MUST”陈述。

LWS 客户端是一个 HTTP 客户端 [rfc9112]，它遵守本规范中所有相关的“MUST”陈述。具体而言，必须遵守本文档9. 操作中的相关规范性 “MUST”陈述。

以下图表是与平台无关的模型， 用于指导实现。

本节描述的数据模型概述了身份验证凭证的任何 具体序列化所需满足的要求。

身份验证凭证MUST 包含关于主体的防篡改声明，包括：

• 主体 REQUIRED — 最终用户的标识符。此项 MUST 是 URI。
• 颁发者 REQUIRED — 颁发身份验证凭证的实体的标识符。此项 MUST 是 URI。
• 客户端 REQUIRED — 客户端应用程序的标识符。此项 SHOULD 是 URI。
• 受众 限制 RECOMMENDED — 一组值， SHOULD 包含一个授权服务器标识符。

对身份验证凭证的验证需要凭证的 验证者和颁发者之间存在信任关系。此信任关系MAY 通过 带外机制建立。用于在验证者和颁发者之间建立信任的任何其他机制 均在特定的身份验证套件中概述。

身份验证凭证MUST 被签名。RECOMMENDED 使用非对称密码学 进行签名。

每个身份验证套件MUST 关联一个令牌类型 URI。身份验证套件SHOULD 使用 IANA “OAuth URI”注册表中定义的 URI。

LWS 授权中的角色与 OAuth 2.0 第 1.1 节 [RFC6749] 中定义的角色相同： 资源所有者、 资源服务器、 客户端（在本规范中称为授权客户端，以 避免歧义），以及 授权服务器。 存储服务器是一种同时符合 LWS 存储规范的资源服务器。

本规范描述了客户端与授权服务器之间的交互，以及 客户端与合规存储服务器之间的交互。

授权服务器与存储服务器之间的交互不在本 规范范围内。 授权服务器可以与存储服务器是同一服务器，也可以是单独的实体。

HTTP/2 401 Unauthorized
Link: <https://storage.example/storage_1>; rel="https://www.w3.org/ns/lws#storage"
WWW-Authenticate: Bearer as_uri="https://authorization.example",
                realm="https://storage.example/storage_1",
                error="invalid_token"

{
    "issuer": "https://authorization.example",
    "grant_types_supported": [
        "urn:ietf:params:oauth:grant-type:token-exchange"],
    "token_endpoint": "https://authorization.example/token",
    "jwks_uri": "https://authorization.example/jwks",
    "claims_supported": [
        "sub",
        "iss",
        "client_id",
        "aud"],
    "response_types_supported": [
        "token"],
    "subject_token_types_supported": [
        "urn:ietf:params:oauth:token-type:jwt",
        "urn:ietf:params:oauth:token-type:id-token"]
}

POST /token HTTP/1.1
Host: authorization.example
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange
&resource=https%3A%2F%2Fstorage.example%2Fstorage_1
&subject_token=eyJ0eXAiOiJhcytqd3QiLCJhbGciO...fiK51VwhsxJ-siBMR-YFiA
&subject_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Aid_token

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

{
    "access_token":"eyJ0eXAiOiJhcytqd3QiLCJhbGciOiJFUzI1NiIs...DeWt4QuZXso",
    "token_type":"Bearer",
    "expires_in":3600
}

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error":"invalid_request"
}

{
  "kid": "ec51c6b2",
  "kty": "EC",
  "alg": "ES256",
  "crv": "P-256",
  "typ": "at+jwt"
}
.
{
  "sub": "https://id.example/agent",
  "iss": "https://authorization.example",
  "client_id": "https://app.example/id",
  "aud": "https://storage.example",
  "exp": 1735686300,
  "iat": 1735686000,
  "jti": "550e8400-e29b-41d4-a716-446655440000"
}
.
signature

Authorization: Bearer eyJ0eXAiOiJhcytqd3QiLCJhbGciOiJFUzI1NiIs...DeWt4QuZXso

存储描述资源提供 客户端在与存储交互时可使用的信息，包括能力和 服务端点的描述。

{
  "@context": [
    "https://www.w3.org/ns/cid/v1",
    "https://www.w3.org/ns/lws/v1"
  ],
  "id": "https://storage.example/",
  "type": "Storage",
  "service": [{
    "type": "StorageRoot",
    "serviceEndpoint": "https://storage.example/root/"
  }]
}

{
  "@context": [
    "https://www.w3.org/ns/cid/v1",
    "https://www.w3.org/ns/lws/v1"
  ],
  "id": "https://storage.example/",
  "type": "Storage",
  "capability": [{
    "type": "https://feature.example/PatchSupport",
    "format": {
      "text/turtle": ["application/sparql-update"],
      "application/n-triples": ["application/sparql-update"],
      "application/linkset+json": ["application/merge-patch+json", "application/json-patch+json"]
    }
  }, {
    "type": "https://feature.example/ResumableUploads"
  }, {
    "type": "https://feature.example/ContentNegotiation",
    "source": "application/ld+json",
    "target": ["text/turtle", "application/n-triples"]
  }, {
    "type": "https://feature.example/ContentNegotiation",
    "source": "image/jpeg",
    "target": ["image/png"]
  }],
  "service": [{
    "type": "StorageRoot",
    "serviceEndpoint": "https://storage.example/root/"
  }, {
    "type": "NotificationService",
    "serviceEndpoint": "https://storage.example/notification/api",
    "subscriptionType": ["WebhookSubscription"]
  }, {
    "type": "TypeIndexService",
    "serviceEndpoint": "https://storage.example/types/index"
  }, {
    "type": "TypeSearchService",
    "serviceEndpoint": "https://storage.example/types/search"
  }, {
    "type": "DataSharingService",
    "serviceEndpoint": "https://storage.example/sharing/api"
  }]
}

关联 Web 存储将资源组织到容器中。容器是一种 专门的资源，它保存对其他资源的引用，这些资源称为其成员。容器充当 组织单元，类似于目录或集合，使客户端能够对资源进行分组、发现 和导航。容器维护对其成员资源的引用， 这些资源可能同时包括非容器资源和其他容器资源，从而能够形成 层次结构。通常，除了元数据或其成员的枚举之外，容器 几乎不包含固有内容；其主要作用是聚合和组织 下级资源。存储系统的根被指定为容器，充当 没有上级父项的最高层组织单元。容器表示的结构在8.1 容器 表示中定义；其媒体类型和分页要求在12. LWS 媒体类型中定义。 存储可以充当根容器，从而允许直接写入。

每个 LWS 存储都有一个存储 根，它充当顶级组织单元。存储根没有父项，并充当存储 层次结构的入口点。

LWS 中的资源被分类为以下两类之一：

• 容器 — 包含其他 资源的资源。
• 数据资源 — 承载数据的资源 （例如文档、图像或结构化数据文件）。

资源与其父容器之间的包含关系通过 rel="up" 链接 关系表示。对于任何 非根资源上的 GET 和 HEAD 请求，服务器MUST 在响应中包含一个 Link 标头，其中 rel="up" 指向父容器。

Link: </alice/notes/>; rel="up"

容器的成员在其表示中使用 items 属性列出。服务器管理此列表；客户端不能直接修改它。成员关系 变更作为资源创建和删除的副作用发生。

服务器MUST 始终维护包含关系完整性：

• 创建：在容器中创建新资源时， 服务器MUST 以原子方式将该资源添加到容器的 items 列表中。
• 删除：删除资源时，服务器MUST 以原子方式将其从父容器的 items 列表中移除。 删除容器要求该容器为空， 除非明确请求递归删除。
• 无孤儿资源：每个非根资源MUST 都能从 存储根通过包含关系 层级到达。
• 无环：容器MUST NOT 直接或 间接包含自身。

资源由 URI 标识。资源的 URI 与其在包含关系层次结构中的位置无关。服务器在创建资源时分配 URI， 并且可以采用客户端提示，但客户端不应该假定 URI 结构反映了包含关系。

包含关系通过元数据表示 （rel="up" 链接和容器 表示中的 items 属性），而不是通过 URI 路径结构表示。这种分离允许服务器在 URI 分配方面具有灵活性，同时维护一个定义良好的组织模型。

如果客户端对容器具有读取访问权限，则容器 表示MUST 包含该容器中客户端有权访问的所有资源的标识符。它MAY 也包含该容器中客户端无权访问的资源的标识符。

客户端读取容器列表的能力，并不意味着其可访问所包含的 资源本身，反之亦然。

当客户端检索容器时，服务器会返回一个结构化的容器表示，用于描述该容器及其内容。本节定义容器表示的必需和 可选属性。

{
  "@context": "https://www.w3.org/ns/lws/v1",
  "id": "/alice/notes/",
  "type": "Container",
  "totalItems": 2,
  "items": [
    {
      "type": "DataResource",
      "id": "/alice/notes/shoppinglist.txt",
      "format": "text/plain",
      "size": 47,
      "modified": "2025-11-24T12:00:00Z"
    },
    {
      "type": ["DataResource", "http://example.org/customType"],
      "id": "/alice/notes/todo.json",
      "format": "application/json",
      "size": 2048,
      "modified": "2025-11-24T13:00:00Z"
    }
  ]
}

本节定义了将元数据与LWS 资源关联的模型。 LWS 元数据系统基于 Web 链接 [RFC8288] 的原则，该原则 允许服务器使用类型化链接描述资源之间的关系。元数据增强了 可发现性，支持自描述 API，并与资源操作及容器层次结构保持一致。

元数据模型 LWS 中的所有元数据都表示为一组源自某个资源（链接上下文）的类型化链接。 每个链接包括：

• 链接目标：标识相关资源的 URI。
• 关系类型：定义关系性质的字符串。
• 可选的目标属性：进一步描述链接或目标 资源的附加键值对。

元数据区分资源及其表示，从而在适用时允许使用多种媒体类型。 对于数据资源，元数据包括多个表示，每个表示都带有 format 和可选的 sizeInBytes。对于容器和数据资源，我们将指向 其父容器资源的链接视为该资源元数据的一部分。

链接集资源 对于存储中的每个资源，服务器必须按照 [RFC9264] 将元数据链接 作为独立资源提供。

• 发现：资源的链接集可通过带有 rel="linkset" 关系的 Link 标头发现。
• 媒体类型：链接集资源必须 以 application/linkset+json 的形式提供。
• 完整性：'linkset' 链接必须指向由服务器管理的资源。 对链接集的更新必须与相关资源操作以原子方式进行， 以保持一致性。

发现元数据 客户端主要通过 GET 或 HEAD 请求响应中的 Link 标头发现元数据。

• 存储：服务器必须在相关响应中包含带有 rel="https://www.w3.org/ns/lws#storage" 的 Link 标头。
• 包含关系：对于任何非根资源，服务器必须包含带有 rel="up" 且指向父容器的 Link 标头。
• 偏好：客户端可以将 Prefer 标头 [RFC7240] 与 URI https://www.w3.org/ns/lws#PreferLinkRelations 一起使用，以包含或省略特定关系。

元数据类型

可修改性注意事项 核心元数据可以由客户端修改。为确保互操作性，服务器 必须使用标准 HTTP 标头公布其能力：

1. 方法发现：服务器必须通过 Allow 标头公布对链接集资源执行 GET 和 PATCH 操作的支持。

2. 补丁格式发现：服务器必须通过 Accept-Patch 标头公布对 JSON 合并 补丁 [RFC7386] 的支持： Accept-Patch: application/merge-patch+json。

3. 可选方法：服务器可以支持 PUT 或其他补丁格式； 如果支持，则这些方法和格式必须分别包含在 Allow 和 Accept-Patch 标头中。

[!重要] 除非资源标头中公布了对 PUT 或特定补丁格式的支持，否则客户端不应该假定支持它们，并且必须妥善处理 405 方法 不允许或 415 不支持的媒体类型响应。

管理元数据 元数据通过与资源关联的链接集资源 URI 进行交互来管理。服务器必须支持更新的并发控制。

• 部分更新（PATCH）：这是管理元数据的主要机制。服务器必须支持使用 application/merge-patch+json 的 PATCH。

• 替换（PUT）：如果 Allow 标头中公布了 PUT，客户端可以 替换整个链接集。如果服务器不支持 PUT，则它必须 以 405 方法不允许拒绝该请求。

• 限制：服务器可以限制对特定链接（例如 up 或 items）的修改，以维持系统完整性。

• 生命周期：元数据的生命周期与所描述的资源绑定；删除资源必须导致自动移除其关联链接集资源中的元数据。

创建资源操作将一个新的被服务资源添加到现有容器中。此 操作同时处理数据资源和子容器的创建。

输入：

• 目标容器：将在其中创建新资源的容器的标识符。
• 身份提示：新资源标识符的可选建议。服务器 可以使用此提示，但不是必须使用。
• 内容：新资源的初始内容和类型。

行为：

• 身份生成：服务器确定新 资源的最终标识符（URI）。如果提供了身份提示，服务器会尝试 纳入该提示，同时确保其在容器内唯一且有效。如果未提供提示， 服务器会生成唯一标识符。
• 容器成员关系更新：服务器以原子方式将新资源添加到目标 容器的成员列表中。
• 元数据初始化：服务器为新 资源初始化系统元数据。如果该资源有关联的元数据资源，它也会被 初始化。

可能的响应：

• 已创建：操作成功。服务器返回新创建资源的最终 标识符。
• 目标未找到：指定的目标容器不存在。
• 不允许：客户端身份已知，但其无权在此容器中创建资源。
• 未知请求者：服务器不识别客户端的身份，需要 身份验证。
• 冲突：具有生成标识符的资源已存在，或者存在 其他状态冲突。
• 未知错误：发生了意外的内部错误。

使用 POST 向目标容器 URI 创建新资源，由服务器分配 最终标识符。客户端可以通过在 POST 请求中包含一个或多个 Link 标头，按照 [RFC8288] 中 Web 链接的语法，为新资源提供初始的用户管理元数据。 服务器管理的元数据必须 由服务器在创建时自动生成，并且不得 被客户端提供的链接覆盖。

成功后，服务器必须返回 201 状态码，并在 Location 标头中提供新 URI。服务器必须包含用于 关键服务器管理元数据的 Link 标头，其中包括指向父容器的链接 (rel="up")，以及指向所创建资源专用链接集资源的链接 (rel="linkset"; type="application/linkset+json")。其他链接应该包括 rel="type"（指示 https://www.w3.org/ns/lws#Container 或 https://www.w3.org/ns/lws#DataResource）。响应主体可以为空，也可以 包含资源的最小表示。所有元数据的创建和链接必须与资源创建以原子方式进行，以保持一致性。

POST（向容器 URI） – 使用服务器分配的名称创建： 使用 POST 在现有容器内添加新资源。服务器为资源分配 标识符。客户端按如下方式指示要创建的资源类型：

• 要创建容器，客户端必须包含一个带有 rel="type" 的 Link 标头， 使其指向容器类型： Link: <https://www.w3.org/ns/lws#Container>; rel="type"。
• 要创建数据资源，客户端应在请求主体中包含 资源内容，并使用适当的 Content-Type 标头。

示例（使用 POST 创建新的数据资源）：

POST /alice/notes/ HTTP/1.1
Host: example.com
Authorization: Bearer <token>
Content-Type: text/plain
Content-Length: 47

milk
eggs
bread
butter
apples
orange juice

在此示例中，客户端正在向容器 /alice/notes/ 发送 POST 请求。它 提供 text/plain 内容（一份购物清单），并为新资源建议名称 shoppinglist.txt。如果 /alice/notes/ 存在且客户端 已获得授权，服务器将创建新的数据资源，并将其添加到该容器的成员中。

示例（对 POST 的响应 — 数据资源）：

HTTP/1.1 201 Created
Location: /alice/notes/shoppinglist.txt
Content-Type: text/plain; charset=UTF-8
Link: </alice/notes/shoppinglist.txt.meta>; rel="linkset"; type="application/linkset+json"
Link: </alice/notes/>; rel="up"
Link: <https://www.w3.org/ns/lws#DataResource>; rel="type"
Content-Length: 0

成功后，返回 201 Created，并在 Location 标头中提供新 URI。响应主体可以 为空，也可以是最小表示。 如果目标容器 /alice/notes/ 不存在，服务器 必须返回 404 错误状态，除非其他状态码更为适当。

创建容器：要创建新的容器，客户端使用 POST 向现有父容器发送请求，并使用 Link 标头指示 容器类型。例如：

POST /alice/ HTTP/1.1
Host: example.com
Authorization: Bearer <token>
Content-Length: 0
Link: <https://www.w3.org/ns/lws#Container>; rel="type"

示例（对 POST 的响应 — 容器）：

HTTP/1.1 201 Created
Location: /alice/notes/
Link: </alice/notes/.meta>; rel="linkset"; type="application/linkset+json"
Link: </alice/>; rel="up"
Link: <https://www.w3.org/ns/lws#Container>; rel="type"
Content-Length: 0

这将在 /alice/notes/ 创建新的容器，其中由服务器生成的 元数据包括值为 https://www.w3.org/ns/lws#Container 的 rel="type"。

有关创建操作的其他说明（HTTP 绑定）：

• POST 不是幂等的。重复执行可能会创建重复资源；客户端应该 避免无意的重试，或使用唯一标识符/检查来防止这种情况。
• 元数据更新是原子的；服务器必须确保链接集资源在返回成功之前已创建并填充 服务器管理的必需字段。
• 为便于发现，服务器应该在 401 响应中包含带有 rel="https://www.w3.org/ns/lws#storage" 的 Link 标头，以引导没有 硬编码 URI 的客户端。

管理和检索元数据（与创建相关）： 尽管元数据主要通过读取操作检索，但它是在创建过程中生成的。客户端可以 在创建后立即对新资源 URI 使用 GET 或 HEAD 来检索元数据。客户端可以使用 Prefer 标头请求包含特定的元数据链接（通过关系类型）和 属性。

检索现有资源的表示，或容器的列表。

• 输入：目标标识符和可选参数。
• 行为：
  • 对于非容器资源，服务器返回资源内容。
  • 对于容器，服务器返回成员 资源列表，该列表MAY 基于授权进行过滤。列表必须包含 每个成员的核心元数据。
• 结果：所请求的表示或失败通知。

读取资源操作通过 HTTP GET 请求（以及用于仅获取标头请求的 HEAD） 请求资源表示。行为取决于目标 URL 是容器还是非容器资源（数据资源）。服务器MUST 通过元数据区分资源类型。所有响应MUST 与 第 8.1 节定义的元数据集成，包括用于关键关系的 Link 标头，例如 rel="linkset"、rel="up" 和 rel="type"。服务器MUST 确保读取期间资源状态与其元数据之间的原子性。

GET（非容器资源） – 检索资源内容： 向资源 URI 发送 GET 以获取完整内容（如果已获授权）。以 200 OK 响应，正文包含 数据，Content-Type 与所存储的媒体类型匹配。服务器MUST 按照 [RFC7233] 支持 范围请求，以便部分检索。响应MUST 包含 ETag 标头，用于并发控制和 缓存。

示例（GET 一个文件）：

GET /alice/notes/shoppinglist.txt HTTP/1.1
Authorization: Bearer <token>
Accept: text/plain

这会请求 /alice/notes/shoppinglist.txt 的内容，表明客户端希望 以文本形式获取它。假定资源存在、是文本，并且客户端有权访问：

HTTP/1.1 200 OK
Content-Type: text/plain; charset=UTF-8
Content-Length: 34
ETag: "abc123456"
Link: </alice/notes/shoppinglist.txt.meta>; rel="linkset"; type="application/linkset+json"
Link: </alice/notes/>; rel="up"
Link: <https://www.w3.org/ns/lws#DataResource>; rel="type"

milk
cheese
bread
guacamole
soda
chocolate bars
hash
eggs

服务器返回了文本内容（共 34 字节，如 Content-Length 所示）。 内容正是该文件中存储的数据。ETag: "abc123456" 是用于缓存或并发目的的版本 标识符。响应包含用于元数据 可发现性的 Link 标头，并带有 up 和 type 等强制字段。

GET（容器资源） – 列出容器内容： 当目标 URI 对应于容器（通过元数据类型确定）时，GET 请求返回该 容器成员的列表。响应正文是 容器表示，如容器表示一节所定义，使用 LWS 容器媒体 类型。该列表包括每个成员的元数据：资源标识符（MUST）、类型（MUST）、媒体类型（对于 DataResources，MUST）、大小（SHOULD）以及 修改时间戳（SHOULD）。

示例（GET 一个容器）：

GET /alice/notes/ HTTP/1.1
Authorization: Bearer <token>
Accept: application/lws+json

假定容器存在且客户端有权访问：

HTTP/1.1 200 OK
Content-Type: application/lws+json
ETag: "container-etag-789"
Link: </alice/notes/.meta>; rel="linkset"; type="application/linkset+json"
Link: </alice/>; rel="up"
Link: <https://www.w3.org/ns/lws#Container>; rel="type"

{
  "@context": "https://www.w3.org/ns/lws/v1",
  "id": "/alice/notes/",
  "type": "Container",
  "totalItems": 2,
  "items": [
    {
      "type": "DataResource",
      "id": "/alice/notes/shoppinglist.txt",
      "format": "text/plain",
      "size": 47,
      "modified": "2025-11-24T12:00:00Z"
    },
    {
      "type": ["DataResource", "http://example.org/customType"],
      "id": "/alice/notes/todo.json",
      "format": "application/json",
      "size": 2048,
      "modified": "2025-11-24T13:00:00Z"
    }
  ]
}

在此示例中，/alice/notes/ 是一个容器。响应使用带有 LWS 上下文的 JSON-LD，列出带有必需元数据的成员。每个条目都包含其 type、 id、format、size 和 modified 时间戳作为扁平 属性。

在所有情况下，服务器MUST 在响应 标头中包含以下元数据：ETag（表示列表版本，它会在成员关系修改时变化），以及 Link 标头，其中 rel="type" 表明它是一个容器，并包含 rel="linkset" 和 rel="up"。

HEAD（任何资源或容器） – 仅标头/元数据： LWS 服务器MUST 对容器和非容器均支持 HEAD [RFC9110]， 返回与 GET 相同的标头（包括 ETag、Content-Type、用于元数据的 Link），但没有正文。这可以在不传输内容的情况下检索 元数据。

缓存和条件请求：LWS 利用 HTTP 缓存语义。服务器MUST 支持通过 If-None-Match（使用 ETag）或 If-Modified-Since 标头进行条件请求。如果资源或容器列表未更改，则响应 304 Not Modified，以避免冗余传输。所有 GET/HEAD 响应中MUST 提供 ETag， 用于并发和缓存支持。

可发现性和授权：为了增强可发现性，服务器SHOULD 在 401 Unauthorized 响应上包含带有 参数的 WWW-Authenticate 标头，以便在没有硬编码 URI 的情况下引导客户端。元数据链接SHOULD 在适用时包含。

通过完整替换或部分补丁修改现有 [served resource] 的状态。

• 输入：目标标识符、新内容和可选的并发约束。
• 行为：服务器以原子方式应用更改。如果提供了并发约束， 且资源自请求者上次读取后已被修改，则拒绝更新。
• 结果：更新确认或冲突通知。

更新资源通过 PUT 请求（替换整个资源）或 PATCH 请求（应用 部分修改）修改现有被服务 资源的内容。客户端必须对资源 URL 拥有写访问权限才能执行这些 操作。 注：本节描述更新资源的主要内容。要更新其元数据，请见第 9.3.2 节。 LWS 服务器MUST 将资源 URI 上的 PUT 和 PATCH 请求处理为 仅对资源内容的修改，默认情况下不影响关联的linkset 资源。为了可选择地在单个原子操作中同时更新内容和 元数据，客户端MAY 在对资源 URI 的 PUT/PATCH 请求中包含 Link 标头，并指定偏好 'Prefer: set-linkset'（如 RFC 7240 中所定义）。在这种情况下，服务器MUST 将提供的 Link 标头解释为 对 linkset 的替换（对于 PUT）或部分更新（对于 PATCH），并同时应用 内容更改。此行为对服务器而言是OPTIONAL，但如果支持，MUST 通过 Prefer 标头显式调用，以防止无意 覆盖元数据。不支持组合更新的服务器MUST 忽略 该偏好或以 501 Not Implemented 响应。

PUT（替换完整资源） – 向资源 URI 发送 PUT，并在 正文中包含新的完整内容和匹配的 Content-Type（通常与现有类型一致）。PUT 对现有 资源是幂等的。为安全起见，包含带有当前 ETag 的 If-Match（依据第 7.3 节并发）；不匹配会产生 412 Precondition Failed 或 409 Conflict。如果没有检查，更新是无条件的，但可能覆盖 并发更改。如果服务器支持资源的 Etags，它MUST 以 428 Precondition Required 响应拒绝缺少 If-Match 标头的无条件 PUT 请求。

示例（PUT 更新资源）：

PUT /alice/personalinfo.json HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json
If-Match: "abc123456"
{
"name": "Alice",
"age": 30,
"city": "New London",
"state": "Connecticut"
}

在此示例中，客户端正在更新 /alice/personalinfo.json 处的现有 JSON 资源。它 包含一个 If-Match 标头，其中带有它从早先 GET 或 HEAD 请求获得的 ETag "abc123456"。 服务器会将其与当前 ETag 比较；如果匹配，就继续用 所提供的 JSON 替换内容。如果不匹配，服务器会拒绝更新（因为该资源在此期间 已被其他人更改）。 成功响应：如果更新成功，服务器可以用 200 OK 响应，并可能包含 更新后的表示或某些确认信息（例如新内容或其中一部分）。或者， 服务器可以用 204 No Content 响应，表示成功但无正文（如果无需传达更多 信息，这尤其常见）。无论哪种情况，服务器SHOULD 包含新的 ETag 来表示新版本，如果返回正文，也可以包含 Content-Type。例如：

HTTP/1.1 204 No Content
ETag: "def789012"

这会告诉客户端更新已完成，并提供新的 ETag。如果服务器选择 返回更新后的内容，它可能使用 200 OK 并在正文中包含 JSON，同时 带有标头。

• 错误响应：如果 If-Match 不匹配（并发 修改），服务器可以返回 412 Precondition Failed（表示 前提条件标头失败）或 409 Conflict —— 我们之前的抽象描述使用 Conflict 表示并发问题，而 409 是该场景的自然映射。如果资源 不存在，则旨在更新的 PUT 会导致 404 Not Found（除非意图是 创建，但通常客户端只有在确定自己正在做什么时才使用 PUT 创建， 或者将其作为没有 If-Match 的 upsert 使用）。如果客户端未获授权， 则为 403 Forbidden（或者在未提供有效凭据时为 401 Unauthorized）。如果 请求载荷无效，则为 400 Bad Request。

PATCH（部分更新） – HTTP PATCH 方法 [RFC5789] 允许客户端指定对资源的部分修改，而不是发送完整的新 内容。当资源很大且只有一小部分发生变化时，发送整个内容效率较低， 或者在并发编辑中希望应用特定更改时，这很有用。LWS 服务器MUST 至少支持 [RFC7386] 中定义的 JSON Merge Patch（application/merge-patch+json）。

更新资源元数据（对 Linkset 使用 HTTP PUT / PATCH） 资源的元数据通过修改其对应的linkset 资源来更新， 该资源通过带有 rel="linkset" 的 Link 标头发现。 完整替换（PUT）：对linkset 资源 URI 发送 PUT 请求，并在正文中包含完整 linkset 文档，会替换该资源的所有元数据。 部分更新（PATCH）：对linkset 资源 URI 发送 PATCH 请求，会添加、移除或 修改特定链接。

元数据的并发控制 因为资源的元数据可能由多个参与者修改，防止并发覆盖至关重要。 为确保数据完整性，LWS 服务器和客户端MUST 为所有 对linkset 资源的 PUT 和 PATCH 操作，实现使用条件请求 [RFC7232] 的乐观并发控制。 服务器职责： 服务器MUST 在其对linkset 资源的 GET 和 HEAD 请求响应中包含 Etag 标头。 在成功对 linkset 执行 PUT 或 PATCH 后，服务器MUST 为修改后的 linkset 生成新的、 唯一 Etag 值，并在响应的 Etag 标头中返回它。 客户端职责： 修改linkset 资源时，客户端MUST 包含一个 If-Match 标头，其中包含它最近收到的该资源 Etag。 处理规则： 如果 If-Match 标头值与 linkset 的当前 Etag 不匹配，服务器MUST 以 412 Precondition Failed 状态码拒绝请求。 如果对 linkset URI 的 PUT 或 PATCH 请求缺少 If-Match 标头，服务器MUST 以 428 Precondition Required 状态码拒绝请求 [RFC6585]。 示例（PUT 替换 linkset）： 客户端首先获取 linkset 并接收其 ETag。

GET /alice/personalinfo.json.meta HTTP/1.1
Authorization: Bearer <token>
Accept: application/linkset+json
HTTP/1.1 200 OK
Content-Type: application/linkset+json
ETag: "meta-v1"
{
  "linkset": [
    {
      "anchor": "/alice/personalinfo.json",
      "describedby": [ { "href": "/schemas/personal-info.json" } ]
    }
  ]
}

客户端现在想要添加许可证。它构造一个新的完整 linkset 文档，并发送带有 If-Match 标头的 PUT 请求。

PUT /alice/personalinfo.json.meta HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/linkset+json
If-Match: "meta-v1"
{
  "linkset": [
    {
      "anchor": "/alice/personalinfo.json",
      "describedby": [ { "href": "/schemas/personal-info.json" } ],
      "license": [ { "href": "https://creativecommons.org/licenses/by/4.0/" } ]
    }
  ]
}

如果成功，服务器以成功响应，并返回新的 ETag。

HTTP/1.1 204 No Content
ETag: "meta-v2"

更新规则摘要 如果你只想更改资源的内容 → 对资源本身执行 PUT/PATCH。 如果你只想更改资源的链接（元数据）→ 对该资源关联的linkset 资源执行 PUT/PATCH。 如果你想同时更改内容和链接 → 对资源本身执行 PUT/PATCH，并包含适当的 Link 标头和 'Prefer: set-linkset'。同时设置默认关闭。

永久移除资源及其关联元数据。

• 输入：目标标识符、可选的递归标志（用于容器），以及可选并发约束。
• 行为：
  • 对于非容器资源，服务器移除内容和元数据，并更新父容器的成员关系。
  • 对于容器，服务器通常要求该容器为空，除非显式请求并支持递归删除。
• 结果：移除确认或失败通知。

删除资源操作使用 HTTP DELETE 方法实现，如上述抽象 操作中所定义。本节指定输入、行为和响应的 HTTP 绑定。

DELETE 请求以要移除的资源或容器的 URI 为目标。客户端MAY 包含带有 ETag 的 If-Match 标头，以进行并发 检查。

删除和包含关系： 删除资源时，服务器MUST 以原子方式将其从其 父容器的 items 列表中移除。父容器的 totalItems 计数SHOULD 相应更新，并且其 ETagMUST 被更新以反映该变更。

对于非容器资源，服务器移除资源内容、其关联元数据（linkset 资源），以及父容器中的包含关系引用。

对于容器资源，服务器默认执行非递归 删除。如果该容器非空且未请求递归，则服务器 MUST 以 409 Conflict 拒绝请求。服务器MAY 支持递归删除正在被删除的容器内的所有包含资源。 客户端MUST 使用 Depth: infinity 标头来请求 递归删除，如 [RFC4918] 中所定义。

成功时，服务器MUST 以 204 No Content 响应。服务器SHOULD 支持条件请求，如 [RFC9110] 中所定义。

如果客户端缺少授权，服务器MUST 返回 403 Forbidden（如果 客户端身份已知但权限不足）或 401 Unauthorized（如果未提供有效 身份验证）。在泄露资源存在性会造成安全风险的情况下， 服务器MAY 改为返回 404 Not Found。

示例（DELETE 非容器资源）：

DELETE /alice/notes/shoppinglist.txt HTTP/1.1
Authorization: Bearer <token>
If-Match: "abc123456"

假定 ETag 匹配且客户端已获授权，服务器会以原子方式删除资源、其元数据， 并将其从父容器 /alice/notes/ 中移除：

HTTP/1.1 204 No Content

示例（DELETE 非空容器且不递归）：

DELETE /alice/notes/ HTTP/1.1
Authorization: Bearer <token>

假定 /alice/notes/ 包含资源，服务器会拒绝删除：

HTTP/1.1 409 Conflict
Content-Type: text/plain

Cannot delete container /alice/notes/ - container is not empty.

示例（如果支持，递归 DELETE 容器）：

DELETE /alice/notes/ HTTP/1.1
Authorization: Bearer <token>
Depth: infinity

假定服务器支持递归且客户端对所有内容都有权限，服务器会以原子方式 删除该容器及其后代：

HTTP/1.1 204 No Content

此表将通用 LWS 响应（来自 第 8 节）映射到 HTTP 状态码和载荷，以保持一致性，并纳入诸如 分页、并发控制、配额约束和元数据集成等特定场景：

存储可以支持通知。支持通知的存储必须 在其存储描述资源的 service 数组中通告一个 type 等于 NotificationService 的服务对象。

该服务对象必须包含一个 serviceEndpoint 属性，其 值 为订阅端点的 URI。该服务对象必须包含一个 subscriptionType 属性，其值为一个字符串数组，其中每个字符串 标识一种受支持的订阅类型。

服务对象上可以存在其他属性。

{
  "@context": ["https://www.w3.org/ns/lws/v1"],
  "id": "https://storage.example/",
  "type": "Storage",
  "service": [{
    "type": "NotificationService",
    "serviceEndpoint": "https://notification.example/subscriptions",
    "subscriptionType": [
      "WebhookSubscription"
    ]
  }]
}

通知表示为一个类型为 Notification 的 JSON-LD 文档。信封携带有关递送 上下文的元数据，并封装一个描述该事件的 Activity Streams 2.0 [ACTIVITYSTREAMS-CORE] [ACTIVITYSTREAMS-VOCABULARY] 活动。

{
  "@context": [
    "https://www.w3.org/ns/lws/v1",
    "https://www.w3.org/ns/activitystreams"
  ],
  "type": "Notification",
  "storage": "https://storage.example/",
  "activity": {
    "id": "ec4dcc48-6581-4232-81c9-584525a98693",
    "type": ["Delete"],
    "object": {
      "id": "https://storage.example/alice/notes/shopping.txt",
      "type": ["DataResource"]
    },
    "origin": "https://storage.example/alice/notes/",
    "published": "2026-03-26T10:30:00Z"
  }
}

{
  "@context": [
    "https://www.w3.org/ns/lws/v1",
    "https://www.w3.org/ns/activitystreams"
  ],
  "type": "Notification",
  "storage": "https://storage.example/",
  "activity": [
    {
      "id": "a1b2c3d4-5678-9abc-def0-1234567890ab",
      "type": ["Create"],
      "object": {
        "id": "https://storage.example/alice/notes/meeting.txt",
        "type": ["DataResource"]
      },
      "target": "https://storage.example/alice/notes/",
      "published": "2026-03-26T10:30:00Z"
    },
    {
      "id": "b2c3d4e5-6789-abcd-ef01-234567890abc",
      "type": ["Update"],
      "object": {
        "id": "https://storage.example/alice/profile",
        "type": ["DataResource"]
      },
      "published": "2026-03-26T10:30:01Z"
    }
  ]
}

为接收通知，订阅者通过 向 NotificationService 的 serviceEndpoint 发送 经过身份验证的 POST 请求来创建订阅。 请求正文必须符合 application/lws+json 媒体类型。

POST /subscriptions HTTP/2
Host: notification.example
Authorization: Bearer <access-token>
Content-Type: application/lws+json

{
  "@context": ["https://www.w3.org/ns/lws/v1"],
  "type": "WebhookSubscription",
  "topic": [
    "https://storage.example/alice/notes/",
    "https://storage.example/alice/profile"
  ],
  "inbox": "https://receiver.example/hooks/lws"
}

存储可以在其存储描述资源中通告对访问请求和 访问授权 的支持。当通告此类支持时，描述访问请求端点的服务 对象的 type 必须等于字符串 AccessRequestService，而描述访问授权端点的服务对象的 type 必须 等于字符串 AccessGrantService。服务 对象应当包含一个 conformsTo 属性，其值为一个 包含一个或多个 URI 的集合，用于标识该端点支持的访问配置文件。还可以包含其他属性：

{
  "@context": [
    "https://www.w3.org/ns/cid/v1",
    "https://www.w3.org/ns/lws/v1"
  ],
  "id": "https://storage.example/",
  "type": "Storage",
  "service": [
    {
      "type": "StorageRoot",
      "serviceEndpoint": "https://storage.example/root/"
    },
    {
      "type": "AccessRequestService",
      "serviceEndpoint": "https://access.example/request/",
      "conformsTo": ["https://www.w3.org/ns/lws#AccessProfile"]
    },
    {
      "type": "AccessGrantService",
      "serviceEndpoint": "https://access.example/grant/",
      "conformsTo": ["https://www.w3.org/ns/lws#AccessProfile"]
    }
  ]
}

访问请求或访问授权是一个数据 对象，用于表达身份和路由属性，以及描述 所请求或获准操作的 access 对象。11.3 访问配置文件中描述了一种使用 ODRL 概念描述访问请求的配置文件。

以下示例展示了一个访问请求。该示例使用 11.4.1 JSON-LD 序列化中定义的 JSON-LD 序列化形式。

{
  "@context": [
    "https://www.w3.org/ns/lws/v1"
  ],
  "type": ["AccessRequest"],
  "inbox": "https://id.example/agent/inbox/",
  "storage": "https://storage.example/",
  "access": [{
    "type": ["AccessPolicy"],
    "action": ["read", "create"],
    "assignee": "https://id.example/agent",
    "target": {
      "type": "StorageResource",
      "value": ["https://storage.example/root/projects/"]
    },
    "constraint": [
      {
        "leftOperand": "purpose",
        "operator": "eq",
        "rightOperand": "https://purpose.example/collaboration"
      },
      {
        "leftOperand": "dateTime",
        "operator": "lteq",
        "rightOperand": "2026-06-09T10:00:00Z"
      }
    ]
  }]
}

以下示例展示了一个访问授权。该示例使用 11.4.1 JSON-LD 序列化中定义的 JSON-LD 序列化形式。

{
  "@context": [
    "https://www.w3.org/ns/lws/v1"
  ],
  "type": ["AccessGrant"],
  "storage": "https://storage.example/",
  "access": [{
    "type": ["AccessPolicy"],
    "action": ["read"],
    "assignee": "https://id.example/agent",
    "target": {
      "type": "StorageResource",
      "value": ["https://storage.example/root/projects/"]
    },
    "constraint": [
      {
        "leftOperand": "purpose",
        "operator": "eq",
        "rightOperand": "https://purpose.example/collaboration"
      },
      {
        "leftOperand": "dateTime",
        "operator": "lteq",
        "rightOperand": "2026-06-09T10:00:00Z"
      }
    ]
  }]
}

访问请求和 访问授权上可以存在其他属性。

{
  "type": ["AccessGrant"]
}

{
  "storage": "https://storage.example/"
}

{
  "inbox": "https://id.example/agent/inbox/"
}

本规范定义了一个基于 ODRL 信息模型和ODRL 词汇表的访问配置文件，该配置文件 由以下 URL 标识： https://www.w3.org/ns/lws#AccessProfile。

{
  "access": [{
    "type": ["AccessPolicy"]
  }]
}

{
  "access": [{
    "action": ["read", "create"]
  }]
}

{
  "access": [{
    "assignee": "https://id.example/agent"
  }]
}

{
  "access": [{
    "target": {
      "type": "StorageResource",
      "value": [
        "https://storage.example/root/2025",
        "https://storage.example/root/2026"
      ]
    }
  }]
}

{
  "access": [{
    "constraint": [
      {
        "leftOperand": "purpose",
        "operator": "isAnyOf",
        "rightOperand": [
          "https://purpose.example/collaboration",
          "https://purpose.example/research"
        ]
      }
    ]
  }]
}

{
  "access": [{
    "constraint": [
      {
        "leftOperand": "client",
        "operator": "eq",
        "rightOperand": "https://app.example/client-id"
      }
    ]
  }]
}

{
  "access": [{
    "constraint": [
      {
        "leftOperand": "format",
        "operator": "isAnyOf",
        "rightOperand": ["image/jpeg", "image/png"]
      }
    ]
  }]
}

Link: <https://www.w3.org/ns/lws#DataResource>; rel="type"
Link: <https://type.example/Playlist>; rel="type"

{
  "access": [{
    "constraint": [
      {
        "leftOperand": "type",
        "operator": "isAnyOf",
        "rightOperand": [
          "https://type.example/Playlist",
          "https://type.example/Song"
        ]
      }
    ]
  }]
}

{
  "access": [{
    "constraint": [
      {
        "leftOperand": "dateTime",
        "operator": "gteq",
        "rightOperand": "2026-03-09T12:00:00Z"
      },
      {
        "leftOperand": "dateTime",
        "operator": "lteq",
        "rightOperand": "2026-06-09T10:00:00Z"
      }
    ]
  }]
}

{
  "access": [{
    "action": ["read"],
    "assignee": "https://id.example/agent",
    "target": {
      "type": "StorageResource",
      "value": ["https://storage.example/root/projects/"]
    },
    "constraint": [
      {
        "leftOperand": "dateTime",
        "operator": "lteq",
        "rightOperand": "2026-06-09T10:00:00Z"
      },
      {
        "leftOperand": "client",
        "operator": "eq",
        "rightOperand": "https://app.example/client-id"
      }
    ]
  }]
}

本节定义的数据模型独立于任何特定的 序列化形式。

{
  "@context": [
    "https://www.w3.org/ns/lws/v1"
  ]
}

访问请求和访问授权端点 是 LWS 容器，并且必须 符合本规范定义的规则。

这些端点至少需要支持 GET 和 POST 操作。建议支持 DELETE 操作。 还可以支持其他操作。

这些端点对请求和响应有效载荷都必须支持 11.4.1 JSON-LD 序列化中定义的 JSON-LD 序列化形式。服务器 可以支持其他序列化形式。

主体通过向 访问请求端点提交 POST 请求来 创建访问请求。存储 控制者通过 向访问授权端点提交 POST 请求来创建访问授权。

成功的 POST 操作必须使用 Location 标头作出响应， 该标头被设置为 新资源的 URL。

通知提供了一种机制，用于告知主体和存储 控制者有关 访问请求和访问授权的变更。当 访问请求或访问授权上存在 inbox 属性时，服务器应当向该端点递送 通知，将事件告知 受让方。

通知的序列化形式必须符合 LWS 通知数据模型的要求。

递送到 inbox 端点的通知必须符合 LWS 协议中为通知递送定义的要求。

LWS 存储描述必须可使用媒体类型 application/lws+cid 进行序列化。 application/lws+cid 媒体类型标识一种文档，该文档是 W3C 受控标识符文档 [CID-1.0] 的一种特化，并使用 LWS 词汇表进行了扩展。

LWS 容器表示必须支持媒体类型 application/lws+json。

虽然 LWS 容器表示使用 JSON-LD 约定，但 LWS 的约束和要求 使使用特定媒体类型具有合理性。由于 LWS 容器可以被视为 JSON-LD 的受限配置文件， 实现应当将 application/ld+json; profile="https://www.w3.org/ns/lws/v1" 媒体类型视为等同于 application/lws+json。

GET /alice/photos/ HTTP/1.1
Authorization: Bearer <token>
Accept: application/lws+json

HTTP/1.1 200 OK
Content-Type: application/lws+json
ETag: "photos-page1-etag"
Link: </alice/photos/.meta>; rel="linkset"; type="application/linkset+json"
Link: </alice/>; rel="up"
Link: <https://www.w3.org/ns/lws#Container>; rel="type"
Link: </alice/photos/?page=1>; rel="first"
Link: </alice/photos/?page=3>; rel="last"
Link: </alice/photos/?page=2>; rel="next"

{
  "@context": "https://www.w3.org/ns/lws/v1",
  "id": "/alice/photos/",
  "type": "Container",
  "totalItems": 150,
  "items": [
    {
      "type": "DataResource",
      "id": "/alice/photos/vacation.jpg",
      "format": "image/jpeg",
      "size": 248392,
      "modified": "2025-11-20T10:30:00Z"
    },
    {
      "type": "DataResource",
      "id": "/alice/photos/portrait.png",
      "format": "image/png",
      "size": 102400,
      "modified": "2025-11-21T14:15:00Z"
    }
  ]
}

GET /alice/photos/?page=2 HTTP/1.1
Authorization: Bearer <token>
Accept: application/lws+json

HTTP/1.1 200 OK
Content-Type: application/lws+json
ETag: "photos-page2-etag"
Link: </alice/photos/.meta>; rel="linkset"; type="application/linkset+json"
Link: </alice/>; rel="up"
Link: <https://www.w3.org/ns/lws#Container>; rel="type"
Link: </alice/photos/?page=1>; rel="first"
Link: </alice/photos/?page=1>; rel="prev"
Link: </alice/photos/?page=3>; rel="next"
Link: </alice/photos/?page=3>; rel="last"

{
  "@context": "https://www.w3.org/ns/lws/v1",
  "id": "/alice/photos/",
  "type": "Container",
  "totalItems": 150,
  "items": [
    {
      "type": "DataResource",
      "id": "/alice/photos/sunset.jpg",
      "format": "image/jpeg",
      "size": 315000,
      "modified": "2025-11-22T09:00:00Z"
    }
  ]
}