Pod Resources#

ESS provides/hosts Solid Pods. Pods are data storage locations.

Resource Types#

ESS Pods supports storing different types of resources.

Resource Description Framework (RDF) Resource#

A Resource Description Framework (RDF) resource is a file whose contents consists of statements (also known as triples) that describe some “subject” by its relationships:

<subject> <predicate> <object>

The predicate describes the relationship between the subject and the object.

For more information, see RDF Data Model.

Container#

A Container is an RDF resource that can contain other Containers as well as RDF and non-RDF resources. It is analogous to a folder in a file system.

Important

Container URLs always end with a slash /.

Non-RDF Resource#

A non-RDF Resource is any non-RDF binary or text file, such as .pdf , .jpeg, etc.

CRUD Operations#

ESS supports the Solid Protocol specification. As such, retrieving, creating, deleting and editing Solid Resources within a Pod is directly supported via the standard HTTP interfaces.

Access Control#

This section summarizes the relationship between Create/Read/Update/Delete (CRUD) operations and the required access modes.

To create a resource, the user requires either an Append or Write access.

Note

The creation operation creates the resource (be it container, RDF resource, non-RDF resource) and updates the content of the parent container with the new resource’s metadata.

Resource	Description
Container	Either `Append` or `Write` access on the parent container (under which the new container is to be created) allows agents to create a new container. For example, to create `https://storage..../parentcontainer/newContainer/`, either an `Append` or a `Write` access on `https://storage..../parentcontainer/` allows agents to create `https://storage..../parentcontainer/newContainer/`.
RDF resource	Either `Append` or `Write` access on the parent container (under which the new resource is to be created) allows agents to create a RDF resource. For example, to create `https://storage..../parentcontainer/newResource/`, either an `Append` or a `Write` access on `https://storage..../parentcontainer/` allows agents to create `https://storage..../parentcontainer/newResource`.
Non-RDF resource	Either `Append` or `Write` access on the parent container (under which the new resource is to be created) allows agents to create a new non-RDF resource. For example, to create `https://storage..../parentcontainer/foo.jpg`, an `Append` or `Write` access on `https://storage..../parentcontainer/` allows agents to create `https://storage..../parentcontainer/foo.jpg`.

Resource

Description

Container

Either Append or Write access on the parent container (under which the new container is to be created) allows agents to create a new container.

For example, to create https://storage..../parentcontainer/newContainer/, either an Append or a Write access on https://storage..../parentcontainer/ allows agents to create https://storage..../parentcontainer/newContainer/.

RDF resource

Either Append or Write access on the parent container (under which the new resource is to be created) allows agents to create a RDF resource.

For example, to create https://storage..../parentcontainer/newResource/, either an Append or a Write access on https://storage..../parentcontainer/ allows agents to create https://storage..../parentcontainer/newResource.

Non-RDF resource

Either Append or Write access on the parent container (under which the new resource is to be created) allows agents to create a new non-RDF resource.

For example, to create https://storage..../parentcontainer/foo.jpg, an Append or Write access on https://storage..../parentcontainer/ allows agents to create https://storage..../parentcontainer/foo.jpg.

For read operations [1], the user requires Read access.

Resource	Description
Container	`Read` access on the target container (analogous to a folder in a file system) allow agents to read/retrieve the container as a resource (not the resource(s) under the container). That is, Read access only affects read operation on the container itself. Reading a container (which stores metadata about the resources contained within the container) allows a client to discover what resources are contained inside the container and their resource type (i.e., analogous to an `ls` on a folder in a file system).
RDF resource	`Read` access on the RDF resource allows agents to read/retrieve the resource (regardless of the access on the parent container). For example, if a resource has as its URL `https://storage..../container/ResourceToRead`, to read/retrieve this resource: The user must have `Read` access on `https://storage..../container/ResourceToRead`. The user’s access on `https://storage..../container/` is immaterial.
Non-RDF resource	`Read` access on a non-RDF resource allows agents to read/retrieve the resource (regardless of Read access on the container). For example, if a non-RDF resource has as its URL `https://storage..../container/foo.jpg`, to read/retrieve this resource: The user must have `Read` access on `https://storage..../container/foo.jpg`. The user’s access on `https://storage..../container/` is immaterial.

Resource

Description

Container

Read access on the target container (analogous to a folder in a file system) allow agents to read/retrieve the container as a resource (not the resource(s) under the container). That is, Read access only affects read operation on the container itself.

Reading a container (which stores metadata about the resources contained within the container) allows a client to discover what resources are contained inside the container and their resource type (i.e., analogous to an ls on a folder in a file system).

RDF resource

Read access on the RDF resource allows agents to read/retrieve the resource (regardless of the access on the parent container).

For example, if a resource has as its URL https://storage..../container/ResourceToRead, to read/retrieve this resource:

The user must have Read access on https://storage..../container/ResourceToRead.
The user’s access on https://storage..../container/ is immaterial.

Non-RDF resource

Read access on a non-RDF resource allows agents to read/retrieve the resource (regardless of Read access on the container).

For example, if a non-RDF resource has as its URL https://storage..../container/foo.jpg, to read/retrieve this resource:

The user must have Read access on https://storage..../container/foo.jpg.
The user’s access on https://storage..../container/ is immaterial.

For update operations, the user requires Append or Write access, depending on the specific update operation.

Resource	Description
Resource	Description
Container	To add resources to the Container, see the `Create` tab. To delete resources from the Container, see the `Delete` tab.
RDF resource	Either `Append` or `Write` access on an RDF resource allows agents to add content (statements) to the resource. `Write` access on an RDF resource allows agents to delete content (statements) from the resource. `Write` access on an RDF resource allows agents to modify existing content (statements) in the resource.
Non-RDF resource	`Write` access on the target resource allows agents to overwrite/replace the resource (regardless of the access on the parent container). For example, if the non-RDF resource has as its URL `https://storage..../container/foo.jpg`, to overwrite this resource: The user must have `Write` access on `https://storage..../container/foo.jpg`. The user’s access on `https://storage..../container/` is immaterial.

For delete operations, the user requires Write access.

Resource	Description
Container	`Write` access on both the parent container and the target container allows agents to delete the target container. For example, to delete `https://storage..../parentcontainer/containerToDelete/`, `Write` access on both `https://storage..../parentcontainer/` and `https://storage..../parentcontainer/containerToDelete/` allows agents to delete `https://storage..../parentcontainer/containerToDelete/`. Tip To delete a container, the container must be empty.
RDF resource	To delete an RDF resource , `Write` access on both the parent container and the target resource allows agents to delete the target resource. For example, to delete `https://storage..../parentcontainer/resourceToDelete/`, `Write` access on both `https://storage..../parentcontainer/` and `https://storage..../parentcontainer/resourceToDelete` allows agents to delete `https://storage..../parentcontainer/resourceToDelete`.
Non-RDF resource	To delete a non-RDF resource, `Write` access on both the parent container and the target resource allows agents to delete the target resource. For example, to delete `https://storage..../parentcontainer/foo.jpg`, `Write` access on both `https://storage..../parentcontainer/` and `https://storage..../parentcontainer/foo.jpg` allows agents to delete `https://storage..../parentcontainer/foo.jpg`.

Resource

Description

Container

Write access on both the parent container and the target container allows agents to delete the target container.

For example, to delete https://storage..../parentcontainer/containerToDelete/, Write access on both https://storage..../parentcontainer/ and https://storage..../parentcontainer/containerToDelete/ allows agents to delete https://storage..../parentcontainer/containerToDelete/.

Tip

To delete a container, the container must be empty.

RDF resource

To delete an RDF resource , Write access on both the parent container and the target resource allows agents to delete the target resource.

For example, to delete https://storage..../parentcontainer/resourceToDelete/, Write access on both https://storage..../parentcontainer/ and https://storage..../parentcontainer/resourceToDelete allows agents to delete https://storage..../parentcontainer/resourceToDelete.

Non-RDF resource

To delete a non-RDF resource, Write access on both the parent container and the target resource allows agents to delete the target resource.

For example, to delete https://storage..../parentcontainer/foo.jpg, Write access on both https://storage..../parentcontainer/ and https://storage..../parentcontainer/foo.jpg allows agents to delete https://storage..../parentcontainer/foo.jpg.

Other Considerations#

Resource Deletion#

For resource deletions, ESS uses soft deletes. That is, ESS marks the resource as deleted but does not perform an actual delete from the data store. The use of soft deletes can:

Help maintain throughput when compared to database delete operations that may be potentially costly due to locking.
Facilitate disaster recovery.
Be part of a data-retention strategy.

Note

Overwriting a resource (file) with a new resource (file) also results in a soft delete of the old version of the resource.

Overwriting a resource with a new resource is separate from an operation that just modifies the contents of a resource. Instead, modification of the contents (even though the modification may completely replace the contents) results in orphan data.

Starting in 2.1, ESS provides the ability to schedule hard deletes for the soft deleted resources

Modification of Resource Content#

When data in a file is modified or deleted, the old data remains but is no longer referenced by metadata. That is, the replaced/deleted data is orphaned.

Starting in 2.1, ESS provides the ability to schedule hard deletes for the orphan data.

Note

The modification/deletion of the data is separate from overwriting a file with a new file. Overwriting a file does not result in orphan data. Instead, overwriting a file with a new file results in a soft delete of the old version of the file.

Initial Access Policies#

When a Pod is created, like any other Pod resource, an Access Control Resource is also created for the Pod Root. The ACR is initialized with default ACP policies.

The initial policies give the Pod Owner read and write access to the Pod. These policies also specify a client matcher as well if the Authorization service’s configuration for the initial client allow list is set:

INRUPT_AUTHORIZATION_DEFAULT_ACR_CLIENT_ID_ALLOW_LIST or if that is unset,
INRUPT_AUTHORIZATION_CLIENT_ID_ALLOW_LIST.

Disambiguation

Both Authorization Service and Pod Storage Service have a INRUPT_AUTHORIZATION_CLIENT_ID_ALLOW_LIST setting.

Only the Authorization Service setting affects which clients are allowed. The Pod Storage Service is for Discovery purposes only.

A Pod’s Initial Policies are set when the Pod is provisioned. As such, updates to the operator-controlled allow lists do not affect existing Pods.

Note

Starting in 2.1, ESS uses the values in its Authorization service’s INRUPT_AUTHORIZATION_DEFAULT_ACR_CLIENT_ID_ALLOW_LIST (at the time of Pod creation) to create the client matcher for the initial ACP policies. If the setting is unset, ESS uses the values in its Authorization service’s INRUPT_AUTHORIZATION_CLIENT_ID_ALLOW_LIST (at the time of Pod creation).

Using the value of the Pod owner’s WebID and an initial client allow list, ESS creates the initial policies of the form:

If allOf(AgentMatcher and ClientMatcher) evaluates to true, Then allow (Read and Write).

Specifically, ESS creates:

Policy 1 for the Pod Root:

If the agent matches the Pod owner’s WebID, and if the client application’s Client ID has a match in the initial client allow list, allow Read and Write access.

Policy 2 for the Pod Root’s Initial Member Policies:

If the agent matches the Pod owner’s WebID, and if the client application’s Client ID has a match in the initial client allow list, allow Read and Write access.

For more information on a Container’s Member Policies, see Member Policies.

Note

Starting in 2.1, ESS uses the values in Authorization service’s INRUPT_AUTHORIZATION_DEFAULT_ACR_CLIENT_ID_ALLOW_LIST (at the time of Pod creation) to create the client matcher for the initial policies. If the setting is unset, ESS uses the values in its Authorization service’s INRUPT_AUTHORIZATION_CLIENT_ID_ALLOW_LIST (at the time of Pod creation).

If the initial client allow list is empty (when creating the policy), ESS uses the value of the Pod owner’s WebID to create initial policies of the form:

If allOf(AgentMatcher) evaluates to true, Then allow (Read and Write).

Specifically, ESS creates:

Policy 1 for the Pod Root:

If the agent matches the Pod owner’s WebID, allow Read and Write access.

Policy 2 for the Pod Root’s Initial Member Policies:

If the agent matches the Pod owner’s WebID, allow Read and Write access.

For more information on a Container’s Member Policies, see Member Policies.

Note

After a Pod’s initial policies have been created, changes to INRUPT_AUTHORIZATION_DEFAULT_ACR_CLIENT_ID_ALLOW_LIST (or INRUPT_AUTHORIZATION_CLIENT_ID_ALLOW_LIST) do not impact the Pod’s policies.