1.1.1 Deprecated terms

Previous revisions of OSLC-based specifications [OSLCCore2], used terminology that may no longer be relevant, accurate or needed any more. Some of those deprecated terms are:

Provider (deprecated)

See Server [HTTP11].

Consumer (deprecated)

See Client [HTTP11].

1.2.1 Normative references

[ABNF]

D. Crocker; P. Overell. Augmented BNF for Syntax Specifications: ABNF. IETF. Internet Standard. URL: https://tools.ietf.org/html/rfc5234

[CORS]

WHATWG contributors. Fetch standard. WHATWG. Living Standard. URL: https://fetch.spec.whatwg.org/commit-snapshots/d070ea245c6eb66cf4196324f063dc6ab608d9e6/#http-cors-protocol

[HTTP11]

R. Fielding, Ed.; J. Reschke, Ed.. Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing. IETF, June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7230.html

[LDP]

Steve Speicher; John Arwe; Ashok Malhotra. Linked Data Platform 1.0. W3C, 26 February 2015. W3C Recommendation. URL: https://www.w3.org/TR/ldp/

[LDPPaging]

S. Speicher; J. Arwe; A. Malhotra. Linked Data Platform Paging 1.0. http://www.w3c.org. W3C Working Group Note. URL: https://www.w3.org/TR/ldp-paging/

[OSLCCCM1]

Nick Crossley. OSLC Configuration Management 1.0. OASIS. OASIS Working Draft. URL: https://oslc-op.github.io/oslc-specs/specs/config/oslc-config-mgt.html

[OSLCCore2]

S. Speicher; D. Johnson. OSLC Core 2.0. http://open-services.net. Finalized. URL: https://open-services.net/bin/view/Main/OslcCoreSpecification

[OSLCQuery]

Jim Amsden; S. Padgett; S. Speicher; David Honey. OSLC Query Version 3.0. OASIS. Project Specification. URL: https://docs.oasis-open-projects.org/oslc-op/query/v3.0/oslc-query.html

[OSLCTRS3]

Nick Crossley, Axel Reichwein. OSLC Tracked Resource Set 3.0. OASIS. OASIS Working Draft. URL: https://oslc-op.github.io/oslc-specs/specs/trs/tracked-resource-set.html

[OpenIDConnect]

OpenID Connect. openid.net. URL: http://openid.net/connect/

[RFC2119]

S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. IETF, March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119

[RFC8174]

B. Leiba. Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. IETF, May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174

[rfc6749]

D. Hardt, Ed.. The OAuth 2.0 Authorization Framework. IETF, October 2012. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc6749

1.2.2 Informative references

[HTML5]

Ian Hickson; Robin Berjon; Steve Faulkner; Travis Leithead; Erika Doyle Navara; Theresa O'Connor; Silvia Pfeiffer. HTML5. W3C, 27 March 2018. W3C Recommendation. URL: https://www.w3.org/TR/html5/

[LDBestPractices]

Linked Data Best Practices. jazz.net. URL: https://jazz.net/wiki/bin/view/LinkedData/BestPractices

[SHACL]

Holger Knublauch; Dimitris Kontokostas. Shapes Constraint Language (SHACL). http://www.w3.org/. W3C Recommendation. URL: https://www.w3.org/TR/shacl/

[Turtle]

Eric Prud'hommeaux; Gavin Carothers. RDF 1.1 Turtle. W3C, 25 February 2014. W3C Recommendation. URL: https://www.w3.org/TR/turtle/

[WEBARCH]

Ian Jacobs; Norman Walsh. Architecture of the World Wide Web, Volume One. W3C, 15 December 2004. W3C Recommendation. URL: https://www.w3.org/TR/webarch/

[rdf11-concepts]

Richard Cyganiak; David Wood; Markus Lanthaler. RDF 1.1 Concepts and Abstract Syntax. W3C, 25 February 2014. W3C Recommendation. URL: https://www.w3.org/TR/rdf11-concepts/

        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.

      http://open-services.net/ns/[vocab-short-name]/shapes/[SPEC-version]
    

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
    

4.1.1 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. [CORE-4]

OSLC 3.0 servers SHOULD protect resources with [rfc6749] Authentication utilizing [OpenIDConnect]. [CORE-5]

4.1.2 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.

4.1.3 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. [CORE-6]

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. [CORE-7]

OSLC Services SHOULD provide and accept RDF/XML representations for each OSLC resource to preserve compatibility with [OSLCCore2]. [CORE-8]

OSLC Services MAY provide and accept existing standard or emerging standard formats such as XML, HTML, and the Atom Syndication Format. [CORE-9]

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. [CORE-10]

OSLC servers SHOULD support the CORS protocol [CORS] in order to allow browser-based OSLC clients to interact with the server. [CORE-11] 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. [CORE-12]
• OSLC servers SHOULD use the Access-Control-Allow-Headers header [CORS] to allow the use of the OSLC-Core-Version header in OSLC requests. [CORE-13]

4.1.4 Common Vocabulary

Common Vocabulary Terms defines a number of commonly used RDF vocabulary terms and resources (shapes), that have broad applicability across various domains.

4.1.5 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. [CORE-14]

OSLC Services use HTTP for create, retrieve, update and delete operations on resources. OSLC Services MUST comply with the HTTP specification [HTTP11]. [CORE-15]

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: [CORE-16]

• 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. [CORE-17]
• 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. [CORE-18]
• 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. [CORE-19]

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). [CORE-20]

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). [CORE-21]

4.1.6 Selective Properties

OSLC Services MAY support a technique called Selective Properties to enable clients to retrieve only selected property values. [CORE-22]

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.

4.1.7 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.

4.1.8 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.

4.1.9 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. [CORE-24]

4.1.10 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.

GET http://example.com/blogs/entry/1?oslc.paging=true&pageSize=200&pageno=2

<rdf:RDF
   xmlns:oslc_blog="http://open-services.net/ns/bogus/blogs#"
   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
   xmlns:foaf="http://http://xmlns.com/foaf/0.1/"
   xmlns:dcterms="http://purl.org/dc/terms/">

   <oslc_blog:Entry
      rdf:about="http://example.com/blogs/entry/1">
      &lt;!-- partial property values of of the blog entry --&gt;
   </oslc_blog:Entry>

   <oslc:ResponseInfo rdf:about="http://example.com/blogs/entry/1?oslc.paging=true&amp;pageSize=200&amp;pageno=2">
      <oslc:nextPage rdf:resource="http://example.com/blogs/entry/1?oslc.paging=true&amp;pageSize=200&amp;pageno=3" />
   </oslc:ResponseInfo>

</rdf:RDF>

4.1.11 Attachments

Attachments describes a minimal way to manage attachments related to web resources using LDP-Containers and Non-RDF Source [LDP].

4.1.12 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. [CORE-41]

4.1.13 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]. [CORE-42]

4.1.14 Error Responses

Error responses returned by servers in response to requests are defined in Common Vocabulary Terms, Errors.