연결된 웹 스토리지 프로토콜 1.0

LWS 프로토콜은 어떤 주체가 일부 리소스를 일부 에이전트에게 제공할 수 있도록 하는 표준 상호작용을 정의한다.

• 제공되는 리소스 - (사용 가능한 리소스? 게시된 리소스?) (UCS에서 정의되지 않음) 이 문서에 정의된 프로토콜을 사용하여 상호작용, 검색 또는 조작을 위해 서비스가 노출하는 네트워크 접근 가능 엔터티.
• 요청 에이전트 - (UCS의 엔터티) 제공 가능한 리소스와 상호작용하기 위한 요청을 시작하는 엔터티(예: 클라이언트, 사용자 또는 프로세스).

리소스 관리자는 제공되는 리소스를 비공개로 유지할 수 있고, 누구나 공개적으로 사용할 수 있게 할 수도 있으며, 그 가시성을 제한된 집합의 요청 에이전트로 제한할 수도 있다.

• 인증 - 요청을 실행하는 에이전트의 신원을 확인하는 과정.
• 권한 부여 - 에이전트가 특정 리소스에 접근하거나 일련의 작업 중 하나를 수행할 권한이 있는지 결정하는 과정.
• 리소스 관리자 - (UCS의 컨트롤러) 제공되는 리소스에 대한 접근을 제어할 권한을 가진 에이전트.

비규범적이라고 표시된 절뿐 아니라, 이 명세의 모든 작성 지침, 다이어그램, 예시 및 참고는 비규범적이다. 이 명세의 그 밖의 모든 내용은 규범적이다.

이 문서의 핵심어 MAY, MUST, MUST NOT, OPTIONAL, RECOMMENDED, REQUIRED, SHOULD, 및 SHOULD NOT은 여기 표시된 것처럼 모두 대문자로 나타나는 경우에, 그리고 그 경우에만, BCP 14 [RFC2119] [RFC8174]에 설명된 대로 해석된다.

LWS 서버는 이 명세의 관련 "MUST" 문을 모두 준수하는 HTTP 서버 [rfc9112]이다. 구체적으로, 이 문서의 9. 작업에 있는 관련 규범적 "MUST" 문을 준수해야 한다.

LWS 클라이언트는 이 명세의 관련 "MUST" 문을 모두 준수하는 HTTP 클라이언트 [rfc9112]이다. 구체적으로, 이 문서의 9. 작업에 있는 관련 규범적 "MUST" 문을 준수해야 한다.

다음 다이어그램은 구현을 안내하기 위한 플랫폼 독립적 모델이다.

이 절에서 설명하는 데이터 모델은 인증 자격 증명의 모든 구체적인 직렬화에 대한 요구사항을 개괄한다.

인증 자격 증명은 주체에 관한 변조 증거가 있는 클레임을 포함해야 하며, 여기에는 다음이 포함된다:

• 주체 REQUIRED — 최종 사용자에 대한 식별자. 이는 MUST URI여야 한다.
• 발급자 REQUIRED — 인증 자격 증명을 발급한 엔터티의 식별자. 이는 MUST URI여야 한다.
• 클라이언트 REQUIRED — 클라이언트 애플리케이션의 식별자. 이는 SHOULD URI여야 한다.
• 대상자 제한 RECOMMENDED — 권한 부여 서버 식별자를 포함해야 하는 값의 목록.

인증 자격 증명의 검증에는 자격 증명의 검증자와 발급자 사이의 신뢰 관계가 필요하다. 이 신뢰 관계는 MAY 대역 외 메커니즘을 통해 수립될 수 있다. 검증자와 발급자 사이의 신뢰를 수립하기 위한 추가 메커니즘은 특정 인증 스위트에 개괄된다.

인증 자격 증명은 MUST 서명되어야 한다. 그 서명에 비대칭 암호화를 사용하는 것이 RECOMMENDED된다.

각 인증 스위트는 토큰 유형 URI와 연관되어야 한다. 인증 스위트는 IANA "OAuth URI" 레지스트리에 정의된 URI를 사용하는 것이 SHOULD된다.

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

Linked Web Storage는 리소스를 컨테이너로 구성한다. 컨테이너는 멤버라고 하는 다른 리소스에 대한 참조를 보유하는 특수한 리소스이다. 컨테이너는 디렉터리나 컬렉션과 유사한 구성 단위로 사용되어 클라이언트가 리소스를 그룹화하고 검색하며 탐색할 수 있게 한다. 컨테이너는 멤버 리소스에 대한 참조를 유지하며, 이러한 멤버 리소스에는 비컨테이너 리소스와 추가 컨테이너 리소스가 모두 포함될 수 있으므로 계층 구조를 형성할 수 있다. 일반적으로 컨테이너에는 메타데이터나 멤버 열거 외에 고유한 콘텐츠가 거의 없으며, 주된 역할은 하위 리소스를 집계하고 구조화하는 것이다. 저장소 시스템의 루트는 상위 부모가 없는 최상위 구성 단위로 사용되는 컨테이너로 지정된다. 컨테이너 표현의 구조는 8.1 컨테이너 표현에서 정의하며, 해당 미디어 유형과 페이지 매김 요구 사항은 12. LWS 미디어 유형에서 정의한다. 저장소는 직접 쓰기를 가능하게 하는 루트 컨테이너로 기능할 수 있다.

모든 LWS 저장소에는 최상위 구성 단위로 사용되는 저장소 루트가 있다. 저장소 루트에는 부모가 없으며 저장소 계층 구조의 진입점 역할을 한다.

LWS의 리소스는 다음 중 하나로 분류된다:

• 컨테이너 — 다른 리소스를 포함하는 리소스.
• 데이터 리소스 — 데이터를 담고 있는 리소스 (예: 문서, 이미지 또는 구조화된 데이터 파일).

리소스와 그 부모 컨테이너 사이의 포함 관계는 rel="up" 링크 관계를 통해 표현된다. 서버는 루트가 아닌 모든 리소스에 대한 GET 및 HEAD 요청의 응답에서 부모 컨테이너를 가리키는 rel="up"이 있는 Link 헤더를 포함해야 한다.

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

컨테이너의 구성원은 그 표현에서 items 속성을 사용하여 나열된다. 서버가 이 목록을 관리하며, 클라이언트는 이를 직접 수정할 수 없다. 구성원 변경은 리소스 생성 및 삭제의 부수 효과로 발생한다.

서버는 항상 포함 관계 무결성을 유지해야 한다:

• 생성: 컨테이너 안에 새 리소스가 생성되면, 서버는 해당 리소스를 컨테이너의 items 목록에 원자적으로 추가해야 한다.
• 삭제: 리소스가 삭제되면, 서버는 이를 부모 컨테이너의 items 목록에서 원자적으로 제거해야 한다. 컨테이너를 삭제하려면, 재귀 삭제가 명시적으로 요청되지 않는 한 해당 컨테이너가 비어 있어야 한다.
• 고아 없음: 루트가 아닌 모든 리소스는 포함 관계 계층을 통해 스토리지 루트에서 도달 가능해야 한다.
• 순환 없음: 컨테이너는 직접 또는 간접적으로 자기 자신을 포함해서는 안 된다.

리소스는 URI로 식별된다. 리소스의 URI는 포함 관계 계층 구조에서의 위치와 독립적이다. 서버는 리소스를 생성할 때 URI를 할당하고 클라이언트 힌트를 반영할 수 있지만, 클라이언트는 URI 구조가 포함 관계를 반영한다고 추정하지 않는 것이 좋다.

포함 관계는 URI 경로 구조가 아니라 메타데이터(rel="up" 링크 및 컨테이너 표현의 items 속성)를 통해 표현된다. 이러한 분리는 서버가 명확히 정의된 조직 모델을 유지하면서도 URI 할당에서 유연성을 가질 수 있게 한다.

클라이언트가 컨테이너에 대한 읽기 접근 권한을 가진 경우, 컨테이너 표현은 해당 클라이언트가 접근할 수 있는, 그 컨테이너 안에 포함된 모든 리소스의 식별자를 포함해야 한다. 또한 클라이언트가 접근할 수 없는, 그 컨테이너 안에 포함된 리소스의 식별자도 포함할 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 메타데이터 시스템은 서버가 유형이 지정된 링크를 사용하여 리소스 간의 관계를 설명할 수 있게 하는 웹 링크 [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 헤더를 반드시 포함해야 한다.
• 선호 사항: 클라이언트는 특정 관계를 포함하거나 생략하기 위해 URI https://www.w3.org/ns/lws#PreferLinkRelations와 함께 Prefer 헤더 [RFC7240]를 사용할 수 있다.

메타데이터 유형

수정 가능성 고려 사항 핵심 메타데이터는 클라이언트가 수정할 수 있다. 상호 운용성을 보장하기 위해 서버는 기능을 알리는 데 표준 HTTP 헤더를 반드시 사용해야 한다.

1. 메서드 검색: 서버는 Allow 헤더를 통해 링크 집합 리소스에 대한 GET 및 PATCH 작업 지원을 반드시 알려야 한다.

2. 패치 형식 검색: 서버는 Accept-Patch 헤더를 통해 JSON 병합 패치 [RFC7386] 지원을 반드시 알려야 한다. Accept-Patch: application/merge-patch+json.

3. 선택적 메서드: 서버는 PUT 또는 대체 패치 형식을 지원할 수 있다. 지원하는 경우 이러한 메서드와 형식은 각각 Allow 및 Accept-Patch 헤더에 반드시 포함되어야 한다.

[!중요] 클라이언트는 리소스 헤더에 지원이 명시되지 않은 한 PUT 또는 특정 패치 형식의 지원을 가정하지 않는 것이 좋으며, 405 Method Not Allowed 또는 415 Unsupported Media Type 응답을 반드시 적절히 처리해야 한다.

메타데이터 관리 메타데이터는 리소스와 연결된 링크 집합 리소스 URI와 상호 작용하여 관리한다. 서버는 업데이트를 위한 동시성 제어를 반드시 지원해야 한다.

• 부분 업데이트(PATCH): 메타데이터 관리를 위한 기본 메커니즘이다. 서버는 application/merge-patch+json을 사용하는 PATCH를 반드시 지원해야 한다.

• 교체(PUT): Allow 헤더에 명시된 경우 클라이언트는 전체 링크 집합을 교체할 수 있다. 서버가 PUT을 지원하지 않으면 405 Method Not Allowed로 요청을 반드시 거부해야 한다.

• 제한 사항: 서버는 시스템 무결성을 유지하기 위해 특정 링크(예: up 또는 items)에 대한 수정을 제한할 수 있다.

• 수명 주기: 메타데이터의 수명 주기는 설명 대상 리소스에 종속된다. 리소스를 삭제하면 연결된 링크 집합 리소스 메타데이터도 반드시 자동으로 제거되어야 한다.

리소스 생성 작업은 새 제공되는 리소스를 기존 컨테이너에 추가한다. 이 작업은 데이터 리소스와 하위 컨테이너 생성을 모두 처리한다.

입력:

• 대상 컨테이너: 새 리소스가 생성될 컨테이너의 식별자.
• 식별자 힌트: 새 리소스의 식별자에 대한 선택적 제안. 서버는 이 힌트를 사용할 수 있지만, 반드시 사용할 필요는 없다.
• 콘텐츠: 새 리소스의 초기 콘텐츠와 유형.

동작:

• 식별자 생성: 서버는 새 리소스의 최종 식별자(URI)를 결정한다. 식별자 힌트가 제공된 경우, 서버는 컨테이너 내의 고유성과 유효성을 보장하면서 이를 반영하려고 시도한다. 힌트가 제공되지 않은 경우, 서버는 고유 식별자를 생성한다.
• 컨테이너 구성원 관계 갱신: 서버는 새 리소스를 대상 컨테이너의 구성원 목록에 원자적으로 추가한다.
• 메타데이터 초기화: 서버는 새 리소스에 대한 시스템 메타데이터를 초기화한다. 리소스에 연결된 메타데이터 리소스가 있는 경우, 그것도 초기화된다.

가능한 응답:

• Created: 작업이 성공했다. 서버는 새로 생성된 리소스의 최종 식별자를 반환한다.
• Target Not Found: 지정된 대상 컨테이너가 존재하지 않는다.
• Not Permitted: 클라이언트의 식별자는 알려져 있지만, 이 컨테이너에서 리소스를 생성할 권한이 없다.
• Unknown Requester: 서버가 클라이언트의 식별자를 인식하지 못하며 인증을 요구한다.
• Conflict: 생성된 식별자를 가진 리소스가 이미 존재하거나 다른 상태 충돌이 있다.
• Unknown Error: 예상치 못한 내부 오류가 발생했다.

새 리소스는 대상 컨테이너 URI에 POST를 사용하여 생성하며, 서버가 최종 식별자를 할당한다. 클라이언트는 [RFC8288]의 웹 링크 구문에 따라 POST 요청에 하나 이상의 Link 헤더를 포함하여 새 리소스의 초기 사용자 관리 메타데이터를 제공할 수 있다. 서버 관리 메타데이터는 생성 시 서버에서 반드시 자동으로 생성해야 하며 클라이언트가 제공한 링크로 재정의해서는 안 된다.

성공하면 서버는 새 URI를 Location 헤더에 포함하여 201 상태 코드를 반드시 반환해야 한다. 서버는 부모 컨테이너에 대한 링크 (rel="up") 및 생성된 리소스의 전용 링크 집합 리소스에 대한 링크(rel="linkset"; type="application/linkset+json")를 비롯한 주요 서버 관리 메타데이터의 Link 헤더를 반드시 포함해야 한다. 추가 링크에는 https://www.w3.org/ns/lws#Container 또는 https://www.w3.org/ns/lws#DataResource를 나타내는 rel="type"을 포함하는 것이 좋다. 본문은 비어 있거나 리소스의 최소 표현을 포함할 수 있다. 일관성을 유지하기 위해 모든 메타데이터 생성과 연결은 리소스 생성과 함께 반드시 원자적으로 수행되어야 한다.

POST(컨테이너 URI에 전송) – 서버에서 할당한 이름으로 생성: POST를 사용하여 기존 컨테이너 내부에 새 리소스를 추가한다. 서버가 리소스의 식별자를 할당한다. 클라이언트는 생성할 리소스의 유형을 다음과 같이 나타낸다.

• 컨테이너를 생성하려면 클라이언트는 Container 유형을 가리키는 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

성공하면 새 URI를 Location 헤더에 포함하여 201 Created를 반환한다. 본문은 비어 있거나 최소 표현일 수 있다. 대상 컨테이너 /alice/notes/가 존재하지 않으면 더 적절한 다른 상태 코드가 없는 한 서버는 404 오류 상태를 반드시 반환해야 한다.

컨테이너 생성: 새 컨테이너를 생성하려면 클라이언트는 Container 유형을 나타내는 Link 헤더와 함께 기존 부모 컨테이너에 POST를 사용한다. 예를 들면 다음과 같다.

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/에 새 컨테이너를 생성하며, rel="type"이 https://www.w3.org/ns/lws#Container인 항목을 포함한 서버 생성 메타데이터도 함께 생성한다.

생성에 관한 추가 참고 사항(HTTP 바인딩):

• POST는 멱등성이 없다. 이를 반복하면 중복 항목이 생성될 수 있으므로 클라이언트는 의도하지 않은 재시도를 피하는 것이 좋으며, 이를 방지하기 위해 고유 식별자나 검사를 사용해야 한다.
• 메타데이터 업데이트는 원자적으로 수행된다. 서버는 성공을 반환하기 전에 링크 집합 리소스가 생성되고 필수 서버 관리 필드로 채워지도록 반드시 보장해야 한다.
• 검색 가능성을 위해 서버는 하드코딩된 URI 없이 클라이언트를 안내하도록 401 응답에 rel="https://www.w3.org/ns/lws#storage"가 있는 Link 헤더를 포함하는 것이 좋다.

메타데이터 관리 및 검색(생성과 관련됨): 메타데이터는 주로 읽기 작업을 통해 검색하지만 생성 중에 만들어진다. 클라이언트는 생성 직후 새 리소스 URI에 GET 또는 HEAD를 사용하여 이를 검색할 수 있다. 클라이언트는 특정 메타데이터 링크와 속성을 포함하도록 요청하기 위해 Prefer 헤더를 사용할 수 있다(관계 유형을 통해).

기존 리소스의 표현 또는 컨테이너의 목록을 검색한다.

• 입력: 대상 식별자 및 선택적 매개변수.
• 동작:
  • 컨테이너가 아닌 리소스의 경우, 서버는 리소스 콘텐츠를 반환한다.
  • 컨테이너의 경우, 서버는 권한 부여에 따라 필터링될 MAY 있는 구성원 리소스 목록을 반환한다. 목록은 각 구성원에 대한 핵심 메타데이터를 포함해야 한다.
• 결과: 요청된 표현 또는 실패 알림.

리소스 읽기 작업은 HTTP GET 요청(및 헤더 전용 요청을 위한 HEAD)으로 리소스 표현을 요청한다. 동작은 대상 URL이 컨테이너인지 또는 컨테이너가 아닌 리소스(데이터 리소스)인지에 따라 다르다. 서버는 메타데이터를 통해 리소스 유형을 구별해야 한다. 모든 응답은 rel="linkset", rel="up", rel="type"과 같은 핵심 관계에 대한 Link 헤더를 포함하여 제8.1절에 정의된 메타데이터와 통합되어야 한다. 서버는 읽기 중 리소스 상태와 그 메타데이터 사이의 원자성을 보장해야 한다.

GET (컨테이너가 아닌 리소스) – 리소스의 콘텐츠 검색: 전체 콘텐츠를 얻기 위해 리소스 URI에 GET을 보낸다(권한이 있는 경우). 200 OK, 데이터를 포함한 본문, 그리고 저장된 미디어 유형과 일치하는 Content-Type으로 응답한다. 서버는 부분 검색을 위해 [RFC7233]에 따른 범위 요청을 지원해야 한다. 응답은 동시성 제어 및 캐싱을 위해 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

서버는 텍스트 콘텐츠를 반환했다(Content-Length가 나타내는 것처럼 총 34바이트). 콘텐츠는 파일에 저장된 정확한 데이터이다. 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 타임스탬프를 평면 속성으로 포함한다.

모든 경우에, 서버는 응답 헤더에 다음 메타데이터를 포함해야 한다: ETag(구성원 수정 시 변경되는 목록 버전을 나타냄), 그리고 그것이 컨테이너임을 나타내는 rel="type", rel="linkset", 및 rel="up"이 있는 Link 헤더.

HEAD (모든 리소스 또는 컨테이너) – 헤더/메타데이터만: LWS 서버는 컨테이너와 비컨테이너 모두에 대해 HEAD [RFC9110]를 지원해야 하며, GET과 동일한 헤더(ETag, Content-Type, 메타데이터에 대한 Link 포함)를 반환하되 본문은 반환하지 않는다. 이를 통해 콘텐츠를 전송하지 않고 메타데이터를 검색할 수 있다.

캐싱 및 조건부 요청: LWS는 HTTP 캐싱 의미론을 활용한다. 서버는 If-None-Match(ETags 사용) 또는 If-Modified-Since 헤더를 통한 조건부 요청을 지원해야 한다. 리소스 또는 컨테이너 목록이 변경되지 않은 경우, 중복 전송을 피하기 위해 304 Not Modified로 응답한다. ETags는 동시성 및 캐싱 지원을 위해 모든 GET/HEAD 응답에 제공되어야 한다.

발견 가능성 및 권한 부여: 향상된 발견 가능성을 위해, 서버는 하드코딩된 URI 없이 클라이언트를 안내하는 매개변수와 함께 401 Unauthorized 응답에 WWW-Authenticate 헤더를 포함하는 것이 SHOULD된다. 해당되는 경우 메타데이터 링크를 포함하는 것이 SHOULD된다.

전체 대체 또는 부분 패치를 통해 기존 [served resource]의 상태를 수정한다.

• 입력: 대상 식별자, 새 콘텐츠 및 선택적 동시성 제약 조건.
• 동작: 서버는 변경을 원자적으로 적용한다. 동시성 제약 조건이 제공된 경우, 요청자가 마지막으로 읽은 이후 리소스가 수정되었다면 갱신이 거부된다.
• 결과: 갱신 확인 또는 충돌 알림.

리소스 갱신은 PUT 요청(전체 리소스를 대체) 또는 PATCH 요청(부분 수정을 적용)을 통해 기존 제공되는 리소스의 콘텐츠를 수정한다. 클라이언트는 이러한 작업을 수행하려면 리소스 URL에 대한 쓰기 접근 권한을 가져야 한다. 참고: 이 절은 리소스의 기본 콘텐츠 갱신을 설명한다. 그 메타데이터를 갱신하려면 제9.3.2절을 참조하라. LWS 서버는 리소스 URI에 대한 PUT 및 PATCH 요청을 리소스 콘텐츠에 대한 수정으로만 처리해야 하며, 연결된 linkset 리소스에는 기본적으로 영향을 주지 않아야 한다. 콘텐츠와 메타데이터를 하나의 원자적 작업으로 선택적으로 갱신하려면, 클라이언트는 리소스 URI에 대한 PUT/PATCH 요청에 Link 헤더를 포함하고 'Prefer: set-linkset' 선호사항(RFC 7240에 정의됨)을 지정할 MAY 있다. 이 경우, 서버는 제공된 Link 헤더를 콘텐츠 변경 적용과 더불어 linkset에 대한 대체(PUT의 경우) 또는 부분 갱신(PATCH의 경우)으로 해석해야 한다. 이 동작은 서버에게 OPTIONAL이지만, 지원되는 경우 의도하지 않은 메타데이터 덮어쓰기를 방지하기 위해 Prefer 헤더를 통해 명시적으로 호출되어야 한다. 결합 갱신을 지원하지 않는 서버는 선호사항을 무시하거나 501 Not Implemented로 응답해야 한다.

PUT (전체 리소스 대체) – 리소스 URI에 PUT을 보내며, 본문에는 새 전체 콘텐츠를, Content-Type에는 일치하는 유형(일반적으로 기존 유형과 일관됨)을 포함한다. PUT은 기존 리소스에 대해 멱등적이다. 안전을 위해 현재 ETag와 함께 If-Match를 포함한다(제7.3절 동시성 참조). 불일치하면 412 Precondition Failed 또는 409 Conflict가 발생한다. 검사 없이 갱신은 무조건적이지만 동시 변경을 덮어쓸 위험이 있다. 서버가 리소스에 대해 Etags를 지원하는 경우, If-Match 헤더가 없는 무조건 PUT 요청을 428 Precondition Required 응답으로 거부해야 한다.

예시(리소스를 갱신하기 위한 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 리소스를 갱신하고 있다. 이전 GET 또는 HEAD 요청에서 얻은 ETag "abc123456"을 If-Match 헤더에 포함한다. 서버는 이를 현재 ETag와 비교한다. 일치하면, 제공된 JSON으로 콘텐츠를 대체한다. 일치하지 않으면, 서버는 갱신을 거부한다(그 사이 다른 사람이 리소스를 변경했기 때문). 성공 응답: 갱신이 성공하면, 서버는 200 OK로 응답하고 갱신된 표현 또는 일부 확인 정보 (예: 새 콘텐츠 또는 그 일부)를 포함할 수 있다. 또는 서버는 본문 없이 성공을 나타내기 위해 204 No Content로 응답할 수 있다(특히 추가 정보 전달이 필요하지 않은 경우 흔함). 어느 경우든, 서버는 새 버전을 나타내는 새 ETag를 포함하는 것이 SHOULD되며, 본문이 반환되는 경우 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 서버는 [RFC7386]에 정의된 JSON Merge Patch (application/merge-patch+json)를 최소한 지원해야 한다.

리소스 메타데이터 갱신(HTTP PUT / PATCH on Linkset) 리소스의 메타데이터는 rel="linkset"이 있는 Link 헤더를 통해 발견되는 해당 linkset 리소스를 수정하여 갱신된다. 전체 대체(PUT): 전체 linkset 문서를 본문에 담아 linkset 리소스 URI에 PUT 요청을 보내면 리소스의 모든 메타데이터가 대체된다. 부분 갱신(PATCH): linkset 리소스 URI에 대한 PATCH 요청은 특정 링크를 추가, 제거 또는 수정한다.

메타데이터에 대한 동시성 제어 리소스의 메타데이터는 여러 행위자가 수정할 수 있으므로, 동시 덮어쓰기를 방지하는 것이 중요하다. 데이터 무결성을 보장하기 위해, LWS 서버와 클라이언트는 linkset 리소스에 대한 모든 PUT 및 PATCH 작업에서 조건부 요청 [RFC7232]을 사용하는 낙관적 동시성 제어를 구현해야 한다. 서버 책임: 서버는 linkset 리소스에 대한 GET 및 HEAD 요청 응답에 Etag 헤더를 포함해야 한다. linkset에 대한 PUT 또는 PATCH가 성공하면, 서버는 수정된 linkset에 대해 새롭고 고유한 Etag 값을 생성하고 응답의 Etag 헤더에 반환해야 한다. 클라이언트 책임: linkset 리소스를 수정할 때, 클라이언트는 해당 리소스에 대해 가장 최근에 받은 Etag를 포함하는 If-Match 헤더를 포함해야 한다. 처리 규칙: If-Match 헤더 값이 linkset의 현재 Etag와 일치하지 않으면, 서버는 412 Precondition Failed 상태 코드로 요청을 거부해야 한다. linkset URI에 대한 PUT 또는 PATCH 요청에서 If-Match 헤더가 누락된 경우, 서버는 428 Precondition Required 상태 코드 [RFC6585]로 요청을 거부해야 한다. 예시(linkset을 대체하기 위한 PUT): 클라이언트가 먼저 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한다. 콘텐츠와 링크를 모두 변경하려는 경우 → 적절한 Link 헤더와 'Prefer: set-linkset'을 포함하여 리소스 자체에 PUT/PATCH한다. 둘을 모두 설정하는 것은 기본적으로 꺼져 있다.

리소스와 그 연결된 메타데이터를 영구적으로 제거한다.

• 입력: 대상 식별자, 선택적 재귀 플래그(컨테이너의 경우), 및 선택적 동시성 제약 조건.
• 동작:
  • 컨테이너가 아닌 리소스의 경우, 서버는 콘텐츠, 메타데이터를 제거하고 부모 컨테이너의 구성원 관계를 갱신한다.
  • 컨테이너의 경우, 재귀 삭제가 명시적으로 요청되고 지원되지 않는 한 서버는 일반적으로 컨테이너가 비어 있을 것을 요구한다.
• 결과: 제거 확인 또는 실패 알림.

리소스 삭제 작업은 위의 추상 작업에서 정의한 대로 HTTP DELETE 메서드를 사용하여 구현된다. 이 절은 입력, 동작 및 응답에 대한 HTTP 바인딩을 지정한다.

DELETE 요청은 제거할 리소스 또는 컨테이너의 URI를 대상으로 한다. 클라이언트는 동시성 검사를 위해 ETag가 있는 If-Match 헤더를 포함할 MAY 있다.

삭제 및 포함 관계: 리소스가 삭제되면, 서버는 이를 부모 컨테이너의 items 목록에서 원자적으로 제거해야 한다. 부모 컨테이너의 totalItems 개수는 그에 따라 갱신되는 것이 SHOULD되며, 그 ETag는 변경을 반영하도록 갱신되어야 한다.

컨테이너가 아닌 리소스의 경우, 서버는 리소스 콘텐츠, 그 연결된 메타데이터(linkset 리소스), 그리고 부모 컨테이너의 포함 관계 참조를 제거한다.

컨테이너 리소스의 경우, 서버는 기본적으로 비재귀 삭제를 사용한다. 컨테이너가 비어 있지 않고 재귀가 요청되지 않은 경우, 서버는 409 Conflict로 요청을 거부해야 한다. 서버는 삭제되는 컨테이너 내의 모든 포함 리소스에 대한 재귀 삭제를 지원할 MAY 있다. 클라이언트는 [RFC4918]에 정의된 대로 재귀 삭제를 요청하기 위해 Depth: infinity 헤더를 사용해야 한다.

성공 시, 서버는 204 No Content로 응답해야 한다. 서버는 [RFC9110]에 정의된 조건부 요청을 지원하는 것이 SHOULD된다.

클라이언트에게 권한이 없는 경우, 서버는 403 Forbidden(클라이언트의 식별자는 알려져 있지만 권한이 부족한 경우) 또는 401 Unauthorized(유효한 인증이 제공되지 않은 경우)를 반환해야 한다. 리소스 존재를 드러내는 것이 보안 위험을 야기하는 경우, 서버는 대신 404 Not Found를 반환할 MAY 있다.

예시(컨테이너가 아닌 리소스 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인 서비스 객체를 반드시 게시해야 한다.

서비스 객체는 값이 구독 엔드포인트의 URI인 serviceEndpoint 속성을 반드시 포함해야 한다. 서비스 객체는 값이 문자열 배열이며, 각 문자열이 지원되는 구독 유형을 식별하는 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"
}

스토리지는 해당 스토리지 설명 리소스에서 접근 요청 및 접근 권한 부여 지원을 게시할 수 있다. 이러한 지원을 게시하는 경우, 접근 요청 엔드포인트를 설명하는 서비스 객체는 문자열 AccessRequestService와 동일한 type을 반드시 가져야 하며, 접근 권한 부여 엔드포인트를 설명하는 서비스 객체는 문자열 AccessGrantService와 동일한 type을 반드시 가져야 한다. 서비스 객체는 값이 해당 엔드포인트에서 지원되는 접근 프로필을 식별하는 하나 이상의 URI 컬렉션인 conformsTo 속성을 포함하는 것이 좋다. 추가 속성을 포함할 수 있다.

{
  "@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 객체를 표현하는 데이터 객체이다. ODRL 개념을 사용하여 접근 요청을 설명하는 프로필은 11.3 접근 프로필에서 설명한다.

다음 예제는 접근 요청을 보여 준다. 이 예제는 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 작업은 새 리소스의 URL로 설정된 Location 헤더를 사용하여 반드시 응답해야 한다.

알림은 접근 요청 및 접근 권한 부여의 변경 사항을 에이전트와 스토리지 제어자에게 알리는 메커니즘을 제공한다. 접근 요청 또는 접근 권한 부여에 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"
    }
  ]
}