This document outlines a common approach for HTTP/LDP-based servers to be able to publish their RESTful API
capabilities and how clients discover and use them.
Status:
This document was last revised or approved by the membership of OASIS on the above date.
The level of approval is also listed above.
Check the “Latest stage” location noted above for possible later revisions of this document.
Any other numbered Versions and other technical work produced by the Open Project are listed at
https://open-services.net/about/.
Comments on this work can be provided by opening issues in the project repository
or by sending email to the project’s public comment list
oslc-op@lists.oasis-open-projects.org.
The English version of this specification is the only normative version. Non-normative
translations may also be available.
Note that any machine-readable content
(Computer Language Definitions)
declared Normative for this Work Product is provided in separate plain text files.
In the event of a discrepancy between any such plain text file and display content
in the Work Product's prose narrative document(s), the content in the separate plain text file prevails.
Citation format:
When referencing this specification the following citation format should be used:
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.
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.
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:
How to authenticate
If the target tool is capable of receiving creation requests for defects
Whether defect creation can be handled via a user interface
What fields are required, with what types of data
If the defect record can be pre-filled with some data from the test currently being executed
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.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:
A certain authentication model (OAuth2, OpenID Connect, HTTPS Basic)
Creating resources with a given type
User interface previews of a given resource
User interface dialogs for creating or selecting resources of given types
Prefilling dialogs for resource creation
Describing the constraints on a resource creation or update request (allowable properties or values)
Querying resources to select specific instances and property values
Adding attachments to resources
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:
In their user documentation or UI
Using HTTP OPTIONS * to return a ServiceProviderCatalog or link headers to root LDPCs
describing the discovery capabilities offered
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. 1Service 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. 1Service 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:
Configuration information could be provided through files that are read at startup to define the service
providers and services for the supported domains. These files could utilize the ServiceProviderCatalog and
ServiceProvider resource formats.
Servers may provide administration facilities or operational modes (through commands, REST services, GUI,
etc.) that:
Create and configure additional LDPCs that provide new services
Define or extend domain vocabularies
Define or extend resource shapes to constrain vocabularies for specific purposes
Servers may choose to support these configuration changes only on restart, or dynamically at runtime.
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.
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]
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]
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
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.
Description: An LDPC describing an OSLC server that offers one or more ServiceProvider LDPCs. Servers MAY also organize the ServiceProviders in one or more ServiceProviderCatalog LDPCs to enable OSLC clients to find ServiceProviders offered [DIS-19]. The members of these catalogs may include other nested catalogs as well as service providers.
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.
Description: An LDPC whose properties describe specific services offered by a server, and the URIs to use for those services in the context of that ServiceProvider.
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.
Description: A Creation Factory describes a capability for creating resources, including an LDPC capable of creating and containing new resources via HTTP POST.
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.
Description: A Query Capability describes a query capability, capable of querying resources via HTTP GET or POST.
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.
Description:Service Providers MUST provide a Prefix Definition for each prefix supported by the service [DIS-24]. Each Prefix Definition defines a namespace prefix that clients MAY use in forming OSLC Query Syntax strings [DIS-25].
Description: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 [DIS-26].
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.
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.
Servers SHOULD minimize the use of HTTP response headers on various HTTP operations as to avoid unnecessary
additional response content for clients to consume.
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.
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.
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.
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.
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.
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.
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.
Servers MAY describe constraints enforced on resource representations through the
http://open-services.net/ns/core#resourceShape property of a Creation Factory resource.
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.
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.
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.
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.
Servers MAY provide OAuth configuration information in the OAuthConfiguration member of a
ServiceProviderCatalog as described in 5.Resource Constraints.
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
