From c75cca6b25e2763fcf36d200cc8fbdf1c49178e8 Mon Sep 17 00:00:00 2001 From: Justin Bingham Date: Tue, 3 Dec 2019 23:19:23 -0500 Subject: [PATCH 01/27] initial commit of resource metadata hypothesis --- resource-metadata/README.md | 7 +++ resource-metadata/hypothesis.md | 103 ++++++++++++++++++++++++++++++++ 2 files changed, 110 insertions(+) create mode 100644 resource-metadata/README.md create mode 100644 resource-metadata/hypothesis.md diff --git a/resource-metadata/README.md b/resource-metadata/README.md new file mode 100644 index 00000000..ef2c80a5 --- /dev/null +++ b/resource-metadata/README.md @@ -0,0 +1,7 @@ +# Resource Metadata in Solid + +A project undertaken by the [Data Interoperability Panel](https://github.com/solid/data-interoperability-panel). + +## Goal + +The aim of this project is to produce a candidate proposal to the [Solid Specification](https://github.com/solid/specification) that defines a mechanism for how metadata (i.e. access control, shape constraints) is associated and accessed for a given resource. diff --git a/resource-metadata/hypothesis.md b/resource-metadata/hypothesis.md new file mode 100644 index 00000000..7e5f31a3 --- /dev/null +++ b/resource-metadata/hypothesis.md @@ -0,0 +1,103 @@ +# Resource Metadata Model + +## Background + +This document introduces a mechanism for linking to metadata about resources in the Solid Ecosystem using HTTP Link headers. Examples of this linking mechanism include: + +- A binary JPEG image with a Link header, pointing to a description that has an RDF representation. +- An LDP container with a Link header, pointing to an ACL resource that governs access controls for the contained resources. +- A resource whose shape is constrained by a ShEx document includes a Link header that points to that ShEx resource. +- A resource may keep an audit trail of modification events. A client could follow the URI in a Link header to access that audit trail. + +A given resource might link to zero or more such related metadata representations. Having a unified model to describe how clients and servers interact with and process these resources will help clarify expectations, while also providing a shared pattern for extending the features of server implementations. + +The metadata model described in this document makes it possible for clients to decorate resources with structured descriptive data. Those metadata may serve as supplementary descriptions or, when supported by a server implementation, they may influence the behavior of the resources. + +Some examples include: + +- An ACL resource controls how a server makes authorization decisions for a container and any child resources. +- A shape constraint resource may limit the RDF structures that can be added to a resource or container. +- A “configuration” resource may control how a resource is versioned, or which indexes are exposed for it. + +Access to different categories of metadata may require different levels of privilege, which must be specified as part of the definition of a given metadata type. + +## Discovery +Given the URL of a resource or container, a client can discover the metadata resources by issuing a GET (or HEAD) request and inspecting the Link headers in the response. The rel= attribute will define the relationship to the target URL. [https://tools.ietf.org/html/rfc8288] + +For any defined metadata type available for a given resource, all representations of that resource MUST include a Link header pointing to the location of each metadata resource. For example, as defined by the Solid Web Access Control specification, a client can use this mechanism to discover the location of an ACL resource: + +Link: ; rel="acl" + +### Discovery of Annotated Resource + +Certain metadata resource types MAY require the server to include a link back to the annotated resource using an appropriate link relation. For example, LDP defines a bidirectional discovery mechanism for RDF descriptions of NonRDF resources, via Link headers: + +Link: ; rel="description" + +along with: + +Link: ; rel="describedby" + +For cases where link relations are not defined by IANA, a URL can be used. For example: + +Link: ; + rel="https://example.org/ns#hasMetadata" + +and: + +Link: ; + rel="https://example.org/ns#isMetadataOf" + +String-based link relations, such as in the examples above, must be registered with IANA. But it is also possible to use custom relation types by using a full IRI. The Linked Data Platform, the Linked Data Notification and the Web Annotation specifications make use of full IRIs in the rel attribute. + +## Reserved resource metadata types + +### Web Access Control + +ACL resources as defined by Web Access Control. MUST be supported. + +Discovered via ```rel=acl``` +and ```rel=http://www.w3.org/ns/solid/terms#resource``` + +### Resource Description + +Resource description provides a general mechanism for resource annotation, such as for providing descriptive metadata for a binary file. MUST be supported. + +Discovered via ```rel=describedby``` and ```rel=describes``` + +### Shape Constraint + +Enforces conformance of the resource to an associated SHACL or ShEx data shape. MUST be supported. + +Discovered via ```rel=http://www.w3.org/ns/solid/terms#shape``` and ```rel=http://www.w3.org/ns/solid/terms#resource``` + +### Server Managed + +Server-managed metadata not otherwise included in HTTP headers. MUST be supported. + +Discovered via ```rel=http://www.w3.org/ns/solid/terms#metadata``` and ```rel=http://www.w3.org/ns/solid/terms#resource``` + +### Configuration + +Configuration metadata, e.g. settings for memento creation. MUST be supported. + +Discovered via ```rel=http://www.w3.org/ns/solid/terms#configuration``` + +## Non-Reserved Types + +A server may support other metadata types. + +## Implementation Patterns + +There are many ways a server could implement these features. A file-based server could have a special naming scheme reserved for these metadata resources. Alternatively, a server could represent every resource internally as a dataset, storing each separate type of metadata in its own named graph. + +[ Include example of file based ] + +[ Include example of graph based ] + +## Open Questions + +* Should we stipulate whether metadata resources MUST or SHOULD be RDF? +* Can all clients see links to all metadata associated with a given document as a general rule, or should this be something defined for each individual type of metadata? +* Should anchor= be used rather than rel= for the discovery of an annotated resource (see [RFC 5988](https://tools.ietf.org/html/rfc5988)) +* Should there be portability requirements for certain metadata types? For example, acls should be portable so that if a given user moves their data from once implementation to another, their acl should go along, but certain implementation specific metadata may not. From edd6c705d1a9abe2c257fb17ca464f7afcd2750f Mon Sep 17 00:00:00 2001 From: Justin Bingham Date: Tue, 3 Dec 2019 23:30:48 -0500 Subject: [PATCH 02/27] added lifecycle --- resource-metadata/hypothesis.md | 21 +++++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) diff --git a/resource-metadata/hypothesis.md b/resource-metadata/hypothesis.md index 7e5f31a3..f3ce6e37 100644 --- a/resource-metadata/hypothesis.md +++ b/resource-metadata/hypothesis.md @@ -54,20 +54,25 @@ String-based link relations, such as in the examples above, must be registered w ### Web Access Control -ACL resources as defined by Web Access Control. MUST be supported. +ACL resources as defined by Web Access Control. MUST be supported. MUST be deleted when resource is deleted. -Discovered via ```rel=acl``` -and ```rel=http://www.w3.org/ns/solid/terms#resource``` +Authorization: acl:Control + +Discovered via ```rel=acl``` and ```rel=http://www.w3.org/ns/solid/terms#resource``` ### Resource Description -Resource description provides a general mechanism for resource annotation, such as for providing descriptive metadata for a binary file. MUST be supported. +Resource description provides a general mechanism for resource annotation, such as for providing descriptive metadata for a binary file. MUST be supported. MUST be deleted when resource is deleted. + +Authorization: acl:Read, acl:Write Discovered via ```rel=describedby``` and ```rel=describes``` ### Shape Constraint -Enforces conformance of the resource to an associated SHACL or ShEx data shape. MUST be supported. +Enforces conformance of the resource to an associated SHACL or ShEx data shape. MUST be supported. MUST be deleted when resource is deleted. + +Authorization: acl:Control Discovered via ```rel=http://www.w3.org/ns/solid/terms#shape``` and ```rel=http://www.w3.org/ns/solid/terms#resource``` @@ -75,11 +80,15 @@ Discovered via ```rel=http://www.w3.org/ns/solid/terms#shape``` and ```rel=http: Server-managed metadata not otherwise included in HTTP headers. MUST be supported. +__Note: This may be too broad to be able to properly determine what the authorization rule, or lifecycle should be. May need to consider breaking this up into specific types.__ + Discovered via ```rel=http://www.w3.org/ns/solid/terms#metadata``` and ```rel=http://www.w3.org/ns/solid/terms#resource``` ### Configuration -Configuration metadata, e.g. settings for memento creation. MUST be supported. +Configuration metadata, e.g. settings for memento creation. MUST be supported. MUST be deleted when resource is deleted. + +Authorization: acl:Control Discovered via ```rel=http://www.w3.org/ns/solid/terms#configuration``` From 91f96d87e3fe02a42ae83391d5b8f0945acdcaa6 Mon Sep 17 00:00:00 2001 From: Justin Bingham Date: Tue, 3 Dec 2019 23:32:41 -0500 Subject: [PATCH 03/27] remove containment reference --- resource-metadata/hypothesis.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/resource-metadata/hypothesis.md b/resource-metadata/hypothesis.md index f3ce6e37..5d4fc847 100644 --- a/resource-metadata/hypothesis.md +++ b/resource-metadata/hypothesis.md @@ -22,7 +22,7 @@ Some examples include: Access to different categories of metadata may require different levels of privilege, which must be specified as part of the definition of a given metadata type. ## Discovery -Given the URL of a resource or container, a client can discover the metadata resources by issuing a GET (or HEAD) request and inspecting the Link headers in the response. The rel= attribute will define the relationship to the target URL. [https://tools.ietf.org/html/rfc8288] +Given the URL of a resource, a client can discover the metadata resources by issuing a GET (or HEAD) request and inspecting the Link headers in the response. The rel= attribute will define the relationship to the target URL. [https://tools.ietf.org/html/rfc8288] For any defined metadata type available for a given resource, all representations of that resource MUST include a Link header pointing to the location of each metadata resource. For example, as defined by the Solid Web Access Control specification, a client can use this mechanism to discover the location of an ACL resource: From 74d04b841c059f115082cd88d8fbe83f2179b4ea Mon Sep 17 00:00:00 2001 From: Justin Bingham Date: Wed, 4 Dec 2019 15:19:31 -0500 Subject: [PATCH 04/27] adjust authz --- resource-metadata/hypothesis.md | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/resource-metadata/hypothesis.md b/resource-metadata/hypothesis.md index 5d4fc847..687ddf32 100644 --- a/resource-metadata/hypothesis.md +++ b/resource-metadata/hypothesis.md @@ -54,9 +54,17 @@ String-based link relations, such as in the examples above, must be registered w ### Web Access Control -ACL resources as defined by Web Access Control. MUST be supported. MUST be deleted when resource is deleted. +Related Issues: +https://github.com/solid/specification/issues/58 +https://github.com/solid/specification/issues/42 +https://github.com/solid/specification/issues/31 +https://github.com/solid/specification/issues/131 -Authorization: acl:Control +ACL resources as defined by [Web Access Control](https://github.com/solid/web-access-control-spec) MUST be supported. + +MUST be deleted when resource is deleted. + +Authorization Model: Discovered via ```rel=acl``` and ```rel=http://www.w3.org/ns/solid/terms#resource``` @@ -64,7 +72,7 @@ Discovered via ```rel=acl``` and ```rel=http://www.w3.org/ns/solid/terms#resourc Resource description provides a general mechanism for resource annotation, such as for providing descriptive metadata for a binary file. MUST be supported. MUST be deleted when resource is deleted. -Authorization: acl:Read, acl:Write +Authorization Model: Discovered via ```rel=describedby``` and ```rel=describes``` @@ -72,7 +80,7 @@ Discovered via ```rel=describedby``` and ```rel=describes``` Enforces conformance of the resource to an associated SHACL or ShEx data shape. MUST be supported. MUST be deleted when resource is deleted. -Authorization: acl:Control +Authorization Model: Discovered via ```rel=http://www.w3.org/ns/solid/terms#shape``` and ```rel=http://www.w3.org/ns/solid/terms#resource``` @@ -88,7 +96,7 @@ Discovered via ```rel=http://www.w3.org/ns/solid/terms#metadata``` and ```rel=ht Configuration metadata, e.g. settings for memento creation. MUST be supported. MUST be deleted when resource is deleted. -Authorization: acl:Control +Authorization Model: Discovered via ```rel=http://www.w3.org/ns/solid/terms#configuration``` @@ -110,3 +118,4 @@ There are many ways a server could implement these features. A file-based server * Can all clients see links to all metadata associated with a given document as a general rule, or should this be something defined for each individual type of metadata? * Should anchor= be used rather than rel= for the discovery of an annotated resource (see [RFC 5988](https://tools.ietf.org/html/rfc5988)) * Should there be portability requirements for certain metadata types? For example, acls should be portable so that if a given user moves their data from once implementation to another, their acl should go along, but certain implementation specific metadata may not. +* How do you connect the resource with an ACL when you create it From d7debd22274db3269b280f68f456f473e447cfe5 Mon Sep 17 00:00:00 2001 From: Justin Bingham Date: Tue, 31 Dec 2019 06:50:26 -0500 Subject: [PATCH 05/27] update acl, shape, and resource description --- resource-metadata/hypothesis.md | 113 ++++++++++++++++++++++++-------- 1 file changed, 86 insertions(+), 27 deletions(-) diff --git a/resource-metadata/hypothesis.md b/resource-metadata/hypothesis.md index 687ddf32..3deeb9da 100644 --- a/resource-metadata/hypothesis.md +++ b/resource-metadata/hypothesis.md @@ -2,6 +2,8 @@ ## Background +*This section is non-normative* + This document introduces a mechanism for linking to metadata about resources in the Solid Ecosystem using HTTP Link headers. Examples of this linking mechanism include: - A binary JPEG image with a Link header, pointing to a description that has an RDF representation. @@ -19,10 +21,10 @@ Some examples include: - A shape constraint resource may limit the RDF structures that can be added to a resource or container. - A “configuration” resource may control how a resource is versioned, or which indexes are exposed for it. -Access to different categories of metadata may require different levels of privilege, which must be specified as part of the definition of a given metadata type. +Access to different categories of metadata may require different levels of privilege, which must be specified as part of the definition for a given metadata type. -## Discovery -Given the URL of a resource, a client can discover the metadata resources by issuing a GET (or HEAD) request and inspecting the Link headers in the response. The rel= attribute will define the relationship to the target URL. [https://tools.ietf.org/html/rfc8288] +## Metadata Discovery +Given the URL of a resource, a client can discover the metadata resources by issuing a GET (or HEAD) request and inspecting the Link headers in the response. The [rel= attribute](https://tools.ietf.org/html/rfc8288) will define the relationship to the target URL. For any defined metadata type available for a given resource, all representations of that resource MUST include a Link header pointing to the location of each metadata resource. For example, as defined by the Solid Web Access Control specification, a client can use this mechanism to discover the location of an ACL resource: @@ -50,53 +52,63 @@ Link: ; String-based link relations, such as in the examples above, must be registered with IANA. But it is also possible to use custom relation types by using a full IRI. The Linked Data Platform, the Linked Data Notification and the Web Annotation specifications make use of full IRIs in the rel attribute. -## Reserved resource metadata types +## Metadata Characteristics + +A given resource MAY Link to metadata on a different server. + +Metadata resources on the same Solid server MUST follow the [LDPR interaction model](https://www.w3.org/TR/ldp/#ldpr-gen-linktypehdr). + +## Reserved Metadata Types ### Web Access Control -Related Issues: -https://github.com/solid/specification/issues/58 -https://github.com/solid/specification/issues/42 -https://github.com/solid/specification/issues/31 -https://github.com/solid/specification/issues/131 +ACL resources as defined by [Web Access Control](https://github.com/solid/web-access-control-spec) MUST be supported as a resource metadata type by Solid servers. -ACL resources as defined by [Web Access Control](https://github.com/solid/web-access-control-spec) MUST be supported. +ACL metadata resources are discoverable by the client via ```rel=acl``` and ```rel=http://www.w3.org/ns/solid/terms#resource``` -MUST be deleted when resource is deleted. +An ACL metadata resource MUST be deleted when the resource it is directly associated with is also deleted and the two resources reside on the same Solid server. -Authorization Model: +To access or manage an ACL meta resource, an [acl:agent](https://github.com/solid/web-access-control-spec#describing-agents) MUST have [acl:Control](https://github.com/solid/web-access-control-spec#aclcontrol) privileges per the [ACL inheritance algorithm](https://github.com/solid/web-access-control-spec#acl-inheritance-algorithm) on the resource directly associated with it. -Discovered via ```rel=acl``` and ```rel=http://www.w3.org/ns/solid/terms#resource``` +A Solid server SHOULD sanity check ACL metadata resources upon creation or update to restrict invalid changes. ### Resource Description -Resource description provides a general mechanism for resource annotation, such as for providing descriptive metadata for a binary file. MUST be supported. MUST be deleted when resource is deleted. +Resource description is a general mechanism to provide descriptive metadata for a given resource. It MUST be supported as a resource metadata type by Solid servers. + +The Descriptive metadata resource for a given resource is discovered via ```rel=describedby```. Conversely, the resource being described by a Descriptive metadata resource is discovered via ```rel=describes```. + +A Descriptive metadata resource MUST be deleted when the resource it is directly associated with is also deleted and the two resources reside on the same Solid server. + +Access or management of a Descriptive metadata resource by a given [acl:agent](https://github.com/solid/web-access-control-spec#describing-agents) is subject to the [modes of access](https://github.com/solid/web-access-control-spec#modes-of-access) granted per the [ACL inheritance algorithm](https://github.com/solid/web-access-control-spec#acl-inheritance-algorithm) on the resource directly associated with it. + +### Shape Validation -Authorization Model: +Shape Validation ensures that any data changes in a given resource conform to an associated [SHACL](https://www.w3.org/TR/shacl/) or [ShEx](https://shex.io/shex-semantics/index.html) data shape. It MUST be supported as a resource metadata type by Solid servers. -Discovered via ```rel=describedby``` and ```rel=describes``` +The Shape validation metadata resource for a given resource is discovered via ```rel=http://www.w3.org/ns/solid/terms#shape``` and ```rel=http://www.w3.org/ns/solid/terms#resource```. -### Shape Constraint +.```OPEN QUESTION - Should the link be directly to the shape resource (which is often not going to be on the same server)? Should it be to a local resource that in turn points to the shape (wherever it is), but can also include configuration parameters on the nature of the validation? The latter would seem to provide much more flexibility in the long run.``` -Enforces conformance of the resource to an associated SHACL or ShEx data shape. MUST be supported. MUST be deleted when resource is deleted. +A Shape validation metadata resource MUST be deleted when the resource it is directly associated with is also deleted and the two resources reside on the same Solid server. ```Note: Assumes that we follow the local resource pointing to shape approach``` -Authorization Model: +To access or manage a Shape validation metadata resource, an [acl:agent](https://github.com/solid/web-access-control-spec#describing-agents) MUST have [acl:Control](https://github.com/solid/web-access-control-spec#aclcontrol) privileges per the [ACL inheritance algorithm](https://github.com/solid/web-access-control-spec#acl-inheritance-algorithm) on the resource directly associated with it. -Discovered via ```rel=http://www.w3.org/ns/solid/terms#shape``` and ```rel=http://www.w3.org/ns/solid/terms#resource``` +A Solid server SHOULD sanity check Shape validation metadata resources upon creation or update to restrict invalid changes. ### Server Managed -Server-managed metadata not otherwise included in HTTP headers. MUST be supported. +*This section is still in process* -__Note: This may be too broad to be able to properly determine what the authorization rule, or lifecycle should be. May need to consider breaking this up into specific types.__ +Server-managed metadata not otherwise included in HTTP headers. MUST be supported. -Discovered via ```rel=http://www.w3.org/ns/solid/terms#metadata``` and ```rel=http://www.w3.org/ns/solid/terms#resource``` +Discovered via ```rel=http://www.w3.org/ns/solid/terms#server``` and ```rel=http://www.w3.org/ns/solid/terms#resource``` ### Configuration -Configuration metadata, e.g. settings for memento creation. MUST be supported. MUST be deleted when resource is deleted. +*This section is still in process* -Authorization Model: +Configuration metadata, e.g. settings for memento creation. MUST be supported. MUST be deleted when resource is deleted. Discovered via ```rel=http://www.w3.org/ns/solid/terms#configuration``` @@ -106,11 +118,15 @@ A server may support other metadata types. ## Implementation Patterns +*This section is non-normative.* + There are many ways a server could implement these features. A file-based server could have a special naming scheme reserved for these metadata resources. Alternatively, a server could represent every resource internally as a dataset, storing each separate type of metadata in its own named graph. -[ Include example of file based ] +A server needs to maintain a working knowledge of which resources are metadata, because it tells the clients where to find them. This means that it can similarly apply this knowledge to know when someone is writing to a known metadata resource, such as an ACL, and can apply the appropriate validation and sanity checks to ensure the changes are valid. + +# Draft Resources -[ Include example of graph based ] +This section and the content inside it is meant to aid in the drafting process, and will not be included in the candidate proposal submitted to the specification. The purpose of this section is to aid those contributing to or reviewing this document. ## Open Questions @@ -119,3 +135,46 @@ There are many ways a server could implement these features. A file-based server * Should anchor= be used rather than rel= for the discovery of an annotated resource (see [RFC 5988](https://tools.ietf.org/html/rfc5988)) * Should there be portability requirements for certain metadata types? For example, acls should be portable so that if a given user moves their data from once implementation to another, their acl should go along, but certain implementation specific metadata may not. * How do you connect the resource with an ACL when you create it + +## Additional References + +[Solid Content Representation Spec](https://github.com/solid/solid-spec/blob/master/content-representation.md) - This is the original component specification document (circa 2016) that defined a metadata discovery mechanism using Link headers. + +Notable issues: +- [Specify approach for resource metadata](https://github.com/solid/specification/issues/102) +- [Specify metadata mechanism for Containers, RDFResources, NonRDFResources](https://github.com/solid/specification/issues/63) +- [Clarify the lifecycle of an ACL resource](https://github.com/solid/specification/issues/58) +- [Proposal: server-protected metadata](https://github.com/solid/specification/issues/65) +- [Methods for ACL resource creation](https://github.com/solid/specification/issues/42) +- [How does the server determine whether a resource is an ACL resource](https://github.com/solid/specification/issues/31) +- [Atomicity of creating a resource and its ACL](https://github.com/solid/specification/issues/131) +- [ACL for meta resources](https://github.com/solid/solid/issues/130) +- [How should we handle metadata of non-RDF sources](https://github.com/solid/solid-spec/issues/197) +- [How to delete metadata file?](https://github.com/solid/solid-spec/issues/168) +- [When a resource is deleted, should the acl be deleted too?](https://github.com/solid/solid/issues/251) +- [When deleting a resources, should the corresponding ACL document be deleted?](https://github.com/solid/solid-spec/issues/187) +- [Explain the ACL inheritance algorithm for clients](https://github.com/solid/specification/issues/106) + +Items/themes that are raised in the issues above and should be addressed in some form: + +- Reconfirm use of describedby as a way to get to meta information (#63) +- Specify whether or not metadata should be handled as regular rdf resources (it should be) - probably should put this in the opening section. +- Specify the semantics of meta information for containers (#63) + - Take a look at current NSS use of .meta for containers +- Clarify whether metadata for a container counts towards it being empty or not (#63) +- Specify semantics of meta for NonRDFResources (#63) +- Specify semantics of meta for RDFResources (#63) +- Clarify permissioning of .meta resources (#63) + - Can a client always read metadata? + - Can a client always know the metadata is there (e.g. link headers are advertised) + - What if the user wants to provide access to the file but not the file metadata? +- Clarify the lifecycle of .meta resources (#63, #58) + - [Consensus](https://github.com/solid/specification/issues/31) that deleting a resource must remove associated ACL resource +- Specify how .meta resources get serialized (#63) +- Differentiate user-writeable metadata from server-protected metadata (#63, #65) + - For a given piece of metadata, it is + - only readable and writeable by the server (e.g. internal indexing) + - readable by any client subject to permissions on resource, but only written by the server (e.g. timestamps) + - readable and writeable by any client subject to permissions on resource (i can set the shape constraint, or read/write the acl) +- Determine whether we should point out the actual ACL resource in use in a new link header (timbl suggestion, ruben created issue). Discussed in #31, proposed in #106 +- Can you create an ACL resource in advance, or at the time of creation of the resource itself? (#131) From 1686364b98400aae5fe04ab558e14ce1e7cb3c24 Mon Sep 17 00:00:00 2001 From: Justin Bingham Date: Tue, 7 Jan 2020 15:11:34 -0500 Subject: [PATCH 06/27] grammer correction. Co-Authored-By: Ted Thibodeau Jr --- resource-metadata/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/resource-metadata/README.md b/resource-metadata/README.md index ef2c80a5..ce576b4b 100644 --- a/resource-metadata/README.md +++ b/resource-metadata/README.md @@ -4,4 +4,4 @@ A project undertaken by the [Data Interoperability Panel](https://github.com/sol ## Goal -The aim of this project is to produce a candidate proposal to the [Solid Specification](https://github.com/solid/specification) that defines a mechanism for how metadata (i.e. access control, shape constraints) is associated and accessed for a given resource. +The aim of this project is to produce a candidate proposal to the [Solid Specification](https://github.com/solid/specification) that defines a mechanism for how metadata (such as access control or shape constraints) is associated and accessed for a given resource. From 426fb0656185daf6b3b8e927b4f9a7c166d7025e Mon Sep 17 00:00:00 2001 From: Justin Bingham Date: Tue, 7 Jan 2020 15:27:09 -0500 Subject: [PATCH 07/27] link to w3 specs Co-Authored-By: Ted Thibodeau Jr --- resource-metadata/hypothesis.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/resource-metadata/hypothesis.md b/resource-metadata/hypothesis.md index 3deeb9da..12afea35 100644 --- a/resource-metadata/hypothesis.md +++ b/resource-metadata/hypothesis.md @@ -50,7 +50,7 @@ and: Link: ; rel="https://example.org/ns#isMetadataOf" -String-based link relations, such as in the examples above, must be registered with IANA. But it is also possible to use custom relation types by using a full IRI. The Linked Data Platform, the Linked Data Notification and the Web Annotation specifications make use of full IRIs in the rel attribute. +String-based link relations, such as in the examples above, must be registered with IANA. But it is also possible to use custom relation types by using a full IRI. The [Linked Data Platform](https://www.w3.org/TR/ldp/), the [Linked Data Notifications](https://www.w3.org/TR/ldn/), and the [Web Annotation Protocol](http://www.w3.org/TR/annotation-protocol/) specifications make use of full IRIs in the `rel` attribute. ## Metadata Characteristics From 17790041f9fa6237afadc8b717d4de3ad9391124 Mon Sep 17 00:00:00 2001 From: Justin Bingham Date: Wed, 8 Jan 2020 11:55:27 -0500 Subject: [PATCH 08/27] add types and incorporate feedback --- resource-metadata/hypothesis.md | 42 +++++++++++++++------------------ 1 file changed, 19 insertions(+), 23 deletions(-) diff --git a/resource-metadata/hypothesis.md b/resource-metadata/hypothesis.md index 12afea35..fead3f73 100644 --- a/resource-metadata/hypothesis.md +++ b/resource-metadata/hypothesis.md @@ -30,6 +30,8 @@ For any defined metadata type available for a given resource, all representation Link: ; rel="acl" +Metadata discovered through a Link header for a given resource is considered to be *directly associated* with that resource. + ### Discovery of Annotated Resource Certain metadata resource types MAY require the server to include a link back to the annotated resource using an appropriate link relation. For example, LDP defines a bidirectional discovery mechanism for RDF descriptions of NonRDF resources, via Link headers: @@ -56,7 +58,7 @@ String-based link relations, such as in the examples above, must be registered w A given resource MAY Link to metadata on a different server. -Metadata resources on the same Solid server MUST follow the [LDPR interaction model](https://www.w3.org/TR/ldp/#ldpr-gen-linktypehdr). +Metadata resources on the same Solid server MUST adhere to the same interaction model used by standard Solid resources. ## Reserved Metadata Types @@ -64,9 +66,9 @@ Metadata resources on the same Solid server MUST follow the [LDPR interaction mo ACL resources as defined by [Web Access Control](https://github.com/solid/web-access-control-spec) MUST be supported as a resource metadata type by Solid servers. -ACL metadata resources are discoverable by the client via ```rel=acl``` and ```rel=http://www.w3.org/ns/solid/terms#resource``` +ACL metadata resources are discoverable by the client via ```rel=acl```. -An ACL metadata resource MUST be deleted when the resource it is directly associated with is also deleted and the two resources reside on the same Solid server. +An ACL metadata resource MUST be deleted when the resource it is directly associated with is also deleted and the Solid server is authoritative for both resources. To access or manage an ACL meta resource, an [acl:agent](https://github.com/solid/web-access-control-spec#describing-agents) MUST have [acl:Control](https://github.com/solid/web-access-control-spec#aclcontrol) privileges per the [ACL inheritance algorithm](https://github.com/solid/web-access-control-spec#acl-inheritance-algorithm) on the resource directly associated with it. @@ -76,9 +78,9 @@ A Solid server SHOULD sanity check ACL metadata resources upon creation or updat Resource description is a general mechanism to provide descriptive metadata for a given resource. It MUST be supported as a resource metadata type by Solid servers. -The Descriptive metadata resource for a given resource is discovered via ```rel=describedby```. Conversely, the resource being described by a Descriptive metadata resource is discovered via ```rel=describes```. +The Descriptive metadata resource for a given resource is discovered via ```rel=describedby```. Conversely, the resource being described by a Descriptive metadata resource is discovered via ```rel=http://www.w3.org/ns/solid/terms#resource```. -A Descriptive metadata resource MUST be deleted when the resource it is directly associated with is also deleted and the two resources reside on the same Solid server. +A Descriptive metadata resource MUST be deleted when the resource it is directly associated with is also deleted and the Solid server is authoritative for both resources. Access or management of a Descriptive metadata resource by a given [acl:agent](https://github.com/solid/web-access-control-spec#describing-agents) is subject to the [modes of access](https://github.com/solid/web-access-control-spec#modes-of-access) granted per the [ACL inheritance algorithm](https://github.com/solid/web-access-control-spec#acl-inheritance-algorithm) on the resource directly associated with it. @@ -86,11 +88,9 @@ Access or management of a Descriptive metadata resource by a given [acl:agent](h Shape Validation ensures that any data changes in a given resource conform to an associated [SHACL](https://www.w3.org/TR/shacl/) or [ShEx](https://shex.io/shex-semantics/index.html) data shape. It MUST be supported as a resource metadata type by Solid servers. -The Shape validation metadata resource for a given resource is discovered via ```rel=http://www.w3.org/ns/solid/terms#shape``` and ```rel=http://www.w3.org/ns/solid/terms#resource```. - -.```OPEN QUESTION - Should the link be directly to the shape resource (which is often not going to be on the same server)? Should it be to a local resource that in turn points to the shape (wherever it is), but can also include configuration parameters on the nature of the validation? The latter would seem to provide much more flexibility in the long run.``` +The Shape validation metadata resource for a given resource is discovered via ```rel=http://www.w3.org/ns/solid/terms#shape```. Conversely, the resource being described by a Shape validation metadata resource is discovered via ```rel=http://www.w3.org/ns/solid/terms#resource```. -A Shape validation metadata resource MUST be deleted when the resource it is directly associated with is also deleted and the two resources reside on the same Solid server. ```Note: Assumes that we follow the local resource pointing to shape approach``` +A Shape validation metadata resource MUST be deleted when the resource it is directly associated with is also deleted and the Solid server is authoritative for both resources. To access or manage a Shape validation metadata resource, an [acl:agent](https://github.com/solid/web-access-control-spec#describing-agents) MUST have [acl:Control](https://github.com/solid/web-access-control-spec#aclcontrol) privileges per the [ACL inheritance algorithm](https://github.com/solid/web-access-control-spec#acl-inheritance-algorithm) on the resource directly associated with it. @@ -98,19 +98,23 @@ A Solid server SHOULD sanity check Shape validation metadata resources upon crea ### Server Managed -*This section is still in process* +A Solid server stores information about a resource that clients can read but not change in Server Managed metadata. It MUST be supported as a resource metadata type by Solid servers. + +A Server Managed metadata resource is Discovered via ```rel=http://www.w3.org/ns/solid/terms#server```. Conversely, the resource being described by a Server Managed metadata resource is discovered via ```rel=http://www.w3.org/ns/solid/terms#resource```. -Server-managed metadata not otherwise included in HTTP headers. MUST be supported. +A Server Managed metadata resource MUST be deleted when the resource it is directly associated with is also deleted and the Solid server is authoritative for both resources. -Discovered via ```rel=http://www.w3.org/ns/solid/terms#server``` and ```rel=http://www.w3.org/ns/solid/terms#resource``` +To access a Server Managed metadata resource, an [acl:agent](https://github.com/solid/web-access-control-spec#describing-agents) MUST have [acl:Read](https://github.com/solid/web-access-control-spec#aclread) privileges per the [ACL inheritance algorithm](https://github.com/solid/web-access-control-spec#acl-inheritance-algorithm) on the resource directly associated with it. ### Configuration -*This section is still in process* +Configuration metadata is used to store configurable parameters for a given resource. It MUST be supported as a resource metadata type by Solid servers. -Configuration metadata, e.g. settings for memento creation. MUST be supported. MUST be deleted when resource is deleted. +A configuration metadata resource is discovered via ```rel=http://www.w3.org/ns/solid/terms#configuration```. Conversely, the resource being described by a Configuration metadata resource is discovered via ```rel=http://www.w3.org/ns/solid/terms#resource```. -Discovered via ```rel=http://www.w3.org/ns/solid/terms#configuration``` +A Configuration metadata resource MUST be deleted when the resource it is directly associated with is also deleted and the Solid server is authoritative for both resources. + +To access or manage a Configuration metadata resource, an [acl:agent](https://github.com/solid/web-access-control-spec#describing-agents) MUST have [acl:Control](https://github.com/solid/web-access-control-spec#aclcontrol) privileges per the [ACL inheritance algorithm](https://github.com/solid/web-access-control-spec#acl-inheritance-algorithm) on the resource directly associated with it. ## Non-Reserved Types @@ -128,14 +132,6 @@ A server needs to maintain a working knowledge of which resources are metadata, This section and the content inside it is meant to aid in the drafting process, and will not be included in the candidate proposal submitted to the specification. The purpose of this section is to aid those contributing to or reviewing this document. -## Open Questions - -* Should we stipulate whether metadata resources MUST or SHOULD be RDF? -* Can all clients see links to all metadata associated with a given document as a general rule, or should this be something defined for each individual type of metadata? -* Should anchor= be used rather than rel= for the discovery of an annotated resource (see [RFC 5988](https://tools.ietf.org/html/rfc5988)) -* Should there be portability requirements for certain metadata types? For example, acls should be portable so that if a given user moves their data from once implementation to another, their acl should go along, but certain implementation specific metadata may not. -* How do you connect the resource with an ACL when you create it - ## Additional References [Solid Content Representation Spec](https://github.com/solid/solid-spec/blob/master/content-representation.md) - This is the original component specification document (circa 2016) that defined a metadata discovery mechanism using Link headers. From b740995f61c37cfdf27e764ca89ca837c08b53bd Mon Sep 17 00:00:00 2001 From: Justin Bingham Date: Wed, 8 Jan 2020 11:57:54 -0500 Subject: [PATCH 09/27] Update formatting Co-Authored-By: Ted Thibodeau Jr --- resource-metadata/hypothesis.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/resource-metadata/hypothesis.md b/resource-metadata/hypothesis.md index fead3f73..cb7b7b0b 100644 --- a/resource-metadata/hypothesis.md +++ b/resource-metadata/hypothesis.md @@ -24,7 +24,7 @@ Some examples include: Access to different categories of metadata may require different levels of privilege, which must be specified as part of the definition for a given metadata type. ## Metadata Discovery -Given the URL of a resource, a client can discover the metadata resources by issuing a GET (or HEAD) request and inspecting the Link headers in the response. The [rel= attribute](https://tools.ietf.org/html/rfc8288) will define the relationship to the target URL. +Given the URL of a resource, a client can discover the metadata resources by issuing a `GET` (or `HEAD`) request and inspecting the `Link` headers in the response. The [`rel={attribute}`](https://tools.ietf.org/html/rfc8288) will define the relationship to the target URL. For any defined metadata type available for a given resource, all representations of that resource MUST include a Link header pointing to the location of each metadata resource. For example, as defined by the Solid Web Access Control specification, a client can use this mechanism to discover the location of an ACL resource: From a311c5e8cafc46573dc0f81cc17fd33f8344ee68 Mon Sep 17 00:00:00 2001 From: Justin Bingham Date: Thu, 9 Jan 2020 14:53:16 -0500 Subject: [PATCH 10/27] Grammar adjustments Co-Authored-By: Ted Thibodeau Jr --- resource-metadata/hypothesis.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/resource-metadata/hypothesis.md b/resource-metadata/hypothesis.md index cb7b7b0b..a91454cd 100644 --- a/resource-metadata/hypothesis.md +++ b/resource-metadata/hypothesis.md @@ -68,7 +68,7 @@ ACL resources as defined by [Web Access Control](https://github.com/solid/web-ac ACL metadata resources are discoverable by the client via ```rel=acl```. -An ACL metadata resource MUST be deleted when the resource it is directly associated with is also deleted and the Solid server is authoritative for both resources. +An ACL metadata resource MUST be deleted when the resource it is directly associated with is deleted and the Solid server is authoritative for both resources. To access or manage an ACL meta resource, an [acl:agent](https://github.com/solid/web-access-control-spec#describing-agents) MUST have [acl:Control](https://github.com/solid/web-access-control-spec#aclcontrol) privileges per the [ACL inheritance algorithm](https://github.com/solid/web-access-control-spec#acl-inheritance-algorithm) on the resource directly associated with it. @@ -80,7 +80,7 @@ Resource description is a general mechanism to provide descriptive metadata for The Descriptive metadata resource for a given resource is discovered via ```rel=describedby```. Conversely, the resource being described by a Descriptive metadata resource is discovered via ```rel=http://www.w3.org/ns/solid/terms#resource```. -A Descriptive metadata resource MUST be deleted when the resource it is directly associated with is also deleted and the Solid server is authoritative for both resources. +A Descriptive metadata resource MUST be deleted when the resource it is directly associated with is deleted and the Solid server is authoritative for both resources. Access or management of a Descriptive metadata resource by a given [acl:agent](https://github.com/solid/web-access-control-spec#describing-agents) is subject to the [modes of access](https://github.com/solid/web-access-control-spec#modes-of-access) granted per the [ACL inheritance algorithm](https://github.com/solid/web-access-control-spec#acl-inheritance-algorithm) on the resource directly associated with it. @@ -90,7 +90,7 @@ Shape Validation ensures that any data changes in a given resource conform to an The Shape validation metadata resource for a given resource is discovered via ```rel=http://www.w3.org/ns/solid/terms#shape```. Conversely, the resource being described by a Shape validation metadata resource is discovered via ```rel=http://www.w3.org/ns/solid/terms#resource```. -A Shape validation metadata resource MUST be deleted when the resource it is directly associated with is also deleted and the Solid server is authoritative for both resources. +A Shape validation metadata resource MUST be deleted when the resource it is directly associated with is deleted and the Solid server is authoritative for both resources. To access or manage a Shape validation metadata resource, an [acl:agent](https://github.com/solid/web-access-control-spec#describing-agents) MUST have [acl:Control](https://github.com/solid/web-access-control-spec#aclcontrol) privileges per the [ACL inheritance algorithm](https://github.com/solid/web-access-control-spec#acl-inheritance-algorithm) on the resource directly associated with it. @@ -102,7 +102,7 @@ A Solid server stores information about a resource that clients can read but not A Server Managed metadata resource is Discovered via ```rel=http://www.w3.org/ns/solid/terms#server```. Conversely, the resource being described by a Server Managed metadata resource is discovered via ```rel=http://www.w3.org/ns/solid/terms#resource```. -A Server Managed metadata resource MUST be deleted when the resource it is directly associated with is also deleted and the Solid server is authoritative for both resources. +A Server Managed metadata resource MUST be deleted when the resource it is directly associated with is deleted and the Solid server is authoritative for both resources. To access a Server Managed metadata resource, an [acl:agent](https://github.com/solid/web-access-control-spec#describing-agents) MUST have [acl:Read](https://github.com/solid/web-access-control-spec#aclread) privileges per the [ACL inheritance algorithm](https://github.com/solid/web-access-control-spec#acl-inheritance-algorithm) on the resource directly associated with it. @@ -112,7 +112,7 @@ Configuration metadata is used to store configurable parameters for a given reso A configuration metadata resource is discovered via ```rel=http://www.w3.org/ns/solid/terms#configuration```. Conversely, the resource being described by a Configuration metadata resource is discovered via ```rel=http://www.w3.org/ns/solid/terms#resource```. -A Configuration metadata resource MUST be deleted when the resource it is directly associated with is also deleted and the Solid server is authoritative for both resources. +A Configuration metadata resource MUST be deleted when the resource it is directly associated with is deleted and the Solid server is authoritative for both resources. To access or manage a Configuration metadata resource, an [acl:agent](https://github.com/solid/web-access-control-spec#describing-agents) MUST have [acl:Control](https://github.com/solid/web-access-control-spec#aclcontrol) privileges per the [ACL inheritance algorithm](https://github.com/solid/web-access-control-spec#acl-inheritance-algorithm) on the resource directly associated with it. From 885a8f848fc81790569703844fc90f7c8e320111 Mon Sep 17 00:00:00 2001 From: Justin Bingham Date: Wed, 15 Jan 2020 21:45:38 -0500 Subject: [PATCH 11/27] server and client clarification --- resource-metadata/hypothesis.md | 37 +++++++++++++++++---------------- 1 file changed, 19 insertions(+), 18 deletions(-) diff --git a/resource-metadata/hypothesis.md b/resource-metadata/hypothesis.md index fead3f73..5b476abd 100644 --- a/resource-metadata/hypothesis.md +++ b/resource-metadata/hypothesis.md @@ -11,22 +11,23 @@ This document introduces a mechanism for linking to metadata about resources in - A resource whose shape is constrained by a ShEx document includes a Link header that points to that ShEx resource. - A resource may keep an audit trail of modification events. A client could follow the URI in a Link header to access that audit trail. -A given resource might link to zero or more such related metadata representations. Having a unified model to describe how clients and servers interact with and process these resources will help clarify expectations, while also providing a shared pattern for extending the features of server implementations. +A given resource might link to zero or more such related metadata representations. Having a unified model to describe how clients and Solid servers interact with and process these resources will help clarify expectations, while also providing a shared pattern for extending the features of Solid server implementations. -The metadata model described in this document makes it possible for clients to decorate resources with structured descriptive data. Those metadata may serve as supplementary descriptions or, when supported by a server implementation, they may influence the behavior of the resources. +The metadata model described in this document makes it possible for clients to decorate resources with structured descriptive data. Those metadata may serve as supplementary descriptions or, when supported by a Solid server implementation, they may influence the behavior of the resources. Some examples include: -- An ACL resource controls how a server makes authorization decisions for a container and any child resources. +- An ACL resource controls how a Solid server makes authorization decisions for a container and any child resources. - A shape constraint resource may limit the RDF structures that can be added to a resource or container. - A “configuration” resource may control how a resource is versioned, or which indexes are exposed for it. Access to different categories of metadata may require different levels of privilege, which must be specified as part of the definition for a given metadata type. ## Metadata Discovery + Given the URL of a resource, a client can discover the metadata resources by issuing a GET (or HEAD) request and inspecting the Link headers in the response. The [rel= attribute](https://tools.ietf.org/html/rfc8288) will define the relationship to the target URL. -For any defined metadata type available for a given resource, all representations of that resource MUST include a Link header pointing to the location of each metadata resource. For example, as defined by the Solid Web Access Control specification, a client can use this mechanism to discover the location of an ACL resource: +For any defined metadata type available for a given resource, all representations of that resource MUST include a Link header pointing to the location of each metadata resource. For example, as defined by the Solid [Web Access Control specification](https://github.com/solid/web-access-control-spec), a client can use this mechanism to discover the location of an ACL resource: Link: ; rel="acl" @@ -34,7 +35,7 @@ Metadata discovered through a Link header for a given resource is considered to ### Discovery of Annotated Resource -Certain metadata resource types MAY require the server to include a link back to the annotated resource using an appropriate link relation. For example, LDP defines a bidirectional discovery mechanism for RDF descriptions of NonRDF resources, via Link headers: +Certain metadata resource types MAY require the Solid server to include a link back to the annotated resource using an appropriate link relation. For example, LDP defines a bidirectional discovery mechanism for RDF descriptions of NonRDF resources, via Link headers: Link: ; rel="description" @@ -68,9 +69,9 @@ ACL resources as defined by [Web Access Control](https://github.com/solid/web-ac ACL metadata resources are discoverable by the client via ```rel=acl```. -An ACL metadata resource MUST be deleted when the resource it is directly associated with is also deleted and the Solid server is authoritative for both resources. +An ACL metadata resource MUST be deleted by the Solid server when the resource it is directly associated with is also deleted and the Solid server is authoritative for both resources. -To access or manage an ACL meta resource, an [acl:agent](https://github.com/solid/web-access-control-spec#describing-agents) MUST have [acl:Control](https://github.com/solid/web-access-control-spec#aclcontrol) privileges per the [ACL inheritance algorithm](https://github.com/solid/web-access-control-spec#acl-inheritance-algorithm) on the resource directly associated with it. +To access or manage an ACL metadata resource, an [acl:agent](https://github.com/solid/web-access-control-spec#describing-agents) MUST have [acl:Control](https://github.com/solid/web-access-control-spec#aclcontrol) privileges per the [ACL inheritance algorithm](https://github.com/solid/web-access-control-spec#acl-inheritance-algorithm) on the resource directly associated with it. A Solid server SHOULD sanity check ACL metadata resources upon creation or update to restrict invalid changes. @@ -78,9 +79,9 @@ A Solid server SHOULD sanity check ACL metadata resources upon creation or updat Resource description is a general mechanism to provide descriptive metadata for a given resource. It MUST be supported as a resource metadata type by Solid servers. -The Descriptive metadata resource for a given resource is discovered via ```rel=describedby```. Conversely, the resource being described by a Descriptive metadata resource is discovered via ```rel=http://www.w3.org/ns/solid/terms#resource```. +The Descriptive metadata resource for a given resource is discovered by the client via ```rel=describedby```. Conversely, the resource being described by a Descriptive metadata resource is discovered by the client via ```rel=http://www.w3.org/ns/solid/terms#resource```. -A Descriptive metadata resource MUST be deleted when the resource it is directly associated with is also deleted and the Solid server is authoritative for both resources. +A Descriptive metadata resource MUST be deleted by the Solid server when the resource it is directly associated with is also deleted and the Solid server is authoritative for both resources. Access or management of a Descriptive metadata resource by a given [acl:agent](https://github.com/solid/web-access-control-spec#describing-agents) is subject to the [modes of access](https://github.com/solid/web-access-control-spec#modes-of-access) granted per the [ACL inheritance algorithm](https://github.com/solid/web-access-control-spec#acl-inheritance-algorithm) on the resource directly associated with it. @@ -88,9 +89,9 @@ Access or management of a Descriptive metadata resource by a given [acl:agent](h Shape Validation ensures that any data changes in a given resource conform to an associated [SHACL](https://www.w3.org/TR/shacl/) or [ShEx](https://shex.io/shex-semantics/index.html) data shape. It MUST be supported as a resource metadata type by Solid servers. -The Shape validation metadata resource for a given resource is discovered via ```rel=http://www.w3.org/ns/solid/terms#shape```. Conversely, the resource being described by a Shape validation metadata resource is discovered via ```rel=http://www.w3.org/ns/solid/terms#resource```. +The Shape validation metadata resource for a given resource is discovered by the client via ```rel=http://www.w3.org/ns/solid/terms#shape```. Conversely, the resource being described by a Shape validation metadata resource is discovered by the client via ```rel=http://www.w3.org/ns/solid/terms#resource```. -A Shape validation metadata resource MUST be deleted when the resource it is directly associated with is also deleted and the Solid server is authoritative for both resources. +A Shape validation metadata resource MUST be deleted by the Solid server when the resource it is directly associated with is also deleted and the Solid server is authoritative for both resources. To access or manage a Shape validation metadata resource, an [acl:agent](https://github.com/solid/web-access-control-spec#describing-agents) MUST have [acl:Control](https://github.com/solid/web-access-control-spec#aclcontrol) privileges per the [ACL inheritance algorithm](https://github.com/solid/web-access-control-spec#acl-inheritance-algorithm) on the resource directly associated with it. @@ -100,9 +101,9 @@ A Solid server SHOULD sanity check Shape validation metadata resources upon crea A Solid server stores information about a resource that clients can read but not change in Server Managed metadata. It MUST be supported as a resource metadata type by Solid servers. -A Server Managed metadata resource is Discovered via ```rel=http://www.w3.org/ns/solid/terms#server```. Conversely, the resource being described by a Server Managed metadata resource is discovered via ```rel=http://www.w3.org/ns/solid/terms#resource```. +A Server Managed metadata resource is discovered by the client via ```rel=http://www.w3.org/ns/solid/terms#servermanaged```. Conversely, the resource being described by a Server Managed metadata resource is discovered by the client via ```rel=http://www.w3.org/ns/solid/terms#resource```. -A Server Managed metadata resource MUST be deleted when the resource it is directly associated with is also deleted and the Solid server is authoritative for both resources. +A Server Managed metadata resource MUST be deleted by the Solid server when the resource it is directly associated with is also deleted and the Solid server is authoritative for both resources. To access a Server Managed metadata resource, an [acl:agent](https://github.com/solid/web-access-control-spec#describing-agents) MUST have [acl:Read](https://github.com/solid/web-access-control-spec#aclread) privileges per the [ACL inheritance algorithm](https://github.com/solid/web-access-control-spec#acl-inheritance-algorithm) on the resource directly associated with it. @@ -110,23 +111,23 @@ To access a Server Managed metadata resource, an [acl:agent](https://github.com/ Configuration metadata is used to store configurable parameters for a given resource. It MUST be supported as a resource metadata type by Solid servers. -A configuration metadata resource is discovered via ```rel=http://www.w3.org/ns/solid/terms#configuration```. Conversely, the resource being described by a Configuration metadata resource is discovered via ```rel=http://www.w3.org/ns/solid/terms#resource```. +A configuration metadata resource is discovered by the client via ```rel=http://www.w3.org/ns/solid/terms#configuration```. Conversely, the resource being described by a Configuration metadata resource is discovered by the client via ```rel=http://www.w3.org/ns/solid/terms#resource```. -A Configuration metadata resource MUST be deleted when the resource it is directly associated with is also deleted and the Solid server is authoritative for both resources. +A Configuration metadata resource MUST be deleted by the Solid server when the resource it is directly associated with is also deleted and the Solid server is authoritative for both resources. To access or manage a Configuration metadata resource, an [acl:agent](https://github.com/solid/web-access-control-spec#describing-agents) MUST have [acl:Control](https://github.com/solid/web-access-control-spec#aclcontrol) privileges per the [ACL inheritance algorithm](https://github.com/solid/web-access-control-spec#acl-inheritance-algorithm) on the resource directly associated with it. ## Non-Reserved Types -A server may support other metadata types. +A Solid server may support other metadata types. ## Implementation Patterns *This section is non-normative.* -There are many ways a server could implement these features. A file-based server could have a special naming scheme reserved for these metadata resources. Alternatively, a server could represent every resource internally as a dataset, storing each separate type of metadata in its own named graph. +There are many ways a Solid server could implement these features. A file-based Solid server could have a special naming scheme reserved for these metadata resources. Alternatively, a Solid server could represent every resource internally as a dataset, storing each separate type of metadata in its own named graph. -A server needs to maintain a working knowledge of which resources are metadata, because it tells the clients where to find them. This means that it can similarly apply this knowledge to know when someone is writing to a known metadata resource, such as an ACL, and can apply the appropriate validation and sanity checks to ensure the changes are valid. +A Solid server needs to maintain a working knowledge of which resources are metadata, because it tells the clients where to find them. This means that it can similarly apply this knowledge to know when someone is writing to a known metadata resource, such as an ACL, and can apply the appropriate validation and sanity checks to ensure the changes are valid. # Draft Resources From 52673a31a358d872eb30a3ad33ba29128895efdf Mon Sep 17 00:00:00 2001 From: Justin Bingham Date: Wed, 15 Jan 2020 21:46:22 -0500 Subject: [PATCH 12/27] move draft resources to readme --- resource-metadata/README.md | 47 +++++++++++++++++++++++++++++++++ resource-metadata/hypothesis.md | 47 --------------------------------- 2 files changed, 47 insertions(+), 47 deletions(-) diff --git a/resource-metadata/README.md b/resource-metadata/README.md index ce576b4b..4db86712 100644 --- a/resource-metadata/README.md +++ b/resource-metadata/README.md @@ -5,3 +5,50 @@ A project undertaken by the [Data Interoperability Panel](https://github.com/sol ## Goal The aim of this project is to produce a candidate proposal to the [Solid Specification](https://github.com/solid/specification) that defines a mechanism for how metadata (such as access control or shape constraints) is associated and accessed for a given resource. + +# Draft Resources + +This section and the content inside it is meant to aid those contributing to or reviewing the [draft proposal](hypothesis.md). + +## Additional References + +[Solid Content Representation Spec](https://github.com/solid/solid-spec/blob/master/content-representation.md) - This is the original component specification document (circa 2016) that defined a metadata discovery mechanism using Link headers. + +Notable issues: +- [Specify approach for resource metadata](https://github.com/solid/specification/issues/102) +- [Specify metadata mechanism for Containers, RDFResources, NonRDFResources](https://github.com/solid/specification/issues/63) +- [Clarify the lifecycle of an ACL resource](https://github.com/solid/specification/issues/58) +- [Proposal: server-protected metadata](https://github.com/solid/specification/issues/65) +- [Methods for ACL resource creation](https://github.com/solid/specification/issues/42) +- [How does the server determine whether a resource is an ACL resource](https://github.com/solid/specification/issues/31) +- [Atomicity of creating a resource and its ACL](https://github.com/solid/specification/issues/131) +- [ACL for meta resources](https://github.com/solid/solid/issues/130) +- [How should we handle metadata of non-RDF sources](https://github.com/solid/solid-spec/issues/197) +- [How to delete metadata file?](https://github.com/solid/solid-spec/issues/168) +- [When a resource is deleted, should the acl be deleted too?](https://github.com/solid/solid/issues/251) +- [When deleting a resources, should the corresponding ACL document be deleted?](https://github.com/solid/solid-spec/issues/187) +- [Explain the ACL inheritance algorithm for clients](https://github.com/solid/specification/issues/106) + +Items/themes that are raised in the issues above and should be addressed in some form: + +- Reconfirm use of describedby as a way to get to meta information (#63) +- Specify whether or not metadata should be handled as regular rdf resources (it should be) - probably should put this in the opening section. +- Specify the semantics of meta information for containers (#63) + - Take a look at current NSS use of .meta for containers +- Clarify whether metadata for a container counts towards it being empty or not (#63) +- Specify semantics of meta for NonRDFResources (#63) +- Specify semantics of meta for RDFResources (#63) +- Clarify permissioning of .meta resources (#63) + - Can a client always read metadata? + - Can a client always know the metadata is there (e.g. link headers are advertised) + - What if the user wants to provide access to the file but not the file metadata? +- Clarify the lifecycle of .meta resources (#63, #58) + - [Consensus](https://github.com/solid/specification/issues/31) that deleting a resource must remove associated ACL resource +- Specify how .meta resources get serialized (#63) +- Differentiate user-writeable metadata from server-protected metadata (#63, #65) + - For a given piece of metadata, it is + - only readable and writeable by the server (e.g. internal indexing) + - readable by any client subject to permissions on resource, but only written by the server (e.g. timestamps) + - readable and writeable by any client subject to permissions on resource (i can set the shape constraint, or read/write the acl) +- Determine whether we should point out the actual ACL resource in use in a new link header (timbl suggestion, ruben created issue). Discussed in #31, proposed in #106 +- Can you create an ACL resource in advance, or at the time of creation of the resource itself? (#131) diff --git a/resource-metadata/hypothesis.md b/resource-metadata/hypothesis.md index 5b476abd..93345212 100644 --- a/resource-metadata/hypothesis.md +++ b/resource-metadata/hypothesis.md @@ -128,50 +128,3 @@ A Solid server may support other metadata types. There are many ways a Solid server could implement these features. A file-based Solid server could have a special naming scheme reserved for these metadata resources. Alternatively, a Solid server could represent every resource internally as a dataset, storing each separate type of metadata in its own named graph. A Solid server needs to maintain a working knowledge of which resources are metadata, because it tells the clients where to find them. This means that it can similarly apply this knowledge to know when someone is writing to a known metadata resource, such as an ACL, and can apply the appropriate validation and sanity checks to ensure the changes are valid. - -# Draft Resources - -This section and the content inside it is meant to aid in the drafting process, and will not be included in the candidate proposal submitted to the specification. The purpose of this section is to aid those contributing to or reviewing this document. - -## Additional References - -[Solid Content Representation Spec](https://github.com/solid/solid-spec/blob/master/content-representation.md) - This is the original component specification document (circa 2016) that defined a metadata discovery mechanism using Link headers. - -Notable issues: -- [Specify approach for resource metadata](https://github.com/solid/specification/issues/102) -- [Specify metadata mechanism for Containers, RDFResources, NonRDFResources](https://github.com/solid/specification/issues/63) -- [Clarify the lifecycle of an ACL resource](https://github.com/solid/specification/issues/58) -- [Proposal: server-protected metadata](https://github.com/solid/specification/issues/65) -- [Methods for ACL resource creation](https://github.com/solid/specification/issues/42) -- [How does the server determine whether a resource is an ACL resource](https://github.com/solid/specification/issues/31) -- [Atomicity of creating a resource and its ACL](https://github.com/solid/specification/issues/131) -- [ACL for meta resources](https://github.com/solid/solid/issues/130) -- [How should we handle metadata of non-RDF sources](https://github.com/solid/solid-spec/issues/197) -- [How to delete metadata file?](https://github.com/solid/solid-spec/issues/168) -- [When a resource is deleted, should the acl be deleted too?](https://github.com/solid/solid/issues/251) -- [When deleting a resources, should the corresponding ACL document be deleted?](https://github.com/solid/solid-spec/issues/187) -- [Explain the ACL inheritance algorithm for clients](https://github.com/solid/specification/issues/106) - -Items/themes that are raised in the issues above and should be addressed in some form: - -- Reconfirm use of describedby as a way to get to meta information (#63) -- Specify whether or not metadata should be handled as regular rdf resources (it should be) - probably should put this in the opening section. -- Specify the semantics of meta information for containers (#63) - - Take a look at current NSS use of .meta for containers -- Clarify whether metadata for a container counts towards it being empty or not (#63) -- Specify semantics of meta for NonRDFResources (#63) -- Specify semantics of meta for RDFResources (#63) -- Clarify permissioning of .meta resources (#63) - - Can a client always read metadata? - - Can a client always know the metadata is there (e.g. link headers are advertised) - - What if the user wants to provide access to the file but not the file metadata? -- Clarify the lifecycle of .meta resources (#63, #58) - - [Consensus](https://github.com/solid/specification/issues/31) that deleting a resource must remove associated ACL resource -- Specify how .meta resources get serialized (#63) -- Differentiate user-writeable metadata from server-protected metadata (#63, #65) - - For a given piece of metadata, it is - - only readable and writeable by the server (e.g. internal indexing) - - readable by any client subject to permissions on resource, but only written by the server (e.g. timestamps) - - readable and writeable by any client subject to permissions on resource (i can set the shape constraint, or read/write the acl) -- Determine whether we should point out the actual ACL resource in use in a new link header (timbl suggestion, ruben created issue). Discussed in #31, proposed in #106 -- Can you create an ACL resource in advance, or at the time of creation of the resource itself? (#131) From 3b26f88077b2b7a08d32e260dffdd5d7dc437a56 Mon Sep 17 00:00:00 2001 From: Justin Bingham Date: Wed, 15 Jan 2020 21:50:38 -0500 Subject: [PATCH 13/27] limit types to one metadata resource --- resource-metadata/hypothesis.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/resource-metadata/hypothesis.md b/resource-metadata/hypothesis.md index 93345212..15409ea9 100644 --- a/resource-metadata/hypothesis.md +++ b/resource-metadata/hypothesis.md @@ -69,6 +69,8 @@ ACL resources as defined by [Web Access Control](https://github.com/solid/web-ac ACL metadata resources are discoverable by the client via ```rel=acl```. +A given Solid resource MUST NOT be directly associated with more than one ACL metadata resource. + An ACL metadata resource MUST be deleted by the Solid server when the resource it is directly associated with is also deleted and the Solid server is authoritative for both resources. To access or manage an ACL metadata resource, an [acl:agent](https://github.com/solid/web-access-control-spec#describing-agents) MUST have [acl:Control](https://github.com/solid/web-access-control-spec#aclcontrol) privileges per the [ACL inheritance algorithm](https://github.com/solid/web-access-control-spec#acl-inheritance-algorithm) on the resource directly associated with it. @@ -81,6 +83,8 @@ Resource description is a general mechanism to provide descriptive metadata for The Descriptive metadata resource for a given resource is discovered by the client via ```rel=describedby```. Conversely, the resource being described by a Descriptive metadata resource is discovered by the client via ```rel=http://www.w3.org/ns/solid/terms#resource```. +A given Solid resource MUST NOT be directly associated with more than one Descriptive metadata resource. + A Descriptive metadata resource MUST be deleted by the Solid server when the resource it is directly associated with is also deleted and the Solid server is authoritative for both resources. Access or management of a Descriptive metadata resource by a given [acl:agent](https://github.com/solid/web-access-control-spec#describing-agents) is subject to the [modes of access](https://github.com/solid/web-access-control-spec#modes-of-access) granted per the [ACL inheritance algorithm](https://github.com/solid/web-access-control-spec#acl-inheritance-algorithm) on the resource directly associated with it. @@ -91,6 +95,8 @@ Shape Validation ensures that any data changes in a given resource conform to an The Shape validation metadata resource for a given resource is discovered by the client via ```rel=http://www.w3.org/ns/solid/terms#shape```. Conversely, the resource being described by a Shape validation metadata resource is discovered by the client via ```rel=http://www.w3.org/ns/solid/terms#resource```. +A given Solid resource MUST NOT be directly associated with more than one Descriptive metadata resource. + A Shape validation metadata resource MUST be deleted by the Solid server when the resource it is directly associated with is also deleted and the Solid server is authoritative for both resources. To access or manage a Shape validation metadata resource, an [acl:agent](https://github.com/solid/web-access-control-spec#describing-agents) MUST have [acl:Control](https://github.com/solid/web-access-control-spec#aclcontrol) privileges per the [ACL inheritance algorithm](https://github.com/solid/web-access-control-spec#acl-inheritance-algorithm) on the resource directly associated with it. @@ -103,6 +109,8 @@ A Solid server stores information about a resource that clients can read but not A Server Managed metadata resource is discovered by the client via ```rel=http://www.w3.org/ns/solid/terms#servermanaged```. Conversely, the resource being described by a Server Managed metadata resource is discovered by the client via ```rel=http://www.w3.org/ns/solid/terms#resource```. +A given Solid resource MUST NOT be directly associated with more than one Server Managed metadata resource. + A Server Managed metadata resource MUST be deleted by the Solid server when the resource it is directly associated with is also deleted and the Solid server is authoritative for both resources. To access a Server Managed metadata resource, an [acl:agent](https://github.com/solid/web-access-control-spec#describing-agents) MUST have [acl:Read](https://github.com/solid/web-access-control-spec#aclread) privileges per the [ACL inheritance algorithm](https://github.com/solid/web-access-control-spec#acl-inheritance-algorithm) on the resource directly associated with it. @@ -113,6 +121,8 @@ Configuration metadata is used to store configurable parameters for a given reso A configuration metadata resource is discovered by the client via ```rel=http://www.w3.org/ns/solid/terms#configuration```. Conversely, the resource being described by a Configuration metadata resource is discovered by the client via ```rel=http://www.w3.org/ns/solid/terms#resource```. +A given Solid resource MUST NOT be directly associated with more than one Configuration metadata resource. + A Configuration metadata resource MUST be deleted by the Solid server when the resource it is directly associated with is also deleted and the Solid server is authoritative for both resources. To access or manage a Configuration metadata resource, an [acl:agent](https://github.com/solid/web-access-control-spec#describing-agents) MUST have [acl:Control](https://github.com/solid/web-access-control-spec#aclcontrol) privileges per the [ACL inheritance algorithm](https://github.com/solid/web-access-control-spec#acl-inheritance-algorithm) on the resource directly associated with it. From aeb0764095e503b2ed8c9f1a3e226ba26ce71b24 Mon Sep 17 00:00:00 2001 From: Justin Bingham Date: Thu, 16 Jan 2020 15:22:30 -0500 Subject: [PATCH 14/27] Apply suggestions from review Co-Authored-By: Ted Thibodeau Jr --- resource-metadata/README.md | 2 +- resource-metadata/hypothesis.md | 10 +++++----- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/resource-metadata/README.md b/resource-metadata/README.md index 4db86712..ba9ad2c5 100644 --- a/resource-metadata/README.md +++ b/resource-metadata/README.md @@ -32,7 +32,7 @@ Notable issues: Items/themes that are raised in the issues above and should be addressed in some form: - Reconfirm use of describedby as a way to get to meta information (#63) -- Specify whether or not metadata should be handled as regular rdf resources (it should be) - probably should put this in the opening section. +- Specify that metadata should be handled as regular RDF resources - probably should put this in the opening section. - Specify the semantics of meta information for containers (#63) - Take a look at current NSS use of .meta for containers - Clarify whether metadata for a container counts towards it being empty or not (#63) diff --git a/resource-metadata/hypothesis.md b/resource-metadata/hypothesis.md index d2603147..e9346e25 100644 --- a/resource-metadata/hypothesis.md +++ b/resource-metadata/hypothesis.md @@ -70,7 +70,7 @@ ACL metadata resources are discoverable by the client via ```rel=acl```. A given Solid resource MUST NOT be directly associated with more than one ACL metadata resource. -An ACL metadata resource MUST be deleted by the Solid server when the resource it is directly associated with is also deleted and the Solid server is authoritative for both resources. +An ACL metadata resource MUST be deleted by the Solid server when the resource it is directly associated with is deleted and the Solid server is authoritative for both resources. To access or manage an ACL metadata resource, an [acl:agent](https://github.com/solid/web-access-control-spec#describing-agents) MUST have [acl:Control](https://github.com/solid/web-access-control-spec#aclcontrol) privileges per the [ACL inheritance algorithm](https://github.com/solid/web-access-control-spec#acl-inheritance-algorithm) on the resource directly associated with it. @@ -84,7 +84,7 @@ The Descriptive metadata resource for a given resource is discovered by the clie A given Solid resource MUST NOT be directly associated with more than one Descriptive metadata resource. -A Descriptive metadata resource MUST be deleted by the Solid server when the resource it is directly associated with is also deleted and the Solid server is authoritative for both resources. +A Descriptive metadata resource MUST be deleted by the Solid server when the resource it is directly associated with is deleted and the Solid server is authoritative for both resources. Access or management of a Descriptive metadata resource by a given [acl:agent](https://github.com/solid/web-access-control-spec#describing-agents) is subject to the [modes of access](https://github.com/solid/web-access-control-spec#modes-of-access) granted per the [ACL inheritance algorithm](https://github.com/solid/web-access-control-spec#acl-inheritance-algorithm) on the resource directly associated with it. @@ -96,7 +96,7 @@ The Shape validation metadata resource for a given resource is discovered by the A given Solid resource MUST NOT be directly associated with more than one Descriptive metadata resource. -A Shape validation metadata resource MUST be deleted by the Solid server when the resource it is directly associated with is also deleted and the Solid server is authoritative for both resources. +A Shape validation metadata resource MUST be deleted by the Solid server when the resource it is directly associated with is deleted and the Solid server is authoritative for both resources. To access or manage a Shape validation metadata resource, an [acl:agent](https://github.com/solid/web-access-control-spec#describing-agents) MUST have [acl:Control](https://github.com/solid/web-access-control-spec#aclcontrol) privileges per the [ACL inheritance algorithm](https://github.com/solid/web-access-control-spec#acl-inheritance-algorithm) on the resource directly associated with it. @@ -110,7 +110,7 @@ A Server Managed metadata resource is discovered by the client via ```rel=http:/ A given Solid resource MUST NOT be directly associated with more than one Server Managed metadata resource. -A Server Managed metadata resource MUST be deleted by the Solid server when the resource it is directly associated with is also deleted and the Solid server is authoritative for both resources. +A Server Managed metadata resource MUST be deleted by the Solid server when the resource it is directly associated with is deleted and the Solid server is authoritative for both resources. To access a Server Managed metadata resource, an [acl:agent](https://github.com/solid/web-access-control-spec#describing-agents) MUST have [acl:Read](https://github.com/solid/web-access-control-spec#aclread) privileges per the [ACL inheritance algorithm](https://github.com/solid/web-access-control-spec#acl-inheritance-algorithm) on the resource directly associated with it. @@ -122,7 +122,7 @@ A configuration metadata resource is discovered by the client via ```rel=http:// A given Solid resource MUST NOT be directly associated with more than one Configuration metadata resource. -A Configuration metadata resource MUST be deleted by the Solid server when the resource it is directly associated with is also deleted and the Solid server is authoritative for both resources. +A Configuration metadata resource MUST be deleted by the Solid server when the resource it is directly associated with is deleted and the Solid server is authoritative for both resources. To access or manage a Configuration metadata resource, an [acl:agent](https://github.com/solid/web-access-control-spec#describing-agents) MUST have [acl:Control](https://github.com/solid/web-access-control-spec#aclcontrol) privileges per the [ACL inheritance algorithm](https://github.com/solid/web-access-control-spec#acl-inheritance-algorithm) on the resource directly associated with it. From 3a6e38cc2b13268b8185aaf9714179148f01ff7b Mon Sep 17 00:00:00 2001 From: Justin Bingham Date: Thu, 27 Feb 2020 21:48:51 -0500 Subject: [PATCH 15/27] use describes when linking back to annotated resource --- resource-metadata/hypothesis.md | 37 ++++++++++++++------------------- 1 file changed, 16 insertions(+), 21 deletions(-) diff --git a/resource-metadata/hypothesis.md b/resource-metadata/hypothesis.md index d2603147..e5933a9c 100644 --- a/resource-metadata/hypothesis.md +++ b/resource-metadata/hypothesis.md @@ -8,7 +8,7 @@ This document introduces a mechanism for linking to metadata about resources in - A binary JPEG image with a Link header, pointing to a description that has an RDF representation. - An LDP container with a Link header, pointing to an ACL resource that governs access controls for the contained resources. -- A resource whose shape is constrained by a ShEx document includes a Link header that points to that ShEx resource. +- A resource whose shape is constrained by a ShEx schema includes a Link header that points to a metadata resource defining that constraint. - A resource may keep an audit trail of modification events. A client could follow the URI in a Link header to access that audit trail. A given resource might link to zero or more such related metadata representations. Having a unified model to describe how clients and Solid servers interact with and process these resources will help clarify expectations, while also providing a shared pattern for extending the features of Solid server implementations. @@ -28,31 +28,26 @@ Given the URL of a resource, a client can discover the metadata resources by iss For any defined metadata type available for a given resource, all representations of that resource MUST include a Link header pointing to the location of each metadata resource. For example, as defined by the Solid [Web Access Control specification](https://github.com/solid/web-access-control-spec), a client can use this mechanism to discover the location of an ACL resource: -Link: ; rel="acl" +Link: ; rel="acl" Metadata discovered through a Link header for a given resource is considered to be *directly associated* with that resource. -### Discovery of Annotated Resource - -Certain metadata resource types MAY require the Solid server to include a link back to the annotated resource using an appropriate link relation. For example, LDP defines a bidirectional discovery mechanism for RDF descriptions of NonRDF resources, via Link headers: - -Link: ; rel="description" +For cases where link relations are not defined by IANA, a URL can be used. For example: -along with: +Link: ; + rel="https://example.org/ns#metadata" -Link: ; rel="describedby" +String-based link relations, such as in the examples above, must be registered with IANA. But it is also possible to use custom relation types by using a full IRI. The [Linked Data Platform](https://www.w3.org/TR/ldp/), the [Linked Data Notifications](https://www.w3.org/TR/ldn/), and the [Web Annotation Protocol](http://www.w3.org/TR/annotation-protocol/) specifications make use of full IRIs in the `rel` attribute. -For cases where link relations are not defined by IANA, a URL can be used. For example: +### Discovery of Annotated Resource -Link: ; - rel="https://example.org/ns#hasMetadata" +Certain metadata resource types MAY require the Solid server to include a link back to the annotated resource it is directly associated with using an appropriate link relation. For example, LDP defines a bidirectional discovery mechanism for RDF descriptions of NonRDF resources, via Link headers: -and: +Link: ; rel="describes" -Link: ; - rel="https://example.org/ns#isMetadataOf" +along with: -String-based link relations, such as in the examples above, must be registered with IANA. But it is also possible to use custom relation types by using a full IRI. The [Linked Data Platform](https://www.w3.org/TR/ldp/), the [Linked Data Notifications](https://www.w3.org/TR/ldn/), and the [Web Annotation Protocol](http://www.w3.org/TR/annotation-protocol/) specifications make use of full IRIs in the `rel` attribute. +Link: ; rel="describedby" ## Metadata Characteristics @@ -66,7 +61,7 @@ Metadata resources on the same Solid server MUST adhere to the same interaction ACL resources as defined by [Web Access Control](https://github.com/solid/web-access-control-spec) MUST be supported as a resource metadata type by Solid servers. -ACL metadata resources are discoverable by the client via ```rel=acl```. +The ACL metadata resource directly associated with a given resource is discovered by the client via ```rel=acl```. A given Solid resource MUST NOT be directly associated with more than one ACL metadata resource. @@ -80,7 +75,7 @@ A Solid server SHOULD sanity check ACL metadata resources upon creation or updat Resource description is a general mechanism to provide descriptive metadata for a given resource. It MUST be supported as a resource metadata type by Solid servers. -The Descriptive metadata resource for a given resource is discovered by the client via ```rel=describedby```. Conversely, the resource being described by a Descriptive metadata resource is discovered by the client via ```rel=http://www.w3.org/ns/solid/terms#resource```. +The Descriptive metadata resource directly associated with a given resource is discovered by the client via ```rel=describedby```. Conversely, the resource being described by a Descriptive metadata resource is discovered by the client via ```rel=describes```. A given Solid resource MUST NOT be directly associated with more than one Descriptive metadata resource. @@ -92,7 +87,7 @@ Access or management of a Descriptive metadata resource by a given [acl:agent](h Shape Validation ensures that any data changes in a given resource conform to an associated [SHACL](https://www.w3.org/TR/shacl/) or [ShEx](https://shex.io/shex-semantics/index.html) data shape. It MUST be supported as a resource metadata type by Solid servers. -The Shape validation metadata resource for a given resource is discovered by the client via ```rel=http://www.w3.org/ns/solid/terms#shape```. Conversely, the resource being described by a Shape validation metadata resource is discovered by the client via ```rel=http://www.w3.org/ns/solid/terms#resource```. +The Shape validation metadata resource directly associated with a given resource is discovered by the client via ```rel=http://www.w3.org/ns/solid/terms#shape```. Conversely, the resource being described by a Shape validation metadata resource is discovered by the client via ```rel=describes```. A given Solid resource MUST NOT be directly associated with more than one Descriptive metadata resource. @@ -106,7 +101,7 @@ A Solid server SHOULD sanity check Shape validation metadata resources upon crea A Solid server stores information about a resource that clients can read but not change in Server Managed metadata. It MUST be supported as a resource metadata type by Solid servers. -A Server Managed metadata resource is discovered by the client via ```rel=http://www.w3.org/ns/solid/terms#servermanaged```. Conversely, the resource being described by a Server Managed metadata resource is discovered by the client via ```rel=http://www.w3.org/ns/solid/terms#resource```. +A Server Managed metadata resource directly associated with a given resource is discovered by the client via ```rel=http://www.w3.org/ns/solid/terms#servermanaged```. Conversely, the resource being described by a Server Managed metadata resource is discovered by the client via ```rel=describes```. A given Solid resource MUST NOT be directly associated with more than one Server Managed metadata resource. @@ -118,7 +113,7 @@ To access a Server Managed metadata resource, an [acl:agent](https://github.com/ Configuration metadata is used to store configurable parameters for a given resource. It MUST be supported as a resource metadata type by Solid servers. -A configuration metadata resource is discovered by the client via ```rel=http://www.w3.org/ns/solid/terms#configuration```. Conversely, the resource being described by a Configuration metadata resource is discovered by the client via ```rel=http://www.w3.org/ns/solid/terms#resource```. +A configuration metadata resource directly associated with a given resource is discovered by the client via ```rel=http://www.w3.org/ns/solid/terms#configuration```. Conversely, the resource being described by a Configuration metadata resource is discovered by the client via ```rel=describes```. A given Solid resource MUST NOT be directly associated with more than one Configuration metadata resource. From 252dfce8a22b3772246c83ca8017742d04830c2a Mon Sep 17 00:00:00 2001 From: Justin Bingham Date: Thu, 27 Feb 2020 23:34:07 -0500 Subject: [PATCH 16/27] incorporate csarven feedback - part1 --- resource-metadata/hypothesis.md | 52 ++++++++++----------------------- 1 file changed, 15 insertions(+), 37 deletions(-) diff --git a/resource-metadata/hypothesis.md b/resource-metadata/hypothesis.md index 21ecb074..4a9d2cf8 100644 --- a/resource-metadata/hypothesis.md +++ b/resource-metadata/hypothesis.md @@ -4,50 +4,36 @@ *This section is non-normative* -This document introduces a mechanism for linking to metadata about resources in the Solid Ecosystem using HTTP Link headers. Examples of this linking mechanism include: +This document introduces a mechanism for linking to metadata about resources in the Solid Ecosystem using HTTP Link headers. The metadata may serve as supplementary descriptions or, when supported by a Solid server implementation, may influence the behavior of the resources. It is not meant to supplant the ability for the directly associated resource to self-describe. + +Examples of this mechanism in use include: - A binary JPEG image with a Link header, pointing to a description that has an RDF representation. -- An LDP container with a Link header, pointing to an ACL resource that governs access controls for the contained resources. +- A container with a Link header, pointing to an ACL resource that governs access controls for the contained resources. - A resource whose shape is constrained by a ShEx schema includes a Link header that points to a metadata resource defining that constraint. -- A resource may keep an audit trail of modification events. A client could follow the URI in a Link header to access that audit trail. - -A given resource might link to zero or more such related metadata representations. Having a unified model to describe how clients and Solid servers interact with and process these resources will help clarify expectations, while also providing a shared pattern for extending the features of Solid server implementations. - -The metadata model described in this document makes it possible for clients to decorate resources with structured descriptive data. Those metadata may serve as supplementary descriptions or, when supported by a Solid server implementation, they may influence the behavior of the resources. - -Some examples include: +- A resource with an associated set of configurable parameters includes a Link header that points to a resource where those configurable parameters reside. -- An ACL resource controls how a Solid server makes authorization decisions for a container and any child resources. -- A shape constraint resource may limit the RDF structures that can be added to a resource or container. -- A “configuration” resource may control how a resource is versioned, or which indexes are exposed for it. +A given resource might link to zero or more such related metadata representations. -Access to different categories of metadata may require different levels of privilege, which must be specified as part of the definition for a given metadata type. +Access to different types of metadata may require varying levels of privilege, which must be specified as part of the definition for a given metadata type. ## Metadata Discovery -Given the URL of a resource, a client can discover the metadata resources by issuing a `GET` (or `HEAD`) request and inspecting the `Link` headers in the response. The [`rel={attribute}`](https://tools.ietf.org/html/rfc8288) will define the relationship to the target URL. + +Given the URL of a resource, a client can discover the metadata resources by issuing a `GET`, `HEAD`, or `OPTIONS` request and inspecting the `Link` headers in the response. The [`rel={relation-type}`](https://tools.ietf.org/html/rfc8288) will define the relationship to the target URL. Refer to [RFC8288](https://tools.ietf.org/html/rfc8288) for allowed [link relation types](https://tools.ietf.org/html/rfc8288#section-2.1). For any defined metadata type available for a given resource, all representations of that resource MUST include a Link header pointing to the location of each metadata resource. For example, as defined by the Solid [Web Access Control specification](https://github.com/solid/web-access-control-spec), a client can use this mechanism to discover the location of an ACL resource: -Link: ; rel="acl" +Link: ; rel="acl" Metadata discovered through a Link header for a given resource is considered to be *directly associated* with that resource. -For cases where link relations are not defined by IANA, a URL can be used. For example: - -Link: ; - rel="https://example.org/ns#metadata" - -String-based link relations, such as in the examples above, must be registered with IANA. But it is also possible to use custom relation types by using a full IRI. The [Linked Data Platform](https://www.w3.org/TR/ldp/), the [Linked Data Notifications](https://www.w3.org/TR/ldn/), and the [Web Annotation Protocol](http://www.w3.org/TR/annotation-protocol/) specifications make use of full IRIs in the `rel` attribute. - ### Discovery of Annotated Resource -Certain metadata resource types MAY require the Solid server to include a link back to the annotated resource it is directly associated with using an appropriate link relation. For example, LDP defines a bidirectional discovery mechanism for RDF descriptions of NonRDF resources, via Link headers: +Certain metadata resource types require the Solid server to link back to the annotated resource that the metadata is directly associated with, via Link headers. In these instances, the link relation ```rel=describes``` MUST be used. -Link: ; rel="describes" +For example, a metadata resource `````` directly associated with `````` whose type requires linking back to the annotated resource MUST have the following included in its Link headers: -along with: - -Link: ; rel="describedby" +Link: ; rel="describes" ## Metadata Characteristics @@ -55,6 +41,8 @@ A given resource MAY Link to metadata on a different server. Metadata resources on the same Solid server MUST adhere to the same interaction model used by standard Solid resources. +A metadata resource MUST be deleted by the Solid server when the resource it is directly associated with is also deleted and the Solid server is authoritative for both resources. + ## Reserved Metadata Types ### Web Access Control @@ -65,8 +53,6 @@ The ACL metadata resource directly associated with a given resource is discovere A given Solid resource MUST NOT be directly associated with more than one ACL metadata resource. -An ACL metadata resource MUST be deleted by the Solid server when the resource it is directly associated with is deleted and the Solid server is authoritative for both resources. - To access or manage an ACL metadata resource, an [acl:agent](https://github.com/solid/web-access-control-spec#describing-agents) MUST have [acl:Control](https://github.com/solid/web-access-control-spec#aclcontrol) privileges per the [ACL inheritance algorithm](https://github.com/solid/web-access-control-spec#acl-inheritance-algorithm) on the resource directly associated with it. A Solid server SHOULD sanity check ACL metadata resources upon creation or update to restrict invalid changes. @@ -79,8 +65,6 @@ The Descriptive metadata resource directly associated with a given resource is d A given Solid resource MUST NOT be directly associated with more than one Descriptive metadata resource. -A Descriptive metadata resource MUST be deleted by the Solid server when the resource it is directly associated with is deleted and the Solid server is authoritative for both resources. - Access or management of a Descriptive metadata resource by a given [acl:agent](https://github.com/solid/web-access-control-spec#describing-agents) is subject to the [modes of access](https://github.com/solid/web-access-control-spec#modes-of-access) granted per the [ACL inheritance algorithm](https://github.com/solid/web-access-control-spec#acl-inheritance-algorithm) on the resource directly associated with it. ### Shape Validation @@ -91,8 +75,6 @@ The Shape validation metadata resource directly associated with a given resource A given Solid resource MUST NOT be directly associated with more than one Descriptive metadata resource. -A Shape validation metadata resource MUST be deleted by the Solid server when the resource it is directly associated with is deleted and the Solid server is authoritative for both resources. - To access or manage a Shape validation metadata resource, an [acl:agent](https://github.com/solid/web-access-control-spec#describing-agents) MUST have [acl:Control](https://github.com/solid/web-access-control-spec#aclcontrol) privileges per the [ACL inheritance algorithm](https://github.com/solid/web-access-control-spec#acl-inheritance-algorithm) on the resource directly associated with it. A Solid server SHOULD sanity check Shape validation metadata resources upon creation or update to restrict invalid changes. @@ -105,8 +87,6 @@ A Server Managed metadata resource directly associated with a given resource is A given Solid resource MUST NOT be directly associated with more than one Server Managed metadata resource. -A Server Managed metadata resource MUST be deleted by the Solid server when the resource it is directly associated with is deleted and the Solid server is authoritative for both resources. - To access a Server Managed metadata resource, an [acl:agent](https://github.com/solid/web-access-control-spec#describing-agents) MUST have [acl:Read](https://github.com/solid/web-access-control-spec#aclread) privileges per the [ACL inheritance algorithm](https://github.com/solid/web-access-control-spec#acl-inheritance-algorithm) on the resource directly associated with it. ### Configuration @@ -117,8 +97,6 @@ A configuration metadata resource directly associated with a given resource is d A given Solid resource MUST NOT be directly associated with more than one Configuration metadata resource. -A Configuration metadata resource MUST be deleted by the Solid server when the resource it is directly associated with is deleted and the Solid server is authoritative for both resources. - To access or manage a Configuration metadata resource, an [acl:agent](https://github.com/solid/web-access-control-spec#describing-agents) MUST have [acl:Control](https://github.com/solid/web-access-control-spec#aclcontrol) privileges per the [ACL inheritance algorithm](https://github.com/solid/web-access-control-spec#acl-inheritance-algorithm) on the resource directly associated with it. ## Non-Reserved Types From c20dd843b8ba51acf92fd32c75f2fac5887c70ea Mon Sep 17 00:00:00 2001 From: Justin Bingham Date: Mon, 16 Mar 2020 16:25:18 -0400 Subject: [PATCH 17/27] add table with pointers to reserved types --- resource-metadata/hypothesis.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/resource-metadata/hypothesis.md b/resource-metadata/hypothesis.md index 4a9d2cf8..f1b5a28b 100644 --- a/resource-metadata/hypothesis.md +++ b/resource-metadata/hypothesis.md @@ -27,6 +27,16 @@ Link: ; rel="acl" Metadata discovered through a Link header for a given resource is considered to be *directly associated* with that resource. +The following are [reserved metadata types](#reserved-metadata-types) and the associated link relation URIs that are used for discovery. Other metadata types and relations may also be used, and may be added to the reserved set in the future. + +| Metadata Type | Link Relation | +| :------------- |:-------------| +| [Web Access Control](#web-access-control) | ```acl``` or ```http://www.w3.org/ns/solid/terms#acl``` | +| [Resource Description](#resource-description) | ```describedby``` or ```https://www.w3.org/ns/iana/link-relations/relation#describedby``` | +| [Shape Validation](#shape-validation) | ```http://www.w3.org/ns/solid/terms#shape``` | +| [Server Managed](#server-managed) | ```http://www.w3.org/ns/solid/terms#servermanaged``` | +| [Configuration](#configuration) | ```http://www.w3.org/ns/solid/terms#configuration``` | + ### Discovery of Annotated Resource Certain metadata resource types require the Solid server to link back to the annotated resource that the metadata is directly associated with, via Link headers. In these instances, the link relation ```rel=describes``` MUST be used. From 2583e895e6c944033f77a7abdbc20ad294ff815d Mon Sep 17 00:00:00 2001 From: Justin Bingham Date: Mon, 16 Mar 2020 16:44:59 -0400 Subject: [PATCH 18/27] clarify metadata characteristics --- resource-metadata/hypothesis.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/resource-metadata/hypothesis.md b/resource-metadata/hypothesis.md index f1b5a28b..ff634840 100644 --- a/resource-metadata/hypothesis.md +++ b/resource-metadata/hypothesis.md @@ -47,9 +47,9 @@ Link: ; rel="describes" ## Metadata Characteristics -A given resource MAY Link to metadata on a different server. +A given resource MAY Link to metadata on a different server under a different authority, per the configuration of the Solid server on which the resource resides. -Metadata resources on the same Solid server MUST adhere to the same interaction model used by standard Solid resources. +Metadata resources that reside on a Solid server MUST adhere to the same interaction model used by standard Solid resources, except where specified in the [definition](#reserved-metadata-types) of the metadata type. A metadata resource MUST be deleted by the Solid server when the resource it is directly associated with is also deleted and the Solid server is authoritative for both resources. From b2a55932b4950bee6e36addfe9daebacf83d271a Mon Sep 17 00:00:00 2001 From: Justin Bingham Date: Mon, 16 Mar 2020 16:57:13 -0400 Subject: [PATCH 19/27] clarify acl sanity check --- resource-metadata/hypothesis.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/resource-metadata/hypothesis.md b/resource-metadata/hypothesis.md index ff634840..d21cce6d 100644 --- a/resource-metadata/hypothesis.md +++ b/resource-metadata/hypothesis.md @@ -65,7 +65,7 @@ A given Solid resource MUST NOT be directly associated with more than one ACL me To access or manage an ACL metadata resource, an [acl:agent](https://github.com/solid/web-access-control-spec#describing-agents) MUST have [acl:Control](https://github.com/solid/web-access-control-spec#aclcontrol) privileges per the [ACL inheritance algorithm](https://github.com/solid/web-access-control-spec#acl-inheritance-algorithm) on the resource directly associated with it. -A Solid server SHOULD sanity check ACL metadata resources upon creation or update to restrict invalid changes. +A Solid server SHOULD sanity check ACL metadata resources upon creation or update to restrict invalid changes, such as by performing shape validation against authorization statements therein. ### Resource Description From c7ba28c7a543c9b2b41076e99761c53d064c9f98 Mon Sep 17 00:00:00 2001 From: Justin Bingham Date: Mon, 16 Mar 2020 16:59:50 -0400 Subject: [PATCH 20/27] clarify metadata characteristics --- resource-metadata/hypothesis.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/resource-metadata/hypothesis.md b/resource-metadata/hypothesis.md index d21cce6d..a99754cb 100644 --- a/resource-metadata/hypothesis.md +++ b/resource-metadata/hypothesis.md @@ -49,7 +49,7 @@ Link: ; rel="describes" A given resource MAY Link to metadata on a different server under a different authority, per the configuration of the Solid server on which the resource resides. -Metadata resources that reside on a Solid server MUST adhere to the same interaction model used by standard Solid resources, except where specified in the [definition](#reserved-metadata-types) of the metadata type. +Metadata resources that reside on a Solid server MUST adhere to the same interaction model used by other standard Solid resources, except where specified in the [definition](#reserved-metadata-types) of the metadata type. A metadata resource MUST be deleted by the Solid server when the resource it is directly associated with is also deleted and the Solid server is authoritative for both resources. From 49c8ef906114d4e692fc91fddfb9b10d1fe70d93 Mon Sep 17 00:00:00 2001 From: Justin Bingham Date: Mon, 16 Mar 2020 21:01:23 -0400 Subject: [PATCH 21/27] clarify server managed metadata --- resource-metadata/hypothesis.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/resource-metadata/hypothesis.md b/resource-metadata/hypothesis.md index a99754cb..5cc5f25b 100644 --- a/resource-metadata/hypothesis.md +++ b/resource-metadata/hypothesis.md @@ -91,13 +91,13 @@ A Solid server SHOULD sanity check Shape validation metadata resources upon crea ### Server Managed -A Solid server stores information about a resource that clients can read but not change in Server Managed metadata. It MUST be supported as a resource metadata type by Solid servers. +A Solid server stores information about a resource that clients can read but not change in Server Managed metadata. Examples of Server Managed metadata could include resource creation or modification timestamps, identity of the agent that created the resource, etc. It MUST be supported as a resource metadata type by Solid servers. -A Server Managed metadata resource directly associated with a given resource is discovered by the client via ```rel=http://www.w3.org/ns/solid/terms#servermanaged```. Conversely, the resource being described by a Server Managed metadata resource is discovered by the client via ```rel=describes```. +A Server Managed metadata resource directly associated with a given resource is discovered by the client via ```rel=http://www.w3.org/ns/solid/terms#managed```. Conversely, the resource being described by a Server Managed metadata resource is discovered by the client via ```rel=describes```. A given Solid resource MUST NOT be directly associated with more than one Server Managed metadata resource. -To access a Server Managed metadata resource, an [acl:agent](https://github.com/solid/web-access-control-spec#describing-agents) MUST have [acl:Read](https://github.com/solid/web-access-control-spec#aclread) privileges per the [ACL inheritance algorithm](https://github.com/solid/web-access-control-spec#acl-inheritance-algorithm) on the resource directly associated with it. +To read a Server Managed metadata resource, an [acl:agent](https://github.com/solid/web-access-control-spec#describing-agents) MUST have [acl:Read](https://github.com/solid/web-access-control-spec#aclread) privileges per the [ACL inheritance algorithm](https://github.com/solid/web-access-control-spec#acl-inheritance-algorithm) on the resource directly associated with it. Modes of access beyond [acl:Read](https://github.com/solid/web-access-control-spec#aclread) MUST NOT be permitted on a Server Managed metadata resource. ### Configuration From 87453ac741b9f1dd80ac4c5206f82ef36f92c246 Mon Sep 17 00:00:00 2001 From: Justin Bingham Date: Mon, 16 Mar 2020 21:33:45 -0400 Subject: [PATCH 22/27] clarify configuration and shape validation --- resource-metadata/hypothesis.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/resource-metadata/hypothesis.md b/resource-metadata/hypothesis.md index 5cc5f25b..d4e38862 100644 --- a/resource-metadata/hypothesis.md +++ b/resource-metadata/hypothesis.md @@ -85,7 +85,9 @@ The Shape validation metadata resource directly associated with a given resource A given Solid resource MUST NOT be directly associated with more than one Descriptive metadata resource. -To access or manage a Shape validation metadata resource, an [acl:agent](https://github.com/solid/web-access-control-spec#describing-agents) MUST have [acl:Control](https://github.com/solid/web-access-control-spec#aclcontrol) privileges per the [ACL inheritance algorithm](https://github.com/solid/web-access-control-spec#acl-inheritance-algorithm) on the resource directly associated with it. +To create or modify a Shape validation metadata resource, an [acl:agent](https://github.com/solid/web-access-control-spec#describing-agents) MUST have [acl:Write](https://github.com/solid/web-access-control-spec#aclcontrol) privileges per the [ACL inheritance algorithm](https://github.com/solid/web-access-control-spec#acl-inheritance-algorithm) on the resource directly associated with it. + +To read a Shape validation metadata resource, an [acl:agent](https://github.com/solid/web-access-control-spec#describing-agents) MUST have [acl:Read](https://github.com/solid/web-access-control-spec#aclcontrol) privileges per the [ACL inheritance algorithm](https://github.com/solid/web-access-control-spec#acl-inheritance-algorithm) on the resource directly associated with it. A Solid server SHOULD sanity check Shape validation metadata resources upon creation or update to restrict invalid changes. @@ -101,7 +103,7 @@ To read a Server Managed metadata resource, an [acl:agent](https://github.com/so ### Configuration -Configuration metadata is used to store configurable parameters for a given resource. It MUST be supported as a resource metadata type by Solid servers. +Configuration metadata is used to store configurable parameters for a given resource. For example, whether to maintain [Mementos](https://tools.ietf.org/html/rfc7089) for a given resource, or how the data within a given resource should be rendered or indexed. It MUST be supported as a resource metadata type by Solid servers. A configuration metadata resource directly associated with a given resource is discovered by the client via ```rel=http://www.w3.org/ns/solid/terms#configuration```. Conversely, the resource being described by a Configuration metadata resource is discovered by the client via ```rel=describes```. From ce3c263285377d606c0585fb64c1beb77dc280da Mon Sep 17 00:00:00 2001 From: Justin Bingham Date: Mon, 16 Mar 2020 21:43:26 -0400 Subject: [PATCH 23/27] clarify metadata extension --- resource-metadata/hypothesis.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/resource-metadata/hypothesis.md b/resource-metadata/hypothesis.md index d4e38862..3ab734ed 100644 --- a/resource-metadata/hypothesis.md +++ b/resource-metadata/hypothesis.md @@ -111,14 +111,14 @@ A given Solid resource MUST NOT be directly associated with more than one Config To access or manage a Configuration metadata resource, an [acl:agent](https://github.com/solid/web-access-control-spec#describing-agents) MUST have [acl:Control](https://github.com/solid/web-access-control-spec#aclcontrol) privileges per the [ACL inheritance algorithm](https://github.com/solid/web-access-control-spec#acl-inheritance-algorithm) on the resource directly associated with it. -## Non-Reserved Types +## Extending with Additional Metadata Types -A Solid server may support other metadata types. +A Solid server may support additional resource metadata types. Any additional types must follow the base [Metadata Discovery](#metadata-discovery) and [Metadata Characteristics](#metadata-characteristics) criteria detailed herein. ## Implementation Patterns *This section is non-normative.* -There are many ways a Solid server could implement these features. A file-based Solid server could have a special naming scheme reserved for these metadata resources. Alternatively, a Solid server could represent every resource internally as a dataset, storing each separate type of metadata in its own named graph. +There are many ways a Solid server could implement these features. A file-based Solid server could have a special naming scheme reserved for metadata resources. Alternatively, a Solid server could represent every resource internally as a dataset, storing each separate type of metadata in its own named graph. A Solid server needs to maintain a working knowledge of which resources are metadata, because it tells the clients where to find them. This means that it can similarly apply this knowledge to know when someone is writing to a known metadata resource, such as an ACL, and can apply the appropriate validation and sanity checks to ensure the changes are valid. From bc21ce92f388f4f4f6046f4426fdac484efa3727 Mon Sep 17 00:00:00 2001 From: Justin Bingham Date: Thu, 19 Mar 2020 21:18:49 -0400 Subject: [PATCH 24/27] add metadata lookup through rdf representation --- resource-metadata/hypothesis.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/resource-metadata/hypothesis.md b/resource-metadata/hypothesis.md index 3ab734ed..b18b0c4a 100644 --- a/resource-metadata/hypothesis.md +++ b/resource-metadata/hypothesis.md @@ -19,7 +19,11 @@ Access to different types of metadata may require varying levels of privilege, w ## Metadata Discovery -Given the URL of a resource, a client can discover the metadata resources by issuing a `GET`, `HEAD`, or `OPTIONS` request and inspecting the `Link` headers in the response. The [`rel={relation-type}`](https://tools.ietf.org/html/rfc8288) will define the relationship to the target URL. Refer to [RFC8288](https://tools.ietf.org/html/rfc8288) for allowed [link relation types](https://tools.ietf.org/html/rfc8288#section-2.1). +Given the URL of a resource, a client can discover the metadata resources by issuing a `HEAD` or `GET` request and inspecting the `Link` headers in the response. The [`rel={relation-type}`](https://tools.ietf.org/html/rfc8288) will define the relationship to the target URL. Refer to [RFC8288](https://tools.ietf.org/html/rfc8288) for allowed [link relation types](https://tools.ietf.org/html/rfc8288#section-2.1). + +The client may also make an HTTP `GET` request on the target resource URL to retrieve an RDF representation, whose encoded RDF graph contains a relation of a given metadata type. + +These may be carried out in either order, but if the first fails to result in discovering the metadata resource or the described resource, the second MUST be tried. For any defined metadata type available for a given resource, all representations of that resource MUST include a Link header pointing to the location of each metadata resource. For example, as defined by the Solid [Web Access Control specification](https://github.com/solid/web-access-control-spec), a client can use this mechanism to discover the location of an ACL resource: From 8fc73e4d8c9902c26aeb934b40b3be59d4ce7cdd Mon Sep 17 00:00:00 2001 From: Justin Bingham Date: Thu, 19 Mar 2020 21:27:07 -0400 Subject: [PATCH 25/27] clarify acl deletion --- resource-metadata/hypothesis.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/resource-metadata/hypothesis.md b/resource-metadata/hypothesis.md index b18b0c4a..8de6b4fb 100644 --- a/resource-metadata/hypothesis.md +++ b/resource-metadata/hypothesis.md @@ -69,6 +69,8 @@ A given Solid resource MUST NOT be directly associated with more than one ACL me To access or manage an ACL metadata resource, an [acl:agent](https://github.com/solid/web-access-control-spec#describing-agents) MUST have [acl:Control](https://github.com/solid/web-access-control-spec#aclcontrol) privileges per the [ACL inheritance algorithm](https://github.com/solid/web-access-control-spec#acl-inheritance-algorithm) on the resource directly associated with it. +An ACL metadata resource MUST NOT be deleted unless the resource directly associated with it is deleted. + A Solid server SHOULD sanity check ACL metadata resources upon creation or update to restrict invalid changes, such as by performing shape validation against authorization statements therein. ### Resource Description From fdf9ad10acb8f03554812f5d11d39123fce0d74e Mon Sep 17 00:00:00 2001 From: Justin Bingham Date: Thu, 19 Mar 2020 22:27:30 -0400 Subject: [PATCH 26/27] clarify access modes needed for key operations --- resource-metadata/hypothesis.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/resource-metadata/hypothesis.md b/resource-metadata/hypothesis.md index 8de6b4fb..61b0c4a0 100644 --- a/resource-metadata/hypothesis.md +++ b/resource-metadata/hypothesis.md @@ -67,7 +67,7 @@ The ACL metadata resource directly associated with a given resource is discovere A given Solid resource MUST NOT be directly associated with more than one ACL metadata resource. -To access or manage an ACL metadata resource, an [acl:agent](https://github.com/solid/web-access-control-spec#describing-agents) MUST have [acl:Control](https://github.com/solid/web-access-control-spec#aclcontrol) privileges per the [ACL inheritance algorithm](https://github.com/solid/web-access-control-spec#acl-inheritance-algorithm) on the resource directly associated with it. +To discover, read, create, or modify an ACL metadata resource, an [acl:agent](https://github.com/solid/web-access-control-spec#describing-agents) MUST have [acl:Control](https://github.com/solid/web-access-control-spec#aclcontrol) privileges per the [ACL inheritance algorithm](https://github.com/solid/web-access-control-spec#acl-inheritance-algorithm) on the resource directly associated with it. An ACL metadata resource MUST NOT be deleted unless the resource directly associated with it is deleted. @@ -81,7 +81,9 @@ The Descriptive metadata resource directly associated with a given resource is d A given Solid resource MUST NOT be directly associated with more than one Descriptive metadata resource. -Access or management of a Descriptive metadata resource by a given [acl:agent](https://github.com/solid/web-access-control-spec#describing-agents) is subject to the [modes of access](https://github.com/solid/web-access-control-spec#modes-of-access) granted per the [ACL inheritance algorithm](https://github.com/solid/web-access-control-spec#acl-inheritance-algorithm) on the resource directly associated with it. +To create or modify a Descriptive metadata resource, a given [acl:agent](https://github.com/solid/web-access-control-spec#describing-agents) MUST have [acl:Write](https://github.com/solid/web-access-control-spec#aclcontrol) privileges per the [ACL inheritance algorithm](https://github.com/solid/web-access-control-spec#acl-inheritance-algorithm) on the resource directly associated with it. + +To discover or read a Descriptive metadata resource, an [acl:agent](https://github.com/solid/web-access-control-spec#describing-agents) MUST have [acl:Read](https://github.com/solid/web-access-control-spec#aclcontrol) privileges per the [ACL inheritance algorithm](https://github.com/solid/web-access-control-spec#acl-inheritance-algorithm) on the resource directly associated with it. ### Shape Validation @@ -115,7 +117,7 @@ A configuration metadata resource directly associated with a given resource is d A given Solid resource MUST NOT be directly associated with more than one Configuration metadata resource. -To access or manage a Configuration metadata resource, an [acl:agent](https://github.com/solid/web-access-control-spec#describing-agents) MUST have [acl:Control](https://github.com/solid/web-access-control-spec#aclcontrol) privileges per the [ACL inheritance algorithm](https://github.com/solid/web-access-control-spec#acl-inheritance-algorithm) on the resource directly associated with it. +To discover, read, create, or modify a Configuration metadata resource, an [acl:agent](https://github.com/solid/web-access-control-spec#describing-agents) MUST have [acl:Control](https://github.com/solid/web-access-control-spec#aclcontrol) privileges per the [ACL inheritance algorithm](https://github.com/solid/web-access-control-spec#acl-inheritance-algorithm) on the resource directly associated with it. ## Extending with Additional Metadata Types From e3fdb924268b8cef3676888d37e071f8850c40e8 Mon Sep 17 00:00:00 2001 From: Justin Bingham Date: Fri, 20 Mar 2020 08:36:35 -0400 Subject: [PATCH 27/27] clarify metadata resource association --- resource-metadata/hypothesis.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/resource-metadata/hypothesis.md b/resource-metadata/hypothesis.md index 61b0c4a0..2c5faab3 100644 --- a/resource-metadata/hypothesis.md +++ b/resource-metadata/hypothesis.md @@ -65,7 +65,7 @@ ACL resources as defined by [Web Access Control](https://github.com/solid/web-ac The ACL metadata resource directly associated with a given resource is discovered by the client via ```rel=acl```. -A given Solid resource MUST NOT be directly associated with more than one ACL metadata resource. +A given Solid resource MUST NOT be directly associated with more than one ACL metadata resource. A given ACL metadata resource MUST NOT be directly associated with more than one Solid resource. To discover, read, create, or modify an ACL metadata resource, an [acl:agent](https://github.com/solid/web-access-control-spec#describing-agents) MUST have [acl:Control](https://github.com/solid/web-access-control-spec#aclcontrol) privileges per the [ACL inheritance algorithm](https://github.com/solid/web-access-control-spec#acl-inheritance-algorithm) on the resource directly associated with it.