The following sections and referenced documents define the capabilities for OSLC Core 3.0. These documents
comprise the multi-part specification for OSLC Core 3.0. They represent common capabilities that servers may
provide and that may be discovered and used by clients. Although OSLC Core could be useful on its own, it is
intended to specify capabilities that are common across many domains. Servers will generally specify conformance
with specific domain specifications, and those domain specifications will describe what parts of OSLC Core are
required for conformance. This allows servers to implement the capabilities they need in a standard way without
the burden of implementing capabilities that are not required. The purpose of the OSLC Core Discovery capability
is to allow clients to determine what capabilities are provided by a server. Any provided capability must meet
all the conformance criteria for that capability as defined in the OSLC Core 3.0 specifications.
This implies that any capability that is discoverable is essentially optional, and once discovered, the
capability is provided as defined in the applicable OSLC specifications. Servers should support OSLC Discovery,
but Discovery itself is also an optional capability as servers could provide other means of informing specific
clients of supported OSLC capabilities that could be utilized directly. For example, a server might provide only
preview dialogs on specific resources and nothing else.
Resource Constraints
The shape of an RDF resource is a description of the set of triples it is expected to contain and the
integrity constraints those triples are required to satisfy. Applications of shapes include validating RDF
data, documenting RDF APIs, and providing metadata to tools that handle RDF data such as form and query
builders.
Shapes are different than vocabularies in that shapes may change with new revisions of resource definitions,
whereas vocabularies should evolve in place in a compatible manner.
Constraints on OSLC Core and Domain resources SHOULD be described using
OSLC Core Version 3.0. Part 6: Resource Shape which is included as part of
the OSLC Core multi-part specifications. Servers MAY use other constraint languages such as [[SHACL]] to
define resource constraints.
OSLC Domain specifications SHOULD use the following URI pattern when publishing each individual resource
shape:
http://open-services.net/ns/[vocab-short-name]/shapes/[version]#[shape-name]
For example, for Change Management 3.0, a shape describing the base Change Request resource type might have
the shape URI:
http://open-services.net/ns/cm/shapes/3.0#ChangeRequestShape
Not all shapes would necessarily be updated at the same time.
For example, for Change Management, there should be a resource at:
http://open-services.net/ns/cm/shapes with members such as:
http://open-services.net/ns/cm/shapes/3.0#TaskShape
http://open-services.net/ns/cm/shapes/3.1#WeaknessShape
http://open-services.net/ns/cm/shapes/2.0#ChangeRequestShape
Authentication
Authentication determines how a user of a client identifies themselves to a server to ensure the user has
sufficient privileges to access resources from that server, and provides a mechanism for servers to control
access to resources.
OSLC 3.0 servers MAY protect resources with HTTP Basic Authentication. OSLC Services that use HTTP Basic
Authentication SHOULD do so only via SSL.
OSLC 3.0 servers SHOULD protect resources with [[!rfc6749]] Authentication utilizing [[!OpenIDConnect]].
Resource Discovery
Resource Discovery defines a common approach for HTTP/LDP-based servers to be able to publish their RESTful
API capabilities and how clients can discover and use them.
Resource Representations
OSLC resource representations come in many forms and are subject to standard HTTP and mechanisms for content
negotiation.
OSLC domain specifications specify the representations needed for the specific scenarios that they are
addressing, and should recognize that different representations are appropriate for different purposes. For
example, browser oriented scenarios might be best addressed by JSON or Atom format representations.
OSLC domain specifications are also expected to follow common practices and conventions that are in concert
with existing industry standards and which offer consistency across domains. All of the OSLC specifications
are built upon the standard RDF data model, allowing OSLC to align with the Linked-Data Platform [[!LDP]].
In addition, all OSLC specifications have adopted the convention to illustrate most examples using Turtle
and/or JSON-LD representations and will typically require these representations to enable consistency across
OSLC implementations.
OSLC Services MUST support at least one RDF resource serialization format, and SHOULD support as many
serialization formats as possible through content negotiation.
OSLC Services SHOULD provide and accept RDF documents in Turtle format (identified by the MIME-type
'text/turtle') and in JSON-LD format (identified by the MIME-type 'application/ld+json') representations for
each OSLC resource for compatibility with LDP 1.0.
OSLC Services SHOULD provide and accept RDF/XML representations for each OSLC resource to preserve
compatibility with [[OSLCCore2]].
OSLC Services MAY provide and accept existing standard or emerging standard formats such as XML, HTML, and
the Atom Syndication Format.
OSLC servers SHOULD support the Accept header and whenever possible, respond with one of the content types
requested by the client. When the Accept header requests an unsupported RDF serialization, the OSLC server
SHOULD return an RDF serialization format that it does support, indicating what it is in the Content-Type
header. If the server gets an Accept header for some non-RDF content type, say ATOM, that it does not
support, then it SHOULD return 406 Unacceptable.
OSLC servers SHOULD support the CORS protocol [[!CORS]] in order to allow browser-based OSLC clients to
interact with the server.
In addition to following the general practice, server implementers are recommended to apply the
recommendations listed below:
-
OSLC servers SHOULD use the
Access-Control-Allow-Headers header [[!CORS]] to allow the use of
the Content-Type header in OSLC requests. Despite the Content-Type header being
a CORS-safelisted request header, it needs to be explicitly allowed in order to expand the range of its
permitted values and allow OSLC clients to send RDF contents to the server.
-
OSLC servers SHOULD use the
Access-Control-Allow-Headers header [[!CORS]] to allow the use of
the OSLC-Core-Version header in OSLC requests.
Common Vocabulary
Common Vocabulary Terms defines a number of commonly used RDF vocabulary terms and resources (shapes), that
have broad applicability across various domains.
Resource Operations
Resource Operations specify how clients create, read, update and delete resources managed by servers.
OSLC Core defines a set of HTTP REST services for a set of capabilities that facilitate flexible, loosely
coupled tool integration. These services may be augmented by varous OSLC domain specifications that specify
the capabilities, vocabularies and constraints that define specific resources managed by these integration
capabilities.
OSLC Servers MUST implement standard HTTP protocols and MUST at least support GET requests that
respond with resources in some RDF serialization format.
OSLC Services use HTTP for create, retrieve, update and delete operations on resources. OSLC Services MUST
comply with the HTTP specification [[!HTTP11]].
Because the update process may involve first getting a resource, modifying it and then later putting it back
to the server, there is the possibility of a conflict, e.g. some other client may have have updated the
resource since the GET. To mitigate this problem, OSLC Services SHOULD use the HTTP
If-Match header on a PUT request:
-
If the HTTP
If-Match header is missing OSLC Services SHOULD return HTTP Bad Request (400)
status code to indicate that the header is required.
-
If the HTTP
If-Match header is present OSLC Services MUST behave as described in the HTTP
specification, returning an HTTP Precondition Failed (412) error to indicate that the header does not
match.
-
If the HTTP
If-Match header is present and it matches, but there is some other problem or
conflict with the update then OSLC Services MAY return an HTTP Conflict (409) to indicate that problem.
An OSLC Service SHOULD preserve property values that are not part of the resource definition or Resource
Shape known by the server (unknown property values). An OSLC Service MUST return a 4xx status code if it
decides not to persist any of the unknown property values (in accordance with the LDP specification
§4.2.4.4).
An OSLC Client MUST preserve any unknown property values between requests to the OSLC Services for all HTTP
verbs except PATCH (in accordance with the LDP specification §4.3.1.11).
Selective Properties
OSLC Services MAY support a technique called Selective Properties to enable clients to retrieve only
selected property values.
By adding the key=value pair oslc.properties, specified below, to a resource URI, a client can
request a new resource with a subset of the original resource's values. An additional key=value pair
oslc.prefix can be used to define prefixes used to identify the selected properties.
The oslc.properties key=value pair lets you specify the set of properties to be included in the
response. Both immediate and nested properties may be specified. A nested property is a property that
belongs to the resource referenced by another property. Nested properties are enclosed in brace brackets,
and this nesting may be done recursively, i.e. a nested property may contain other nested properties.
For example, suppose we have a bug report resource at the following URL:
http://example.com/bugs/4242
Suppose this bug resource has properties such as dcterms:title,
dcterms:description, and dcterms:creator, and that
dcterms:creator refers to a person resource that has properties such as
foaf:givenName and foaf:familyName. Suppose you want a representation of the bug
report that includes its dcterms:title and the foaf:givenName and
foaf:familyName of the person referred to by its dcterms:creator. The following
URL illustrates the use of the oslc.properties query value to include those properties:
http://example.com/bugs/4242?oslc.properties=dcterms:title,dcterms:creator{foaf:givenName,foaf:familyName}
The oslc.properties pair is defined by the oslc_properties term in the following BNF grammar:
oslc_properties ::= "oslc.properties=" properties
properties ::= property ("," property)*
property ::= identifier | wildcard | nested_prop
nested_prop ::= (identifier | wildcard) "{" properties "}"
wildcard ::= "*"
identifier ::= PrefixedName
PrefixedName ::= /* see "SPARQL Query Language for RDF", http://www.w3.org/TR/rdf-sparql-query/#rPrefixedName */
In our examples of oslc.properties, property names include a URI prefix, i.e. dcterms: or
foaf:. Here we assume that OSLC has predefined the Dublin Core ( dcterms:) and Friend of a Friend ( foaf:)
prefixes. However, OSLC resources should also be open to new content, which means that new properties may
not have predefined URI prefixes. We therefore need a way to define new URI prefixes in resource requests.
The oslc.prefix value lets you specify URI prefixes used in property names. For example, suppose the foaf:
prefix was not predefined. The following URL illustrates the use of the oslc.prefix value to define it:
http://example.com/bugs/4242?oslc.prefix=foaf=<http://xmlns.com/foaf/0.1/>&oslc.properties=foaf:lastName,...
The syntax of the oslc.prefix is defined by the oslc_prefix term in the following BNF grammar:
oslc_prefix ::= "oslc.prefix=" prefix_defs
prefix_defs ::= prefix_def ("," prefix_def)*
prefix_def ::= prefix "=" uri_ref_esc
prefix ::= PN_PREFIX
PN_PREFIX ::= /* see "SPARQL Query Language for RDF", http://www.w3.org/TR/rdf-sparql-query/#rPN_PREFIX */
uri_ref_esc ::= /* an angle bracket-delimited URI reference in which > and \ are \-escaped. */
OSLC Core specifies a number of predefined PrefixDefinitions for convenience. OSLC Domain specifications may
specify additional pre-defined PrefixDefinitions for their purposes.
Resource Preview
Resource Preview specifies a technique to get a minimal HTML representation of a resource identified by a
URL. Applications often use this representation to display a link with an appropriate icon, a label, or
display a small or large preview when a user makes some gesture over a link.
Delegated Dialogs
Delegated Dialogs allow one application to embed a creation or selection UI into another using HTML
iframe elements and JavaScript code. The embedded dialog notifies the parent page of events
using HTML5 postMessage.
Query
OSLC servers will often manage large amounts of potentially complex link-data entities. Practical use of
this information will require some query capability that minimally supports selection of matching elements,
filtering of desired properties and ordering. OSLC Core defines a query capability that is relatively
simple, can be implemented on a wide range of existing server architectures, and provides a standard, data
source independent query mechanism. The purpose of this query capability is to support tool integration
through a common query mechanism.
OSLC Servers MAY support a Query Capability as defined in [[!OSLCQuery]] to enable clients to
perform selection and projection operations in order to retrieve a selected subset of resources and property
values from an LDPC.
Resource Paging
When a client requests a resource, the client should expect that the entire resource will be returned in the
response, with all property values. This can be problematic because, in some cases, resources may be so
large that a client might not want to retrieve the entire resource in one HTTP response.
One solution for clients that are sensitive to response size is to check the response size before loading.
This method is described in the next section. Another solution is to use Resource Paging.
Resource Paging specifies a capability for servers to make the state of large resources or long lists of
resources available as a list of smaller subset resources (pages) whose representation is easier to produce
by the server and consume by clients. Resource paging is particularly useful in handling results from the
query capability or the contents of an LDP container.
Checking Response Size
Clients that do not wish to load large resources may use the HTTP HEAD method to determine the size of a
resource.
When responding to an HTTP HEAD request, according to [[!HTTP11]] the server SHOULD include an HTTP
Content-Length header that indicates the size of the resource as the "decimal number of octets."
Paging Stability
Because HTTP is a stateless protocol and OSLC Services manage resources that can change frequently, OSLC
clients should assume that the resources returned on a given page are unstable and may change over time.
Some OSLC Servers might wish to guarantee stable paging, meaning that the sequence of pages returned from
the server represent a snapshot in time and will not change as the client pages through them. OSLC
specifications that require stable paging should state this requirement and specify to which resources it
applies.
Note that because stable paging implementations are based on server-side state, it is possible that the
state will expire.
Implementations MAY use the HTTP response code 410 (Expired) to indicate to clients that the link they
requested has expired.
Using Resource Paging
OSLC Services MAY support [[!LDPPaging]] to enable clients to retrieve large LDP resources (LDPRs) a page
at a time.
OSLC Services SHOULD support OSLC paging as described in this section to ensure compatibility with OSLC
2.0 server implementations.
To request a paged version of a resource, a client MUST add at least one "key=value" pair to the query
component of the resource URI: Either oslc.paging=true, or oslc.pageSize, or both.
When responding to a request that includes oslc.paging=true in the URI, a server MAY return a
representation that contains a subset of the resource's property values.
By adding oslc.pageSize to the query component of the resource URI, the client requests that the server
respond with a specific number of property values. For example, oslc.pageSize=20 indicates to the server
that the client would like 20 values per page.
When responding to a request that includes oslc.pageSize in the URI, a server SHOULD return a
representation that contains the requested number of property values.
When Resource Paging is used, the values of a multi-valued property MAY be split across resource pages.
When Resource Paging is used, each property value MUST be represented in its entirety and not split across
multiple partial resource pages.
When a page is returned and it is NOT the last page in the sequence, then it SHOULD include an
oslc:ResponseInfo (see above), which contains a resource-valued property oslc:nextPage that links to a
resource that represents the next page of property-values.
When paging is unstable, by the time a client follows an oslc:nextPage link there may no longer be a next
page, in this case the server MAY respond with an HTTP 404 Page Not Found status code.
Provider Response Size Limitations
When a client requests a resource that an OSLC Service considers to be too large to return in one response
and the client has not indicated that it desires paging (via oslc.paging or oslc.pageSize), the OSLC
Service MAY redirect the client to a representation that contains partial information about the resource.
When the OSLC Service opts to redirect the client to a partial representation, it MUST return an HTTP
Status 302 redirect to a URL that includes either oslc.paging, or oslc.pageSize, or both.
If the URL includes oslc.pageSize then the value should be a value that is acceptable to the service. The
client may choose to follow the redirect and receive a representation that contains partial information
about the resource.
On receiving a resource representation, OSLC Clients should check for the presence of an oslc:nextPage
value to determine if the representation contains partial information about the resource. If the value is
present, then paging is in effect and the representation contains partial information about the resource.
Attachments
Attachments describes a minimal way to manage attachments related to web resources using LDP-Containers and
Non-RDF Source [[!LDP]].
Tracked Resource Sets
OSLC defines a Tracked Resource Set capability that allows servers to expose a set of resources in a way
that enables clients to discover the exact set of resources in the set, to track ongoing changes affecting
resources in the set. This allows OSLC servers to expose a live feed of linked data in a way that permits
clients to build, aggregate, and maintain live, searchable information based on that linked data.
OSLC Servers MAY support a Tracked Resources Set capability as defined in [[!OSLCTRS3]] to enable
OSLC data consumers and providers flexible ways of sharing information.
Configuration Management
OSLC defines a Configuration Management capability for managing versions and configurations of linked data
resources from multiple domains. Using client and server applications that implement the configuration
management capability, a team administrator can create configurations of versioned resources contributed
from tools and data sources across the lifecycle. These contributions can be assembled into aggregate
(global) configurations that are used to resolve references to artifacts in a particular and reproducible
context.
OSLC Clients and Servers MAY support a Configuration Management capability as defined in
[[!OSLCCCM1]].
Error Responses
Error responses returned by servers in response to requests are defined in Common Vocabulary Terms, Errors.
