- A storage description resource provides information a client can use + A storage description resource provides information a client can use when interacting with a storage, including descriptions of capabilities and service endpoints.
diff --git a/lws10-core/IANA-Considerations.html b/lws10-core/IANA-Considerations.html index b64ee10..0e344c9 100644 --- a/lws10-core/IANA-Considerations.html +++ b/lws10-core/IANA-Considerations.html @@ -45,22 +45,22 @@application/lws+json Media Type
- This specification registers the application/lws+json media type for identifying documents conforming to the
- linked web storage document format.
+ This specification registers the application/lws+json media type specifically for identifying documents
+ conforming to the Linked Web Storage container format.
application/lws+json media type are required to conform to
@@ -68,7 +68,21 @@ + Note that while the Linked Web Storage format uses JSON-LD conventions, there are a number of constraints and additional + requirements for LWS implementations that justify the use of a specific media type. +
+ +
+ Because LWS containers can be considered a restricted profile of JSON-LD, implementations SHOULD consider the
+ application/ld+json; profile="https://www.w3.org/ns/lws/v1" media type as equivalent to
+ application/lws+json.
+
items property in container representations and the rel="up" link relation in HTTP headers.@@ -208,6 +215,11 @@
diff --git a/lws10-core/jsonld-context.md b/lws10-core/jsonld-context.md new file mode 100644 index 0000000..7949e1d --- /dev/null +++ b/lws10-core/jsonld-context.md @@ -0,0 +1,62 @@ +### JSON-LD Context and Vocabulary + +#### Normative JSON-LD Context + +Container representations MUST include the following `@context` value: + +``` +"@context": "https://www.w3.org/ns/lws/v1" +``` + +The normative JSON-LD context document defines the mapping between the short property names used in container representations and their full URIs in the LWS and related vocabularies. The context is defined as follows: + +```json +{ + "@context": { + "@version": 1.1, + "@protected": true, + "lws": "https://www.w3.org/ns/lws#", + "as": "https://www.w3.org/ns/activitystreams#", + "schema": "https://schema.org/", + "xs": "http://www.w3.org/2001/XMLSchema#", + "id": "@id", + "type": "@type", + "Container": "lws:Container", + "DataResource": "lws:DataResource", + "items": "lws:items", + "totalItems": "as:totalItems", + "mediaType": "as:mediaType", + "size": { + "@id": "schema:size", + "@type": "xs:long" + }, + "modified": { + "@id": "as:updated", + "@type": "xs:dateTime" + } + } +} +``` + +The context is `@protected`, ensuring that the term definitions cannot be overridden by other contexts. + +#### Vocabulary + +The LWS vocabulary defines the following types and properties used in container representations: + +**Types:** + +| Term | URI | Description | +|------|-----|-------------| +| `Container` | `lws:Container` | A resource that contains other resources | +| `DataResource` | `lws:DataResource` | A data-bearing resource | + +**Properties:** + +| Term | URI | Description | +|------|-----|-------------| +| `items` | `lws:items` | The list of resources contained in a container | +| `totalItems` | `as:totalItems` | The total number of contained resources | +| `mediaType` | `as:mediaType` | The media type of a resource | +| `size` | `schema:size` | The size of a resource in bytes | +| `modified` | `as:updated` | The date-time a resource was last modified | diff --git a/lws10-core/logicalresourceorganization.md b/lws10-core/logicalresourceorganization.md index 2e50798..89143a6 100644 --- a/lws10-core/logicalresourceorganization.md +++ b/lws10-core/logicalresourceorganization.md @@ -1,24 +1,47 @@ -### Logical Resource Organization -This section delineates the abstract data model governing the organization of resources within the Linked Web Storage (LWS) system. It encompasses the structuring of containers and resources, their hierarchical interrelations, the functional semantics of containers as organizational units, rules pertaining to containment, and mechanisms for clients to organize and navigate resource collections. This model establishes the logical namespace of the storage, delineating inter-resource relationships therein, without presupposing any specific identifier structure or semantic implications derived from identifier composition. Logical organization MUST prioritize discoverability and self-descriptive APIs, avoiding hardcoded locations. Containment is represented as metadata to enable multiple containers per resource without URL changes, supporting sharing use cases. All entities MUST have associated metadata resources using Link Sets (RFC 9264), distinguishing server-managed and user-managed data. +### Container Model -### Resource -In LWS, a resource constitutes the fundamental unit of storage and access. Each resource possesses a unique identifier within the system. A resource may encompass data, such as content or structured information, alongside associated metadata, including attributes like type or modification timestamps. Resources MUST be classified as 'DataResource', 'Container', or 'MetadataResource' via metadata types. DataResources MAY have multiple representations; servers MUST track original media types and support reification in metadata using the 'representation' property, which includes 'mediaType' and optional 'sizeInBytes'. +Linked Web Storage organizes resources into containers. A container is a specialized resource that holds references to other resources, called its members. Containers serve +as organizational units, analogous to directories or collections, enabling clients to group, discover, and navigate resources. A container maintains references to its member resources, +which may comprise both non-container resources and additional container resources, thereby enabling hierarchical formations. Typically, a container holds minimal intrinsic content +beyond metadata or enumerations of its members; its principal role is to aggregate and structure subordinate resources. The storage system's root is designated as a container, serving +as the apex organizational unit devoid of a superior parent. Containers MUST support pagination for membership listings using 'ContainerPage' types, with properties such as 'first', +'next', 'prev', and 'last'. Representations MUST use JSON-LD with a specific frame and normative context, optionally advertising content negotiation via 'Vary: Accept' headers. +Storage MAY function as a root container, enabling direct writes. -### Container -A container is a specialized resource capable of encompassing other resources as members. Containers function as organizational constructs, facilitating the grouping of resources in a manner akin to collections or directories. A container maintains references to its member resources, which may comprise both non-container resources and additional container resources, thereby enabling hierarchical formations. Typically, a container holds minimal intrinsic content beyond metadata or enumerations of its members; its principal role is to aggregate and structure subordinate resources. The storage system's root is designated as a container, serving as the apex organizational unit devoid of a superior parent. Containers MUST support pagination for membership listings using 'ContainerPage' types, with properties such as 'first', 'next', 'prev', and 'last'. Representations MUST use JSON-LD with a specific frame and normative context, optionally advertising content negotiation via 'Vary: Accept' headers. Storage MAY function as a root container, enabling direct writes. +Every LWS storage has a **root container** that serves as the top-level organizational unit. The root container has no parent and acts as the entry point for the storage hierarchy. -### Containment and Hierarchy -With the exception of the root container, every resource is affiliated with precisely one parent container. This affiliation engenders a strict hierarchical structure, manifesting as a tree with a singular root container at its pinnacle. Upon creation within a designated container, a new resource becomes a member of that container, appearing within its membership enumeration. Cycles or multiple parent affiliations are prohibited within this model; a resource cannot concurrently belong to multiple containers without duplication or alternative referencing mechanisms external to the core containment framework. This constraint enhances model simplicity and aligns with conventional organizational paradigms. Containment MUST be modeled as metadata links using 'contains' (from container to member) and 'partOf' (from member to container), allowing transitive queries and multiple hierarchies without slash semantics. Servers MAY support hierarchy arrays for ancestors. +Resources in LWS are classified as either: -### Container Membership Management -Operations involving the creation, deletion, or relocation of resources influence container memberships as follows: -- Upon creation, a new resource is associated with a specified parent container. This association integrates the resource into the parent's membership. -- Deletion of a resource entails its removal from the parent container's membership. Should this render the container devoid of members, it assumes an empty state, potentially permitting its subsequent deletion if warranted. Container deletion typically necessitates an empty state or invokes recursive removal of members. -- The core operations (create, read, update, delete) do not incorporate an explicit relocation or renaming function. To reassign a resource to an alternative container, a client may replicate or recreate the resource in the target location followed by deletion of the original. Implementations may optionally extend non-core operations for relocation or renaming, achievable logically through combined creation and deletion. -Membership is managed via create/delete operations; direct updates to membership listings are server-managed and not client-writable to avoid concurrency issues. +- **Container** — a resource that contains other resources. +- **DataResource** — a data-bearing resource (e.g., a document, image, or structured data file). -### Container Creation -Container instantiation occurs via the standard resource creation operation (Section 7.1), differentiated by an indicator specifying the intent to establish a container rather than a non-container resource. This process yields an empty container amenable to subsequent population with members, including sub-containers to extend the hierarchy. Servers MUST assign identifiers, and empty containers MUST be supported. +### Containment -### Navigating and Listing Resources -Clients navigate the hierarchy through read operations on containers, which yield enumerations of member identifiers. A container's representation furnishes a listing of its members, enabling traversal and discovery of subordinate resources. Listings MUST include metadata for each member, such as resource IDs (MUST), types (array of system and user-defined), representations (MUST for DataResources, including mediaType and optional sizeInBytes), and modified timestamps (SHOULD). \ No newline at end of file +The containment relationship between a resource and its parent container is expressed via the `rel="up"` link relation. Servers MUST include a `Link` header with `rel="up"` pointing to the parent container in responses to GET and HEAD requests on any non-root resource. + +``` +Link: ; rel="up" +``` + +A container's members are listed in its representation using the `items` property. The server manages this list; clients cannot modify it directly. Membership changes occur as a side effect of resource creation and deletion. + +### Containment Integrity + +The server MUST maintain containment integrity at all times: + +- **Creation**: When a new resource is created in a container, the server MUST atomically add the resource to the container's `items` list. +- **Deletion**: When a resource is deleted, the server MUST atomically remove it from its parent container's `items` list. Deleting a container requires the container to be empty, unless recursive deletion is explicitly requested. +- **No orphans**: Every non-root resource MUST be reachable from the root container through the containment hierarchy. +- **No cycles**: A container MUST NOT directly or indirectly contain itself. + +### Resource Identification + +Resources are identified by URIs. The URI of a resource is independent of its position in the containment hierarchy. Servers assign URIs during resource creation and MAY incorporate client hints (e.g., the `Slug` header), but clients SHOULD NOT assume that URI structure reflects containment. + +Containment relationships are expressed through metadata (`rel="up"` links and the `items` property in container representations), not through URI path structure. This separation allows servers flexibility in URI assignment while maintaining a well-defined organizational model. + +### Container Membership and Authorization + +If a client has read access to a container, the container representation MUST include the identifiers for all resources contained in that container to which the client has access. It MAY also contain the identifiers for resources contained in that container to which the client does not have access. + +A client's ability to read a container listing does not imply access to the contained resources themselves, and vice versa. diff --git a/lws10-core/lws-media-type.md b/lws10-core/lws-media-type.md new file mode 100644 index 0000000..5f56618 --- /dev/null +++ b/lws10-core/lws-media-type.md @@ -0,0 +1,15 @@ +### LWS Media Type + +LWS container representation and storage description resource MUST use the media type `application/lws+json`. + +While LWS container representations use JSON-LD conventions, the constraints and requirements for LWS justify the use of a specific media type. Because LWS containers can be considered a restricted profile of JSON-LD, implementations SHOULD consider the `application/ld+json; profile="https://www.w3.org/ns/lws/v1"` media type as equivalent to `application/lws+json`. + +#### Content Negotiation + +Servers MUST support content negotiation for container representations. The response payload MUST be identical regardless of the requested media type — only the `Content-Type` response header varies: + +- If a client requests `application/lws+json`, the server MUST respond with `Content-Type: application/lws+json`. +- If a client requests `application/ld+json`, the server MUST respond with `Content-Type: application/ld+json`. +- If a client requests `application/json`, the server MUST respond with `Content-Type: application/json`. + +In all three cases, the response body is the same JSON-LD document conforming to the LWS container vocabulary. Servers are free to support additional media types (e.g., `text/turtle`) through content negotiation.