链接式 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 resource_metadata="https://storage.example/.well-known/oauth-protected-resource/storage_1/photos/img.jpg",
                error="invalid_token"

{
    "resource": "https://storage.example/storage_1/photos/img.jpg",
    "authorization_servers": ["https://authorization.example"]
}

{
    "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"],
    "subject_identifier_types_supported": [
        "did:web",
        "did:key",
        "https"]
}

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/storage_1",
  "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/json-patch+json", "application/merge-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 元数据系统基于 Web Linking [RFC8288] 的原则，该原则允许服务器使用带类型的链接描述 资源之间的关系。元数据增强可发现性，支持自描述 API， 并与资源操作以及容器层次结构保持一致。

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

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

元数据区分资源及其表示形式，在适用情况下允许存在多种媒体类型。 对于数据资源，元数据包括表示形式，每个表示形式具有 格式以及可选的 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 Patch [RFC6902] 的支持： Accept-Patch: application/json-patch+json。

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

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

管理元数据 元数据通过与资源关联的链接集资源 URI 进行交互来管理。服务器必须在对 GET 和 HEAD 请求的响应中包含 [RFC9110] 中定义的 ETag 标头。

• 部分更新（PATCH）：这是管理元数据的主要机制。服务器必须支持使用 application/json-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 标头请求包含特定的元数据链接（通过关系类型）和 属性。

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

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

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

GET（非容器资源） – 检索资源的内容： 向资源 URI 发送 GET 以获取完整内容（如果已获授权）。以 200 OK 响应，响应主体包含 数据，并且 Content-Type 与存储的媒体类型匹配。服务器必须按照 [RFC7233] 支持用于部分 检索的范围请求。响应必须包含 [RFC9110] 中定义的 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 容器媒体 类型。该列表包括每个成员的元数据：资源标识符（必须）、类型（必须）、媒体类型（对于 DataResources 必须）、大小（应当）以及 修改时间戳（应当）。

示例（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 时间戳，并作为扁平 属性。

在所有情况下，服务器必须在响应 标头中包含以下元数据：[RFC9110] 中定义的 ETag 标头，以及带有 rel="linkset"、rel="up" 和 rel="type" 的 Link 标头，用于表明它是一个 容器。

HEAD（任何资源或容器） – 仅标头/元数据： LWS 服务器必须对容器和非容器都支持 [RFC9110] 中的 HEAD，并返回与 GET 相同的标头（包括 Content-Type、用于元数据的 Link），但不返回响应主体。这使得 无需传输内容即可检索元数据。

缓存和条件请求：LWS 利用 HTTP 缓存语义。服务器应当支持 [RFC9110] 中定义的条件请求， 包括实体标签（ETags）和基于日期的验证器（例如 If-Modified-Since 标头）等机制。如果资源或容器列表 未发生更改，则以 304 Not Modified 响应，以避免冗余传输。

可发现性与授权：为增强可发现性， 401 Unauthorized 响应包含一个 WWW-Authenticate 标头，其中带有 resource_metadata 参数，如授权服务器发现中所述，以便客户端能够 在不硬编码 URI 的情况下定位授权服务器。

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

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

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

PUT（替换整个资源） – 向资源 URI 发送 PUT，请求主体中包含新的完整内容，并带有匹配的 Content-Type（通常与现有类型一致）。对于现有资源，PUT 是幂等的。 客户端应当使用 [RFC9110] 中定义的条件请求，以避免覆盖并发更改。

示例（使用 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）。服务器会将其 与当前实体标签（ETag）进行比较；如果匹配，则继续使用 提供的 JSON 替换内容。如果不匹配，服务器会拒绝更新（因为该资源在此期间已被 其他人更改）。 成功响应：如果更新成功，服务器可以使用 200 OK 响应，并且 可以包含更新后的表示或某种确认信息（例如新内容或其中的一部分）。 或者，服务器可以使用 204 No Content 响应，以表示成功但没有响应主体 （尤其常见于无需传达其他信息的情况）。例如：

HTTP/1.1 204 No Content

• 错误响应：如果 If-Match 前置条件不匹配 （并发修改），服务器以 412 Precondition Failed 响应。如果 资源不存在，则作为更新用途的 PUT 将导致 404 Not Found。如果 客户端未获授权，则返回 403 Forbidden（如果未提供有效 凭据，则返回 401 Unauthorized）。如果请求负载无效，则返回 400 Bad Request。

PATCH（部分更新） – HTTP PATCH 方法 [RFC5789] 允许客户端指定对资源的部分修改，而不是发送全部新的 内容。这对于大型资源很有用，因为如果 仅有一小部分发生变化，发送整个内容会很低效；或者对于并发编辑，你希望应用特定更改时也很有用。LWS 服务器 必须 至少支持 JSON Patch (application/json-patch+json)，如 [RFC6902] 中所定义。

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

元数据的条件请求 由于资源的元数据可以由多个参与者修改，因此防止并发覆盖非常 重要。对于链接集资源上的 PUT 和 PATCH 操作，服务器和客户端应当使用 [RFC9110] 中定义的条件请求。当服务器收到前置条件 失败的条件请求时，它必须以 412 Precondition Failed 状态码拒绝该请求。 示例（使用 PUT 替换链接集）： 客户端首先获取链接集。

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
{
  "linkset": [
    {
      "anchor": "/alice/personalinfo.json",
      "describedby": [ { "href": "/schemas/personal-info.json" } ]
    }
  ]
}

客户端现在希望添加许可证。它构造一个新的完整链接集文档，并发送 PUT 请求。

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

如果成功，服务器将返回成功响应。

HTTP/1.1 204 No Content

更新规则摘要 如果只想更改资源的内容 → 对资源本身执行 PUT/PATCH。 如果只想更改资源的链接（元数据）→ 对资源关联的链接集资源执行 PUT/PATCH。 如果想同时更改内容和链接 → 对资源本身执行 PUT/PATCH，并包含相应的 Link 标头以及 'Prefer: set-linkset'。默认情况下不会同时设置两者。

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

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

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

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

删除与包含关系： 删除资源时，服务器必须以原子方式将其从 父容器的 items 列表中删除。父容器的 totalItems 计数应当相应更新。

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

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

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

如果客户端缺少授权，服务器必须返回 403 Forbidden（如果 已知客户端的身份但权限不足）或 401 Unauthorized（如果未提供有效 身份验证）。如果暴露资源是否存在会带来安全风险， 服务器可以改为返回 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"
    }
  ]
}