|
Open Services for Lifecycle Collaboration
Indexable Linked Data Provider Specification Version 2.0
|
Status: Stable working draft. Implementations welcome to validate the draft. Ongoing work is occurring to validate this draft.
This Version
Latest Version
Previous Version
- This is the first version of this specification.
Authors
- Jim des Rivieres (IBM, OSLC-Core)
Contributors
Table of Contents
Contents
Notation and Conventions
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC2119. Domain name examples use RFC2606.
Introduction
The OSLC Tracked Resource Set 2.0 specification defines a general-purpose protocol for making a large set of resource URIs discoverable and for reporting ongoing changes affecting the set. This document describes how a lifecycle tool web application exposes a live feed of its linked lifecycle data via a tracked resource set, in a way that permits others tool to build and maintain live, searchable indexes based on that linked data.
A particular pool of linked data resources exposed through a particular Tracked Resource Set is referred to as an Indexable Linked Data Source. When exposing a live feed of its linked lifecycle data, a lifecycle tool server is playing the role of Indexable Linked Data Provider. An Indexable Linked Data Consumer is a client (usually another server) that works with linked lifecycle data coming from an Indexable Linked Data Source.
Terminology
This specification uses the term “Tracked Resource Set”, “Change Log”, and “Change Events” defined by the OSLC Tracked Resource Set 2.0 specification.
This specification also defines the following terms:
Access Context - Grouping of resources with similar security requirements.
Access Context List Resource - Resource describing a list of Access Contexts.
Indexable Linked Data Source - Pool of linked data resources.
Indexable Linked Data Consumer - Client application that uses an Indexable Linked Data Source to discover a set of linked data resources and track changes to them.
Indexable Linked Data Provider - Server that implements an Indexable Linked Data Source.
Index Resource - Resource whose URI is listed in the Tracked Resource Set of an Indexable Linked Data Source.
IMPORTANT NOTE TO READERS: The terminology definitions in this section are a normative portion of this specification, imposing requirements upon implementations. All the capitalized words in the text of this specification, such as “Access Context”, reference these defined terms. Whenever the reader encounters them, their definitions found in this section must be followed.
Indexable Linked Data Sources
Note: This section is normative.
An Indexable Linked Data Provider offers one or more Indexable Linked Data Sources.
Each Indexable Linked Data Source has a set of linked data resources, called Index Resources. The Indexable Linked Data Provider decides which particular Index Resources are in a particular Indexable Linked Data Source at any moment. Both the set of Index Resources and the linked data contents of each Index Resource may vary over time.
Each Indexable Linked Data Source consists of a Tracked Resource Set (TRS) resource conforming to the Tracked Resource Set 2.0 specification. The resource URIs listed in a Tracked Resource Set are exactly those of the Indexable Linked Data Source’s Index Resources.
Index Resources MUST have a RDF linked data representation, and SHOULD support GET requests specifying text/turtle as the acceptable media type and returning a Turtle serialization of RDF content in response. Index Resources MAY support other RDF media types as well. The RDF content of an Index Resource is one RDF data graph representing one of the Indexable Linked Data Provider’s linked data resources.
By retrieving the Indexable Linked Data Source’s Tracked Resource Set, an Indexable Linked Data Consumer can discover the URIs of the Indexable Linked Data Source’s Index Resources. By retrieving the Index Resources, an Indexable Linked Data Consumer can discover the linked data representation of that Index Resource.
Indexable Linked Data Source Access Authorization
Note: This section is normative.
An Indexable Linked Data Source’s Tracked Resource Set resources and the Index Resources listed in them are typically protected resources; to gain access, an Indexable Linked Data Consumer is expected to pass satisfactory credentials with its HTTP requests. In order for a lifecycle tool’s linked lifecycle data to be available to Indexable Linked Data Consumers, these protected resources SHOULD support access from trusted Indexable Linked Data Consumers made on behalf of the Consumers themselves (as opposed to on behalf of particular users).
There are several ways for an Indexable Linked Data Provider to achieve this:
- OAuth 2.0 client credentials - An Indexable Linked Data Provider MAY support OAuth 2.0 authentication [RFC6749] from a trusted client. The Consumer obtains an access token via an OAuth 2.0 client credentials grant, and makes requests passing the access token in a Bearer Authorization header [RFC6750].
- 2-legged OAuth 1.0a - An Indexable Linked Data Provider MAY support OAuth 1.0 authentication [RFC5849] from a trusted client. The Consumer makes requests passing an OAuth Authorization header signed with its consumer key and secret but containing no token (a so-called “2-legged” OAuth request).
- Functional user id - An Indexable Linked Data Provider MAY support HTTP Basic authentication [RFC2617] from a trusted client. The Consumer makes requests passing a Basic Authorization header containing the username and password credentials of a high-privilege “functional user id” with broad read access to linked data.
These protected resources MAY support other HTTP authentication methods as well. This applies to the Indexable Linked Data Source’s Tracked Resource Set resource and its various components and pages, as well as to the Indexable Linked Data Source’s Index Resources.
Access Contexts
Note: This section is normative.
An Indexable Linked Data Consumer that makes a copy of linked data obtained from an Indexable Linked Data Source will likely need to control access to its copy of the data. It is simple enough for an Indexable Linked Data Consumer to allow some users to access its copy, while denying access to other users.
In order to make it feasible for Indexable Linked Data Consumers to offer access control at a finer grain than the whole Indexable Linked Data Source, an Indexable Linked Data Provider can define one or more Access Contexts and associate each of its linked data resources with an Access Context. When configuring an Indexable Linked Data Consumer to work with a particular Indexable Linked Data Source, the administrator can query the Indexable Linked Data Provider for a list of Access Contexts relevant to a particular Indexable Linked Data Source. This allows the administrator to configure access control at the level of Access Contexts within an Indexable Linked Data Source, not just at the level of whole Indexable Linked Data Sources.
For its part, the Indexable Linked Data Provider associates individual resources to Access Contexts, which it reflects with a statement (triple) in the resource’s RDF representation. When the Indexable Linked Data Consumer copies a resource from an Indexable Linked Data Source, this triple brings a record of the association(s) between resource and Access Context(s). This lets the Indexable Linked Data Consumer connect access control rules expressed at the level of Access Contexts with the resource representations copied from the Indexable Linked Data Source. Adding a resource to an Access Context, or removing one from it, changes the RDF representation of the resource. Like other changes affecting the RDF representation of the resource, this change is reported as a Change Event in the Tracked Resource Set for the Indexable Linked Data Source. This lets the Indexable Linked Data Consumer work with Indexable Linked Data Sources with Access Contexts whose set of resources varies dynamically.
This set of Access Contexts within an Indexable Linked Data Source can also change over time. Adding a new Access Context to an Indexable Linked Data Source will generally require an administrator to configure the Indexable Linked Data Consumers working with that Indexable Linked Data Source to add an access control rule for dealing with the additional Access Context.
Access Context Namespace
Note: This section is normative.
The namespace used for resources and properties defined in this specification is as follows:
- Namespace URI: [TBD - using
http://open-services.net/ns/core/acc# provisionally, but this needs to be reviewed]
- Default Prefix:
acc
Associations between Resources and Access Contexts
Note: This section is normative.
The RDF acc:accessContext property is used to indicate that a resource belongs to an Access Context. The resource is the subject; the Access Context is the object.
- Property Name:
accessContext
- Description: Access Context of the resource
- Property URI:
http://open-services.net/ns/core/acc#accessContext
For example, the RDF statement (in Turtle):
@prefix acc: <http://open-services.net/ns/core/acc#> .
<https://a.example.com/defect/2314> acc:accessContext <https://a.example.com/acclist#alpha> .
declares the resource https://a.example.com/defect/2314 to be in the Access Context https://a.example.com/acclist#alpha.
A linked data resource of an Indexable Linked Data Source that is deemed (by the Indexable Linked Data Provider) to be in an Access Context MUST use the acc:accessContext predicate in its RDF representation to assert a relation between the linked data resource (subject) and an Access Context. For example, the above RDF statement embedded in the representation of resource https://a.example.com/defect/2314 asserts that this resource is in Access Context https://a.example.com/acclist#alpha. The RDF representation of a linked data resource in several Access Contexts will have multiple such RDF statements; for a linked data resource not in any Access Context, there will be none.
Appendix A: Samples
(this section is informative)
See samples within the body of this specification.
Appendix B: Resource Shapes
Not applicable
Appendix C: Notices and References
Contributors
- Jim des Rivieres (IBM, OSLC-Core)
- Vivek Garg (IBM, OSLC-Core)
- SteveSpeicher (IBM, OSLC-Core Lead)
- Arthur Ryman (IBM, OSLC-Core)
- Nick Crossley (IBM, OSLC-Core)
- Ian Green (IBM, OSLC-Core)
Reporting Issues on the Specification
The working group participants who author and maintain this working draft specification, monitor a distribution list where issues or questions can be raised, see Core Mailing List
Also the issues found with this specification and their resolution can be found at Core 2.0 Issues.
License and Intellectual Property
We make this specification available under the terms and conditions set forth in the site Terms of Use, IP Policy, and the Workgroup Participation Agreement for this Workgroup.
References
Appendix D: Changes
Category:Specifications
