Notices

Copyright © OASIS Open 2021. All Rights Reserved.

All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual Property Rights Policy (the "OASIS IPR Policy"). The full Policy may be found at the OASIS website.

This specification is published under the Attribution 4.0 International (CC BY 4.0). Portions of this specification are also provided under the Apache License 2.0.

All contributions made to this project have been made under the OASIS Contributor License Agreement (CLA).

For information on whether any patents have been disclosed that may be essential to implementing this specification, and any offers of patent licensing terms, please refer to the Open Projects IPR Statements page.

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to OASIS, except as needed for the purpose of developing any document or deliverable produced by an OASIS Open Project or OASIS Technical Committee (in which case the rules applicable to copyrights, as set forth in the OASIS IPR Policy, must be followed) or as required to translate it into languages other than English.

The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns.

This document and the information contained herein is provided on an "AS IS" basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

OASIS requests that any OASIS Party or any other party that believes it has patent claims that would necessarily be infringed by implementations of this OASIS Project Specification or OASIS Standard, to notify the OASIS TC Administrator and provide an indication of its willingness to grant patent licenses to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification.

OASIS invites any party to contact the OASIS TC Administrator if it is aware of a claim of ownership of any patent claims that would necessarily be infringed by implementations of this specification by a patent holder that is not willing to provide a license to such patent claims in a manner consistent with the IPR Mode of the OASIS Open Project that produced this specification. OASIS may include such claims on its website, but disclaims any obligation to do so.

OASIS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on OASIS' procedures with respect to rights in any document or deliverable produced by an OASIS Technical Committee can be found on the OASIS website. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this OASIS Open Project Specification or OASIS Standard, can be obtained from the OASIS TC Administrator. OASIS makes no representation that any information or list of intellectual property rights will at any time be complete, or that any claims in such list are, in fact, Essential Claims.

The name "OASIS" is a trademark of OASIS, the owner and developer of this specification, and should be used only to refer to the organization and its official outputs. OASIS welcomes reference to, and implementation and use of, specifications, while reserving the right to enforce its marks against misleading uses. Please see https://www.oasis-open.org/policies-guidelines/trademark for above guidance.

Table of Contents

1. Introduction

This section is non-normative.

A common problem with building interoperable solutions is having a mechanism for a client to explore a server API or end-point to learn if the target application supports a set of capabilities. Client applications would then provide features based on what is discovered. For example, a person using a quality management tool wants to be able to record a defect in a change management tool. The integration from the quality management tool will want to be able to do a number of things on behalf of the user and provide an integrated experience to streamline the users workflow. To do this, the quality management tool will need to discover information about the change management tool including:

OSLC Discovery 3.0 defines a capability providing client applications a standard way to introspect servers to determine what resource types the server supports, how to preview, select or create instances of those resources, and any constraints on resource creation or update. Discovery capabilities allow clients to determine what capabilities are provided by a server so they can adapt to, and integrate with different servers in support of end user integration scenarios.

1.1 Terminology

Terminology uses and extends the terminology and capabilities of OSLC Core Overview, W3C Linked Data Platform [LDP], W3C's Architecture of the World Wide Web [WEBARCH], Hyper-text Transfer Protocol [HTTP11].

Discovery
The act of an OSLC Client to be able to determine if an OSLC Server supports a given capability.

1.2 References

1.2.1 Normative references

[HTTP11]
R. Fielding, Ed.; J. Reschke, Ed.. Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7230.html
[LDP]
Steve Speicher; John Arwe; Ashok Malhotra. Linked Data Platform 1.0. 26 February 2015. W3C Recommendation. URL: https://www.w3.org/TR/ldp/
[OSLCCore2]
S. Speicher; D. Johnson. OSLC Core 2.0. Finalized. URL: http://open-services.net/bin/view/Main/OslcCoreSpecification
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc2119
[RFC8174]
B. Leiba. Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. May 2017. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc8174
[ROOT-SERVICES]
J. des Rivieres; S. Speicher. Root Services Specification. Approved. URL: https://jazz.net/wiki/bin/view/Main/RootServicesSpec
[WELL-KNOWN]
M. Nottingham. RFC 8615: Well-Known Uniform Resource Identifiers (URIs). Proposed Standard. URL: https://tools.ietf.org/html/rfc8615

1.2.2 Informative references

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

1.3 Typographical Conventions and Use of RFC Terms

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this specification are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

2. Motivation

This section is non-normative.

Management and use of shared information in complex domains such as IT application lifecycle management and systems and software engineering often involve the integration of many data sources supported by tools developed by different vendors on different technical architectures, and introduced at different times. Integrating these tools in order to support a wide range of evolving end user scenarios requires flexible and loosely coupled interactions between consumers and providers of this shared information. An important way of achieving this flexibility and loose coupling is to allow clients to incrementally discover the capabilities of any given server, and then adapt to what is discovered in order to maximize end user capabilities. Although a client may not know ahead of time what capabilities a given server might provide, they can know a standard means of discovering those capabilities, and can be developed to dynamically adapt to the discovered capabilities.

Key usage scenarios that motivate a number of requirements for discovery include determining if the target tool supports:

Additionally there is motivation to establish a common way for tools to support similar mechanisms so that each new capability doesn't introduce a new discovery model. It is also desired to have capabilities defined, whether within a standards development group or proprietary, to be able to leverage a similar approach to discovery.

Security concerns are also important when managing shared information across organization and tool boundaries. The specific security needs of any application however are difficult to predict. Experience has shown that this variability results in complexity for tool integration and therefore some standard mechanism for authentication discovery is highly desired.

The basis for how clients discover capabilities should be based on the methods established by [LDP] and [HTTP11], and service provider resources defined by [OSLCCore2].

3. Basic Concepts

This section is non-normative.

The following sections introduce the basic concepts of OSLC discovery including how clients find discovery URIs, different approaches clients might use to discover server capabilities, and how server capabilities might be extended.

3.1 Bootstrapping Discovery

This section is non-normative.

Discovery will always have to start with at least one discovery resource URI to bootstrap discovery on that server. Servers must provide some way for clients to learn about, find, or discover such LDPC URIs. For example, servers could provide such information:

The URI could be for a ServiceProviderCatalog or context LDPC resource on which either static up-front or dynamic incremental discovery can be performed. Different server implementation architectures and extensibility mechanisms may require different approaches for discovering OSLC discovery resource URIs.

This specification specifies how servers respond to discovery requests through LDPC Link headers or ServiceProviderCatalog and/or ServiceProvider resources. It does not specify how servers organize their LDPCs, how they make distinguished LDPCs known to end users to start the discovery process, or how servers provide efficient access to discovery information that may be distributed over many LDPCs managed by the server. Servers may choose to support the OSLC Query capability on OSLC LDPCs and discovery resources in order to facilitate access to discovery information.

3.2 Approaches to Discovery

This section is non-normative.

There are various approaches for how servers define and advertise their capabilities, and how clients can efficiently discover what is available. The following sections will provide guidance on approaches that should be used.

OSLC defines two broad approaches for clients to discover capabilities provided by a server, loosely categorized as "Static Up-Front" and "Dynamic Incremental".

Static Up-Front discovery, which is compatible with [OSLCCore2], is an up-front or somewhat more static approach to discovery that utilizes ServiceProviderCatalog, ServiceProvider, and Service resources. Typically a client would perform discovery on startup by accessing the Services defined by any ServiceProvider resources the client might need. A client could also access one or more ServiceProviderCatalog resources in order to locate the available ServiceProvider resources. The client would then configure its capabilities based on what was discovered. In many, or possibly most instances, the ServiceProvider resources will be dynamically created by servers based on the state of the information they manage. Clients may choose to periodically refresh their capabilities by re-reading the ServiceProviders and adapting to the newly available services. Therefore this approach to discovery is not completely static, or up-front, but that does represent a possible common usage pattern.

Figure Fig. 1 Service Provider concepts and relationships illustrates the Service Provider Catalog and Service Provider concepts and relationships. There are two resources defined: Service Provider Catalog and Service Provider, that provide the discovery information. There are also a set of local in-line resources that are provided inside these resources to define namespaces, OAuth configurations, contributors as well as services and their capabilities.

To allow clients to discover the RDF vocabularies supported by a server, those vocabularies should be referenced from the service discovery documents, and the vocabularies themselves and their constraining ResourceShapes should be readable RDF resources. The oslc:domain property references a namespace that should resolve to the vocabulary document.

Fig. 1 Service Provider concepts and relationships

Dynamic Incremental discovery is a second approach that utilizes lazy or deferred discovery, getting just the information that is needed for any client capability when it is needed, and not getting information about server capabilities that might not ever be used. Clients typically utilize HTTP OPTIONS or HEAD methods on LDPCs and get discovery information from Link headers included in the HTTP response. This approach is more applicable for situations where the services provided by a server are changing rapidly as the result of resource creation or update, and clients will need to do incremental discovery before executing the next operations. This approach is also useful for clients that only need to do very specific things and are not necessarily involved in a long-running conversation with a server. Discovery in this case can be a simple HTTP OPTIONS request on the required LDPC and the client can immediately complete its operation without needing to deal with potentially large discovery documents.

Both of these approaches are based on a uniform discovery capability. ServiceProviderCatalog, ServiceProvider and Service resources from [OSLCCore2] are specific kinds of LDP Containers. The members of a ServiceProviderCatalog resource include ServiceProviderCatalogs and ServiceProvider LDPCs. ServiceProvider resource members include Service LDPCs. Each of these LDPCs have additional properties as defined by the OSLC vocabulary and shapes. This allows clients to use either approach to discover server provided OSLC capabilities, and maintains compatibility with [OSLCCore2] while providing new, simple and flexible approaches to service discovery.

3.3 Updating Discovery Information

This section is non-normative.

Servers may chose to support changes to their configurations in order to support adding new domains and services, extending existing domains and services, and/or integrating domains. This specification does not specify how servers provide extensibility mechanisms. Some possible approaches could include:

The ServiceProviderCatalog, ServiceProvider and Service shapes specify that much of the discovery information provided in these resource representations is read-only. Therefore clients accessing these resources cannot expect to change read-only properties via HTTP PUT operation on the discovery resources as a means of updating server configurations. However, these constraints only apply to these particular discovery resource representations and do not prevent servers from providing other means of modifying their configuration information. These modifications would then be reflected in read-only properties in the discovery resource representations when they are accessed.

4. Discovery Capabilities

The following sections define the OSLC Core discovery capabilities.

4.1 General Discovery Methods

The following clauses apply to all discovery capabilities including resource creation, resource preview, delegated dialogs for resource creation and selection, and resource constraints discovery. OSLC discovery capabilities may also apply to OSLC resources themselves, including LDPCs, and the discovery LDPC resources including ServiceProviderCatalog, ServiceProvider and Service resources. This allows servers to dynamically configure their capabilities, or provide users with a means of selecting the capabilities they need from those provided by a server.

Clients SHOULD use HTTP OPTIONS to fetch various headers and other configuration information that may be exposed in the response content body from other HTTP methods. [DIS-1]

Servers SHOULD minimize the use of HTTP response headers on various HTTP operations as to avoid unnecessary additional response content for clients to consume. [DIS-2]

This is also to avoid the complexity on server implementations that would be needed to provide such additional content.

4.2 Well-known URI Bootstrapping

An OSLC Server MAY serve a Root Services document at the /.well-known/oslc/rootservices.xml URI [WELL-KNOWN] if the Server provides access to such a document. The Root Services document SHALL conform to the [ROOT-SERVICES] specification. If no specific content type is requested, or if the requested content type is application/xml or application/rdf+xml, the server SHALL return the Root Services document using the RDF/XML-ABBREV format. Servers MAY return other formats in response to other requested content types. [DIS-3]

An OSLC Server SHOULD serve a Service Provider Catalog at the /.well-known/oslc/sp-catalog URI if the Server provides access to such a document. [DIS-4]

An OSLC Server MAY serve an LDP Container at the /.well-known/oslc/ldpc URI if the Server provides access to such a document. [DIS-5]

An OSLC Server MAY use an HTTP redirect to a URI that satisfies the conformance clauses listed above in response to any request under /.well-known/oslc/ URIs. [DIS-6]

An OSLC Server SHALL NOT serve documents on any vendor-specific URIs under /.well-known/oslc/ not defined in any official OSLC specification. [DIS-7]

4.3 Resource Creation Discovery

Resource creation is done by sending an HTTP POST to a URI that supports resource creation, providing the resource content in the entity request body. Clients can discover resources that support resource creation either through the http://open-services.net/ns/core#creationFactory property of a Service in a ServiceProvider resource, or by using an OPTIONS request on an LDPC to determine if it accepts the POST method.

Servers MAY provide one or more creation factories to enable creation of new resources. Creation factories are LDPCs whose URI MAY be given in the oslc:creationFactory property of a Service resource. [DIS-8]

The existence of an Accept-Post header on an HTTP response to a given Request-URI indicates i) that an HTTP POST will be accepted for authorized requests and ii) what types of content are supported in the entity body of the HTTP POST request. Restating of [LDP] conformance clause about Accept-Post. [DIS-9]

The existence of a Link: <http://www.w3.org/ns/ldp#Container>; rel="type" header on an HTTP response to a given Request-URI will indicate that the resource is a LDP Container. Restating conformance clause for [LDP] Link header and resource types. [DIS-10]

In a response to Request-URI on an LDPC, servers SHOULD include Link headers with the relation-types set to rel="http://open-services.net/core#resourceType" and the Target URIs set to the rdf:type of resources that can be created in the LDPC. [DIS-11]

Note: An LDPC can contain multiple types of resources, and the supported member types may change over time. Since there is always some time between when the test is done and when the creation request is sent, and that there may be additional server enforced constraints on the creation resource representation, there is no guarantee that a future creation request will succeed.

Servers MAY include a RDF triple in resource response body of the form: <container-URI> oslc:resourceType <type-URI>. Clients SHOULD use the predicate oslc:resourceType when converting HTTP Link headers that have http://open-services.net/ns/core#resourceType as the Link-relation ("rel" value) into RDF triples. [DIS-12]

This is to assist with scenarios where client applications may want to use the RDF representation in a query to locate LDP Containers that can be used to create the same resource types.

The following example is an OPTIONS request on the /bugs/ resource that demonstrates some of the discovery capabilities.

Example 1
OPTIONS /bugs/ HTTP/1.1
Host: example.com

The response to this example request indicates that POST is supported for creating resources while the Accept-Post header indicates Turtle and JSON-LD content types are supported. The "type" link header indicates the resource is an LDP BasicContainer. The "resourceType" link headers indicate which resource types are supported on POST. In this case the LDP Container advertises support for creating two types of resources: Bug and Feature. POSTing an entity request body that is not one of these types would result in an error.

Example 2
HTTP/1.1 204 No Content
Date: Thu, 12 Jun 2014 18:26:59 GMT
Allow: POST,GET,OPTIONS,HEAD,PUT
Accept-Post: text/turtle, application/ld+json
Link: <http://www.w3.org/ns/ldp#BasicContainer>; rel="type",
    <http://www.w3.org/ns/ldp#Resource>; rel="type"
Link: <http://open-services.net/ns/cm#Bug>; rel="http://open-services.net/ns/core#resourceType",
    <http://example.com/vocab#Feature>; rel="http://open-services.net/ns/core#resourceType"

4.4 Resource Creation and Update Constraints Discovery

In addition to the ways one can discover if a given OSLC Server supports creation of resources and for which types, it is helpful to understand if there are server-enforced constraints on the resource representation. Clients can discover these constraints either through the http://open-services.net/ns/core#resourceShape property of a Creation Factory resource, or by using Link: <constraint-URI>; rel="http://www.w3.org/ns/ldp#constrainedBy" header on an HTTP response to a given Request-URI.

Servers MAY describe constraints enforced on resource representations through the http://open-services.net/ns/core#resourceShape property of a Creation Factory resource. [DIS-13]

In a response to an HTTP OPTIONS, HEAD or GET method on a given Request-URI referencing an LDPC, servers SHOULD include a Link header with the relation-type set to rel="http://open-services.net/core#constrainedBy" and the Target URI set to the URI of a resource that defines constraints on the to-be created or updated resource representation in the LDPC. The resource referenced by Target URI is RECOMMENDED to be a machine-readable representation such as OSLC ResourceShapes, but MAY be some variant or other constraint document. See [LDP] section about server published constraints. [DIS-14]

Example 3
Link: <http://example.com/shapes/bug>; rel="http://www.w3.org/ns/ldp#constrainedBy"

The link header in the example above would be returned on an OPTIONS or HEAD request to a resource of type <http://open-services.net/ns/cm#Bug> to provide the URI of the creation or update constraints.

In a response to an HTTP POST or PUT method on a given Request-URI referencing an LDPC, servers SHOULD include a Link header with the relation-type set to rel="http://open-services.net/core#constrainedBy" and the Target URI set to the URI of a resource that defines constraints that on the to-be created or updated resource representation in the LDPC that were not satisfied. The resource referenced by Target URI is RECOMMENDED to be a machine-readable representation such as OSLC ResourceShapes, but MAY be some variant or other constraint document. See [LDP] section about server published constraints. [DIS-15]

Example 4
Link: <http://example.com/shapes/bug>; rel="http://www.w3.org/ns/ldp#constrainedBy"

The link header in the example above would be returned on a POST or PUT to a resource of type <http://open-services.net/ns/cm#Bug> that violated the referenced constraint.

Servers MAY include a RDF triple in resource response body of the form: <container-URI> ldp:constrainedBy <shape-URI>. Clients SHOULD use the predicate ldp:constrainedBy when converting HTTP response headers for the same Link-relation type, into an RDF triple. [DIS-16]

This is to assist with scenarios where client applications may want to use the RDF representation in a query to locate LDP Containers that are constraints by the same resource.

4.5 Resource User Interface Preview Discovery

See OSLC Resource Preview for resource preview discovery using the Link header or the Prefer header.

4.6 Resource User Interface Delegated Dialogs Discovery

See Delegated dialogs for resource selection and creation delegated UI discovery using the http://open-services.net/ns/core#selectionDialog or http://open-services.net/ns/core#creationDialog properties of a Service resource, or the Link header or the Prefer header.

4.7 Authentication Discovery

Clients SHOULD determine what authentication schemes a server supports by parsing and processing the challenge sent by the target server in response to a request for a protected resource. [DIS-17]

Servers MAY provide OAuth configuration information in the OAuthConfiguration member of a ServiceProviderCatalog as described in 5. Resource Constraints. [DIS-18]

5. Resource Constraints

This document applies the following constraints to the OSLC Core vocabulary terms.

5.1 Resource: ServiceProviderCatalog

ServiceProviderCatalog Properties
Prefixed Name Occurs Read-only Value-type Representation Range Description
dcterms:description Zero-or-one true XMLLiteral N/A Unspecified Description of the services provided.
dcterms:publisher Zero-or-one true AnyResource Inline oslc:Publisher Describes the software product that provides the implementation.
dcterms:title Zero-or-one true XMLLiteral N/A Unspecified Title of this resource.
oslc:domain Zero-or-many true Resource Reference Unspecified Namespace URI of the specification that is implemented by this service. In most cases this namespace URI will be for an OSLC domain, but other URIs MAY be used [DIS-20].
oslc:oauthConfiguration Zero-or-many true AnyResource Inline oslc:OAuthConfiguration Defines the three OAuth URIs required for a client to act as an OAuth consumer.
oslc:serviceProvider Zero-or-many true AnyResource Either oslc:ServiceProvider A service provider LDPC offered by this server.
oslc:serviceProviderCatalog Zero-or-many true AnyResource Either oslc:ServiceProviderCatalog Additional service provider catalog LDPCs used to organize services.

5.2 Resource: ServiceProvider

ServiceProvider Properties
Prefixed Name Occurs Read-only Value-type Representation Range Description
dcterms:description Zero-or-one true XMLLiteral N/A Unspecified Description of the services provided.
dcterms:publisher Zero-or-one true AnyResource Inline oslc:Publisher Describes the software product that provides the implementation.
dcterms:title Zero-or-one true XMLLiteral N/A Unspecified Title of this resource.
oslc:details Zero-or-many true Resource Reference Unspecified A URL that may be used to retrieve a resource to determine additional details about the service provider such as a web page describing it.
oslc:oauthConfiguration Zero-or-many true AnyResource Inline oslc:OAuthConfiguration Defines the three OAuth URIs required for a client to act as an OAuth consumer.
oslc:prefixDefinition Zero-or-many true AnyResource Inline oslc:PrefixDefinition Defines a namespace prefix for use in JSON representations and in forming OSLC Query Syntax strings.
oslc:service One-or-many true AnyResource Inline oslc:Service Describes a service LDPC offered by the service provider.

5.3 Resource: Service

Service Properties
Prefixed Name Occurs Read-only Value-type Representation Range Description
oslc:creationDialog Zero-or-many true AnyResource Inline oslc:Dialog Enables clients to create a resource via UI.
oslc:creationFactory Zero-or-many true AnyResource Inline oslc:CreationFactory An LDPC that enables clients to create new resources.
oslc:domain Exactly-one true Resource Reference Unspecified Namespace URI of the specification that is implemented by this service. In most cases this namespace URI will be for an OSLC domain, but other URIs MAY be used [DIS-21].
oslc:queryCapability Zero-or-many true AnyResource Inline oslc:QueryCapability Enables clients query across a collection of resources.
oslc:selectionDialog Zero-or-many true AnyResource Inline oslc:Dialog Enables clients to select a resource via UI.
oslc:usage Zero-or-many true Resource Reference Unspecified An identifier URI for the domain specified usage of this resource. If a resource has multiple uses, it may designate the primary or default one that should be used with a property value of oslc:default.

5.4 Resource: CreationFactory

CreationFactory Properties
Prefixed Name Occurs Read-only Value-type Representation Range Description
dcterms:title Exactly-one true XMLLiteral N/A Unspecified Title string that could be used for display.
oslc:creation Exactly-one true Resource Reference ldp:Container To create a new resource via the factory, post it to this URI.
oslc:label Zero-or-one true string N/A Unspecified Very short label for use in menu items.
oslc:resourceShape Zero-or-many true Resource Reference oslc:ResourceShape A Creation Factory MAY provide Resource Shapes that describe shapes of resources that may be created [DIS-22].
oslc:resourceType Zero-or-many true Resource Reference rdfs:Class The expected resource type URI of the resource that will be created using this creation factory. These would be the URIs found in the result resource's rdf:type property.
oslc:usage Zero-or-many true Resource Reference Unspecified An identifier URI for the domain specified usage of this resource. If a resource has multiple uses, it may designate the primary or default one that should be used with a property value of oslc:default.

5.5 Resource: QueryCapability

QueryCapability Properties
Prefixed Name Occurs Read-only Value-type Representation Range Description
dcterms:title Exactly-one true XMLLiteral N/A Unspecified Title string that could be used for display.
oslc:label Zero-or-one true string N/A Unspecified Very short label for use in menu items.
oslc:queryBase Exactly-one true Resource Reference Unspecified The base URI to use for queries. Queries are invoked via HTTP GET on a query URI formed by appending a key=value pair to the base URI, as described in Query Capabilities section.
oslc:resourceShape Zero-or-one true Resource Reference oslc:ResourceShape The Query Capability SHOULD provide a Resource Shape that describes the query base URI [DIS-23].
oslc:resourceType Zero-or-many true Resource Reference rdfs:Class The expected resource type URI that will be returned with this query capability. These would be the URIs found in the result resource's rdf:type property.
oslc:usage Zero-or-many true Resource Reference Unspecified An identifier URI for the domain specified usage of this query capability. If a service provides multiple query capabilities, it may designate the primary or default one that should be used with a property value of oslc:default.

5.6 Resource: Publisher

Publisher Properties
Prefixed Name Occurs Read-only Value-type Representation Range Description
dcterms:identifier Exactly-one unspecified string N/A Unspecified A URN that uniquely identifies the implementation.
dcterms:title Exactly-one true XMLLiteral N/A Unspecified Title string that could be used for display.
oslc:icon Zero-or-one true Resource Reference Unspecified URL to an icon file that represents the provider. This icon should be a favicon format and 16x16 pixels in size.
oslc:label Zero-or-one true string N/A Unspecified Very short label for use in menu items.

5.7 Resource: PrefixDefinition

PrefixDefinition Properties
Prefixed Name Occurs Read-only Value-type Representation Range Description
oslc:prefix Exactly-one true string N/A Unspecified Namespace prefix to be used for this namespace.
oslc:prefixBase Exactly-one true Resource Reference Unspecified The base URI of the namespace.

5.8 Resource: OAuthConfiguration

OAuthConfiguration Properties
Prefixed Name Occurs Read-only Value-type Representation Range Description
oslc:authorizationURI Exactly-one true Resource Reference Unspecified URI for obtaining OAuth authorization.
oslc:oauthAccessTokenURI Exactly-one true Resource Reference Unspecified URI for obtaining OAuth access token.
oslc:oauthRequestTokenURI Exactly-one true Resource Reference Unspecified URI for obtaining OAuth request token.

6. Conformance

Implementations of this specification need to satisfy the following conformance clauses.

Clause Number Requirement
DIS-1 Clients SHOULD use HTTP OPTIONS to fetch various headers and other configuration information that may be exposed in the response content body from other HTTP methods.
DIS-2 Servers SHOULD minimize the use of HTTP response headers on various HTTP operations as to avoid unnecessary additional response content for clients to consume.
DIS-3 An OSLC Server MAY serve a Root Services document at the /.well-known/oslc/rootservices.xml URI [WELL-KNOWN] if the Server provides access to such a document. The Root Services document SHALL conform to the [ROOT-SERVICES] specification. If no specific content type is requested, or if the requested content type is application/xml or application/rdf+xml, the server SHALL return the Root Services document using the RDF/XML-ABBREV format. Servers MAY return other formats in response to other requested content types.
DIS-4 An OSLC Server SHOULD serve a Service Provider Catalog at the /.well-known/oslc/sp-catalog URI if the Server provides access to such a document.
DIS-5 An OSLC Server MAY serve an LDP Container at the /.well-known/oslc/ldpc URI if the Server provides access to such a document.
DIS-6 An OSLC Server MAY use an HTTP redirect to a URI that satisfies the conformance clauses listed above in response to any request under /.well-known/oslc/ URIs.
DIS-7 An OSLC Server SHALL NOT serve documents on any vendor-specific URIs under /.well-known/oslc/ not defined in any official OSLC specification.
DIS-8 Servers MAY provide one or more creation factories to enable creation of new resources. Creation factories are LDPCs whose URI MAY be given in the oslc:creationFactory property of a Service resource.
DIS-9 The existence of an Accept-Post header on an HTTP response to a given Request-URI indicates i) that an HTTP POST will be accepted for authorized requests and ii) what types of content are supported in the entity body of the HTTP POST request. Restating of [LDP] conformance clause about Accept-Post.
DIS-10 The existence of a Link: <http://www.w3.org/ns/ldp#Container>; rel="type" header on an HTTP response to a given Request-URI will indicate that the resource is a LDP Container. Restating conformance clause for [LDP] Link header and resource types.
DIS-11 In a response to Request-URI on an LDPC, servers SHOULD include Link headers with the relation-types set to rel="http://open-services.net/core#resourceType" and the Target URIs set to the rdf:type of resources that can be created in the LDPC.
DIS-12 Servers MAY include a RDF triple in resource response body of the form: <container-URI> oslc:resourceType <type-URI>. Clients SHOULD use the predicate oslc:resourceType when converting HTTP Link headers that have http://open-services.net/ns/core#resourceType as the Link-relation ("rel" value) into RDF triples.
DIS-13 Servers MAY describe constraints enforced on resource representations through the http://open-services.net/ns/core#resourceShape property of a Creation Factory resource.
DIS-14 In a response to an HTTP OPTIONS, HEAD or GET method on a given Request-URI referencing an LDPC, servers SHOULD include a Link header with the relation-type set to rel="http://open-services.net/core#constrainedBy" and the Target URI set to the URI of a resource that defines constraints on the to-be created or updated resource representation in the LDPC. The resource referenced by Target URI is RECOMMENDED to be a machine-readable representation such as OSLC ResourceShapes, but MAY be some variant or other constraint document. See [LDP] section about server published constraints.
DIS-15 In a response to an HTTP POST or PUT method on a given Request-URI referencing an LDPC, servers SHOULD include a Link header with the relation-type set to rel="http://open-services.net/core#constrainedBy" and the Target URI set to the URI of a resource that defines constraints that on the to-be created or updated resource representation in the LDPC that were not satisfied. The resource referenced by Target URI is RECOMMENDED to be a machine-readable representation such as OSLC ResourceShapes, but MAY be some variant or other constraint document. See [LDP] section about server published constraints.
DIS-16 Servers MAY include a RDF triple in resource response body of the form: <container-URI> ldp:constrainedBy <shape-URI>. Clients SHOULD use the predicate ldp:constrainedBy when converting HTTP response headers for the same Link-relation type, into an RDF triple.
DIS-17 Clients SHOULD determine what authentication schemes a server supports by parsing and processing the challenge sent by the target server in response to a request for a protected resource.
DIS-18 Servers MAY provide OAuth configuration information in the OAuthConfiguration member of a ServiceProviderCatalog as described in 5. Resource Constraints.
DIS-19 Servers MAY also organize the ServiceProviders in one or more ServiceProviderCatalog LDPCs to enable OSLC clients to find ServiceProviders offered
DIS-20 In most cases this namespace URI will be for an OSLC domain, but other URIs MAY be used
DIS-21 In most cases this namespace URI will be for an OSLC domain, but other URIs MAY be used
DIS-22 A Creation Factory MAY provide Resource Shapes that describe shapes of resources that may be created
DIS-23 The Query Capability SHOULD provide a Resource Shape that describes the query base URI
DIS-24 Service Providers MUST provide a Prefix Definition for each prefix supported by the service
DIS-25 Each Prefix Definition defines a namespace prefix that clients MAY use in forming OSLC Query Syntax strings
DIS-26 Service Providers that support OAuth Authentication SHOULD provide a way for clients to automatically discover the three OAuth URIs necessary to act as an OAuth Consumer