链接式 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/metadata>; rel="storageDescription"
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/lws/v1",
  "id": "https://storage.example/",
  "type": "Storage",
  "service": [{
    "type": "StorageDescription",
    "serviceEndpoint": "https://storage.example/description"
  }]
}

{
  "@context": "https://www.w3.org/ns/lws/v1",
  "id": "https://storage.example/",
  "type": "Storage",
  "capability": [{
    "type": "https://feature.example/PatchSupport",
    "mediaType": {
      "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": "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"
  }, {
    "type": "StorageDescription",
    "serviceEndpoint": "https://storage.example/description"
  }]
}

Linked Web Storage 将资源组织到容器中。容器是一种 专门资源，它保存对其他资源的引用，这些资源称为其成员。容器充当 组织单元，类似于目录或集合，使客户端能够对资源进行分组、发现 和导航。容器维护对其成员资源的引用， 这些成员资源可以同时包括非容器资源和其他容器资源，从而支持 层级结构。通常，容器除了元数据或成员枚举之外， 仅包含最少的内在内容；其主要作用是聚合和结构化 下级资源。存储系统的根被指定为容器，作为 没有上级父项的顶层组织单元。容器MUST 使用 'ContainerPage' 类型支持成员列表的分页，并具有 'first'、 'next'、'prev' 和 'last' 等属性。表示MUST 使用带有特定 框架和规范性上下文的 JSON-LD，并可选择通过 'Vary: Accept' 标头宣告内容协商。 存储MAY 作为根容器运行，从而允许直接写入。

每个 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，并且MAY 纳入客户端提示（例如 Slug 标头）， 但客户端SHOULD NOT 假定 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",
      "mediaType": "text/plain",
      "size": 47,
      "modified": "2025-11-24T12:00:00Z"
    },
    {
      "type": ["DataResource", "http://example.org/customType"],
      "id": "/alice/notes/todo.json",
      "mediaType": "application/json",
      "size": 2048,
      "modified": "2025-11-24T13:00:00Z"
    }
  ]
}

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

元数据模型 LWS 中的所有元数据都表示为一组源自某个资源（链接上下文）的带类型链接。 每个链接由以下部分组成：

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

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

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

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

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

• 存储描述：服务器MUST 在相关响应上支持带有 rel="storageDescription" 的 Link 标头。
• 包含关系：对于任何 非根资源，服务器MUST 包含一个带有 rel="up" 的 Link 标头，指向父容器。
• 偏好：客户端MAY 使用 Prefer 标头 [RFC7240] 和 URI https://www.w3.org/ns/lws#PreferLinkRelations 来包含或省略特定关系。

元数据类型

可修改性考量 核心元数据MAY 由客户端修改。为确保互操作性，服务器 MUST 使用标准 HTTP 标头来宣告其能力：

1. 方法发现：服务器MUST 通过 Allow 标头宣告对 linkset 资源上 GET 和 PATCH 操作的支持。

2. 补丁格式发现：服务器MUST 通过 Accept-Patch 标头宣告 对 JSON Merge Patch [RFC7386] 的支持： Accept-Patch: application/merge-patch+json。

3. 可选方法：服务器MAY 支持 PUT 或替代补丁格式； 如果支持，则这些内容MUST 分别包含在 Allow 和 Accept-Patch 标头中。

[!IMPORTANT] 客户端SHOULD NOT 假定支持 PUT 或特定补丁格式， 除非它们在资源标头中被宣告，并且MUST 优雅处理 405 Method Not Allowed 或 415 Unsupported Media Type 响应。

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

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

• 替换（PUT）：如果在 Allow 标头中宣告，客户端MAY 替换整个 linkset。如果服务器不支持 PUT，则它MUST 以 405 Method Not Allowed 拒绝该请求。

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

• 生命周期：元数据生命周期与所描述的资源绑定；删除资源MUST 导致自动移除其关联的linkset 资源元数据。

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

输入：

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

行为：

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

可能的响应：

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

新资源通过对目标容器 URI 使用 POST 创建，服务器分配 最终标识符。客户端MAY 通过 Slug 标头建议名称。 客户端MAY 通过在 POST 请求中 包含一个或多个 Link 标头，为新资源提供初始用户管理元数据，并遵循 [RFC8288] 中 Web Linking 的语法。服务器管理的元数据MUST 由服务器在创建时自动生成，并且MUST NOT 被 客户端提供的链接覆盖。

成功时，服务器MUST 返回 201 状态码，并在 Location 标头中包含新 URI。服务器MUST 包含 Link 标头， 用于关键服务器管理元数据，包括指向父容器的链接 （rel="up"），以及指向所创建资源的专用linkset 资源的链接 （rel="linkset"; type="application/linkset+json"）。其他链接SHOULD 包括 rel="type"（表示 https://www.w3.org/ns/lws#Container 或 https://www.w3.org/ns/lws#DataResource）。正文MAY 为空或 包含资源的最小表示。所有元数据创建和链接MUST 与资源创建保持原子性，以维护一致性。

POST（到容器 URI） – 使用服务器分配的名称创建： 使用 POST 将新资源添加到现有容器内。服务器为该资源分配标识符， 可选择使用 Slug 标头提出建议。若 Slug 标头不与命名规则或现有 资源冲突，服务器MAY 采纳它。客户端按如下方式指示要创建的资源类型：

• 要创建容器，客户端MUST 包含一个 Link 标头，其 rel="type" 指向 Container 类型： 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
Slug: shoppinglist.txt

milk
eggs
bread
butter
apples
orange juice

在此示例中，客户端正在向容器 /alice/notes/ 发布。 它提供 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/ 不存在，则服务器 MUST 返回 404 错误状态，除非另一个状态码更合适。

创建容器：要创建新的容器，客户端对现有父容器使用 POST，并带有一个指示 Container 类型的 Link 标头。例如：

POST /alice/ HTTP/1.1
Host: example.com
Authorization: Bearer <token>
Content-Length: 0
Slug: notes
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"。

关于 Create（HTTP 绑定）的附加说明：

• POST 不是幂等的。重复它可能会创建重复项；客户端SHOULD 避免无意重试，或使用唯一标识符/检查来防止这种情况。
• 元数据更新是原子的；服务器MUST 确保linkset 资源在返回成功之前被创建，并填充强制性 服务器管理字段。
• 为实现可发现性，服务器SHOULD 在 401 响应上包含带有 rel="storageDescription" 的 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/ld+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",
      "mediaType": "text/plain",
      "size": 47,
      "modified": "2025-11-24T12:00:00Z"
    },
    {
      "type": ["DataResource", "http://example.org/customType"],
      "id": "/alice/notes/todo.json",
      "mediaType": "application/json",
      "size": 2048,
      "modified": "2025-11-24T13:00:00Z"
    }
  ]
}

在此示例中，/alice/notes/ 是一个容器。响应使用带有 LWS 上下文的 JSON-LD，列出带有必需元数据的成员。每个条目都包含其 type、 id、mediaType、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 状态码和载荷，以保持一致性，并纳入诸如 分页、并发控制、配额约束和元数据集成等特定场景：

存储MAY 在其存储描述资源中宣告对访问请求和 访问授予的支持。当宣告此类支持时，描述 访问请求端点的服务 对象MUST 具有等于字符串 AccessRequestService 的 type，并且描述访问授予端点的服务对象MUST 具有 等于字符串 AccessGrantService 的 type。服务 对象SHOULD 包含一个 conformsTo 属性，其值为一个 由一个或多个 URI 组成的集合，用于标识该端点支持的访问配置文件。 可以包含其他属性：

{
  "@context": [
    "https://www.w3.org/ns/lws/v1"
  ],
  "id": "https://storage.example/",
  "type": "Storage",
  "service": [
    {
      "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 对象。一个使用 ODRL 概念描述访问请求的配置文件 在10.3 访问配置文件中描述。

以下示例展示一个访问请求。该示例 使用10.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/projects/"]
    },
    "constraint": [
      {
        "leftOperand": "purpose",
        "operator": "eq",
        "rightOperand": "https://purpose.example/collaboration"
      },
      {
        "leftOperand": "dateTime",
        "operator": "lteq",
        "rightOperand": "2026-06-09T10:00:00Z"
      }
    ]
  }]
}

以下示例展示一个访问授予。该示例 使用10.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/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/data/2025",
        "https://storage.example/data/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": "mediaType",
        "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/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 容器，并且MUST 符合本规范中定义的规则。

这些端点至少需要支持 GET 和 POST 操作。DELETE 操作 是RECOMMENDED。其他操作MAY 受支持。

这些端点MUST 支持 10.4.1 JSON-LD 序列化中定义的 JSON-LD 序列化，用于请求和响应载荷。服务器 MAY 支持其他序列化。

代理 通过向 访问请求端点提交 POST 请求来 创建访问请求。 存储 控制者通过 向访问授予端点提交 POST 请求 创建访问授予。

成功的 POST 操作MUST 以设置为 新资源 URL 的 Location 标头进行响应。

通知提供一种机制，用于告知代理和存储 控制者有关 访问请求和访问授予的变更。当 访问请求或访问授予上存在 inbox 属性时， 服务器SHOULD 向该端点传递 通知，告知被指派方该事件。

通知的序列化MUST 符合 LWS 通知数据模型的要求。

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

LWS 容器表示和存储描述资源MUST 使用媒体类型 application/lws+json。

虽然 LWS 容器表示使用 JSON-LD 约定，但 LWS 的约束和要求 使得使用特定媒体类型是合理的。因为 LWS 容器可被视为 JSON-LD 的受限配置文件， 实现SHOULD 将 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: </alice/photos/.acl>; rel="acl"
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",
      "mediaType": "image/jpeg",
      "size": 248392,
      "modified": "2025-11-20T10:30:00Z"
    },
    {
      "type": "DataResource",
      "id": "/alice/photos/portrait.png",
      "mediaType": "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: </alice/photos/.acl>; rel="acl"
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",
      "mediaType": "image/jpeg",
      "size": 315000,
      "modified": "2025-11-22T09:00:00Z"
    }
  ]
}