-- DaveJohnson - 10 May 2010

OSLC Core Specification Version - OBSOLETE

By: The OSLC Core Specification Workgroup

This is a DRAFT document that has been abandoned and replaced by OSLC Core Spec DRAFT

---

Overview

The Open Services for Lifecycle Collaboration (OSLC) initiative is creating an family of web services specifications for products, services and other tools that support all phases of the software and product lifecycle. The purpose of these specifications is to enable integration between products that support Application Life-cycle Management (ALM) and Product Life-cycle Management (PLM). Each part of the lifecycle or domain has its own work group and specification, for example there are Change Management, Quality Management, Estimation & Measurement and more. Each of the domain specifications are built upon this core specification.

This OSLC Core Specification sets out the common features that every OSLC Service can be expected to support using terminology from the World Wide Web Consortium (W3C). New terminology that we introduce can be found in the glossary section below. This specification is most about OSLC Services, it specifies what OSLC Services MUST, SHOULD and MAY do. It also contains some requirements for other OSLC specifications and for OSLC clients.

OSLC services are accessible via a Service Provider Resource that describes the Services offered. Each Service can provide Creation Factories for resource creation, a Query Capabilities for resource query and Delegated UI Dialogs to enable clients to create and select resources via a web UI. Query Capabilities and Creation Factories may offer Resource Shapes that describe the property names and types of resources managed by the service. This is illustrated in the diagram below. See the section below on Service Provider Resources for further discussion of these concepts.

OSLC Core Specification concepts and relationships

This specification establishes terminology and rules for defining resources in terms of the property names and value-types that are allowed and required. OSLC domain specifications are expected to use these rules and terminologies to describe their resources. See the OSLC Defined Resources section for more on this topic.

This specification also sets out rules for creating resource representations in RDF/XML, JSON, Atom and Turtle formats. OSLC domain specifications are expected to refer to these rules when specifying how their resources are to be represented. See the OSLC Defined Resource Representations section for the representation rules and examples of each format.

We are using the version number 2.0 even though there has never been an OSLC Core Version 1.0 specification. We do this because this OSLC Core specification was written after a series of version 1.0 domain specifications were finalized by OSLC workgroups. The version 2.0 domain specifications will all be based on this Core specification and to avoid confusion this specification will also be known as Version 2.0.

A word about RDF. The resource, property, value data model used for OSLC resources is based on Resource Description Framework (RDF) and OSLC requires RDF representations, but OSLC does not require implementers to provide an RDF triple-store or a SPARQL query-engine.

A word about Atom. Atom Publishing Protocol (APP) and Atom Syndication Format (ASF) formats are referenced in this document, but OSLC is not APP and OSLC implementations do not have to comply with APP.

Design considerations

The core philosophies of OSLC are to build on the powerful and scalable architecture of the World Wide Web and to do the simplest possible things that will work.

Build on the WWW. OSLC builds on the architecture of the WWW and follows the REST architectural pattern. This means that OSLC services provide a uniform HTTP interface, OSLC URIs are stable and opaque and, in simple terms, OSLC works like the web.

Keep things simple. Doing the simplest things that will possibly work means a couple of different things in regard to OSLC. It means starting with simple and existing concepts. For example, we model everything as resources with property values and do not stray from that model. It also means limiting the number of other specifications that we reference. Keeping things simple means building on established and well-known specifications, but also carefully limiting the number of other specifications that we reference. This simplicity is intended to enable loose coupling and to make life easier for everybody: OSLC domain work groups, OSLC service implementers and OSLC client developers.

Accommodate different schemas. Because of the breadth of the OSLC domains, spanning lifecycle and platforms, OSLC has to work for systems with very different data schemas or no schemas at all. Flexibility is needed, but some OSLC Services must be able to offer resource shape information so that clients can learn what properties are allowed and required for resource creation, query and reporting.

Accommodate different representations. Different client platforms might require or at least prefer different representations. For example, in the browser a JSON or or Atom format representation might work best. OSLC Services will all support RDF/XML and may support other formats including JSON, Atom and Turtle.

Glossary of terms

This is a guide to some of the terminology used in this document. The following definitions are standard W3C concepts. OSLC uses these concepts without modification – their definitions are summarized here for the convenience of the reader. See http://www.w3c.org.

• Resource: A network data object or service that can be identified by a URI. Resources may be available in multiple representations (e.g. multiple languages, data formats, size, resolutions) or vary in other ways. (reference: HTTP)

• Representation: An HTTP payload entity, included in an HTTP response, that is subject to content negotiation. There may exist multiple representations. associated with a particular HTTP response status. (reference: HTTP)

• URI: Uniform Resource Identifiers are simply formatted strings which identify--via name, location, or any other characteristic -- a resource (reference: HTTP)

Here are the OSLC specific terms used in this specification:

• OSLC Domain: an OSLC Domain is one ALM or PLM topic area such as Change Management, Requirements management or Automation. Each OSLC Domain will have its own OSLC specification that complies with this Core specification.

• OSLC Service: a set of capabilities that enable a web client to create, retrieve, update and delete resources managed by an ALM or PLM product or online service offering and associated with one OSLC Domain.

• OSLC Service Provider: a product or online service offering that provides an implementation of one or more OSLC Services, which may themselves implement different OSLC Domain specifications.

• OSLC Resource: a resource that is managed by an OSLC Service, may have properties and may link to other resources including those provided by other OSLC Services.

• OSLC Defined Resource: a resource that is either defined by an OSLC specification, defined by an OSLC Resource Shape or both.

• OSLC Defined Properties: resource properties that are defined by an OSLC specification, defined by an OSLC Resource Shape or both.

• OSLC Resource Shape: defines the set of OSLC Properties expected by a particular service or operation and for each their value types, allowed values, cardinality and optionality. Examples of such operations include OSLC Creation Resource and Query Resource. Other examples might include applications that display data in tables.

• OSLC Creation Factory. An OSLC Service may provide one or more creation factories to enable the creation of new resources. A creation factory provides a URI used to create new resources via HTTP POST and may also provide Resource Shapes that describe the types of resources that may be created.

• OSLC Query Capability: An OSLC Service may provide one or more query capabilities to enable query of resources. A query capability provides a base URI for forming query resource URIs and, optionally, Resource Shapes that describe the property values that may be expected in the resources that are queryable via the query capability.

• OSLC Response Info Resource: An OSLC Defined Resource that provides information about a query result, e.g. the next page in a multi-page query result representation.

Notation and Conventions

The key words "MUST", "MUST NOT", "REQUIRED, SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY" and "OPTIONAL" in this document are to be interpreted as described in RFC2119.

---

OSLC Defined Resources

An OSLC Resource is a resource managed by an OSLC Service. An OSLC Resource is typically something like a Change Request, a Requirement or some other ALM or PLM artifact or record, but an OSLC Resource could also be a video or a presentation file. This resource could be stored in a relational database, a flat-file on disk or a source code control system.

An OSLC Service can manage any type of resource and of any content type, but OSLC also defines a special set of resources. OSLC Defined Resources are specified in this document and can be specified in any OSLC specification. Resources are defined by the properties that are allowed and required in the resource.

Defining a an OSLC resource

OSLC uses a simple model of resources with property values and this model is intended to be consistent with the Resource Description Framework (RDF) data model (reference: RDF Concepts). OSLC also builds upon the Extensible Markup Language (XML) namespace mechanism (reference: XML Namespaces). When defining a resource or a property, OSLC Specifications define its name as a URI and its type as a URI. We abbreviate the resource's or property's name as a Prefixed Name (reference: Prefixed Names), which is represented in XML as a QName.

Before resources are defined, we must first define a domain.

Defining an OSLC Domain

This specification defines a set of core resources with properties, and recommends common properties that may be used by other OSLC specifications. Each OSLC domain is expected to define it's own resources and properties. Each OSLC domain is also expected to define a namespace, consisting of a Namespace URI and a default prefix.

• Namespace URI (URI): the Namespace URI of the resource's name. All resources and properties defined within an OSLC domain specification will typically share the same namespace URI. For example, all resources and properties that we define in this specification are given the Namespace URI or http://open-services.net/xmlns/oslc#.
• Default Prefix (String): names that exist within a namespace are prefixed with a string that services as an abbreviation of the Namespace URI. OSLC domains that support the OSLC Query Syntax (defined below) MUST define default prefixes for all of the namespaces that they use.

The namespace used for resources defined in this specification is defined as follows:

• Namespace URI: http://open-services.net/xmlns/oslc#
• Default Prefix: oslc

Once a domain is defined, resources within it can be defined.

Defining an OSLC Resource

OSLC Specifications MUST provide the following information when defining an OSLC Defined Resource or Resource value-type:

• Name (String): name of the the resource which MUST be valid as the Local Name part of a QName (reference: XML Namespaces).
• Type URI (URI): The Type URI of the resource, also known as the RDF Type. Per the rules of Prefixed Names, the Type URI is formed by appending the Name to to the end of the Namespace URI. For example, the resource named Service (defined below) gets the Type URI of http://open-services.net/xmlns/oslc#Service.

Once a resource is defined, its allowed and required properties can be defined.

Defining OSLC Properties

OSLC Specifications MAY provide the a list of properties allowed and/or required in an OSLC Defined Resource. Specifications that do so SHOULD provide the following information for each property that they define.

• Name (String): name of the the resource which MUST be valid as the Local Name part of a QName (reference: XML Namespaces).
• Title (String): Title of the property.
• Description (String): Description of the property.
• Occurs (String): may be 'exactly-one', 'at-most-one', 'zero-or-many' or 'one-or-many'.
• Extended (Boolean): if true this indicates that the property value, then in OSLC services that support OSLC Query Syntax this property value MAY only occur in resources whose URI includes the oslc.properties parameter.
• Value-types (URI): A property MAY allow multiple the value-types, each value-type MUST be a URI that corresponds to one of the following:
  • Literal value-types:
    • Boolean: a boolean type as specified by XSD Boolean ( http://www.w3.org/2001/XMLSchema#boolean, reference: XSD Datatypes).
    • DateTime: a Date and Time type as specified by XSD dateTime ( http://www.w3.org/2001/XMLSchema#dateTime, reference: XSD Datatypes).
    • Integer: an integer number type as specified by XSD Integer ( http://www.w3.org/2001/XMLSchema#integer, reference: XSD Datatypes).
    • Decimal: a decimal number type as specified by XSD Decimal ( http://www.w3.org/2001/XMLSchema#decimal, reference: XSD Datatypes).
    • Double: a double floating-point number type as specified by XSD Double ( http://www.w3.org/2001/XMLSchema#double, reference: XSD Datatypes).
    • Float: a floating-point number type as specified by XSD Float ( http://www.w3.org/2001/XMLSchema#float, reference: XSD Datatypes).
    • String: a string type as specified by XSD String ( http://www.w3.org/2001/XMLSchema#string, reference: XSD Datatypes).
    • National Language String: a string type based on XSD String ( http://open-service.net/xmlns/oslc-core-1.0#MultiLanguageString). Used in cases where multiple translations of a string must be provided. Each value represents one language.
    • XMLLiteral: a Literal XML value ( http://www.w3.org/1999/02/22-rdf-syntax-ns#XMLLiteral).
  • Resource value-types:
    • Resource: value is a resource available at a specified URI, represented in RDF/XML as an element with an rdf:resource attribute that specifies the URI.
    • Local Resource: value is local to the current resource and available only via a local ID, represented in RDF/XML as an element with an rdf:nodeID attribute that specifies the local ID. Used to reference a Local Inline Resource.
    • Inline Resource: value is a resource available at a specified URI, but with property values represented inline in the current resource, represented in RDF/XML as an element containing property value elements and with an rdf:about attribute specifying the URI.
    • Local Inline Resource: value a resource that is local to the current resource, which contains property values, represented in RDF/XML as an element containing property value elements and MAY have an rdf:nodeID attribute specifying the resource’s local ID.

In the rest of this document we will define OSLC resources as described above. The below section titled OSLC Defined Resource Representations defines how OSLC resources are to be represented in RDF/XML, JSON and other formats.

Unknown properties and content

For OSLC Defined Resources, clients should assume that an OSLC Service will discard unknown property values. An OSLC Service MAY discard property values in an OSLC Defined Resource that are not part of the resource's definition or the relevant Resource Shape.

Resource Operations

OSLC Services use HTTP for operations on resources, that comply with the HTTP specification (reference: HTTP).

Resource Creation

To create an OSLC Defined Resource, or any type of resource managed by a service, an OSLC client HTTP POSTs a representation of that resource to a Creation URI. See the section on Creation Factories for more information.

Resource Removal

To delete an OSLC Defined Resource, or any type of resource managed by a service, a client performs an HTTP DELETE on the resource's URI.

Resource Update

To update an OSLC Resource in an OSLC Service, a client fetches a representation of that resource via HTTP GET. The client updates the representation and then uses HTTP PUT to send he new representation to the resource's URI.

Because the update process involves first getting a resource, modifying it and then later putting it back to the server there is the possibility of a conflict. Some other client may have have updated the resource. To mitigate this problem, OSLC Services can use the HTTP If-Match header:

• If the HTTP If-Match header is missing OSLC services MAY return HTTP Bad Request (400) status code to indicate that the header is required.
• If the HTTP If-Match header is present OSLC services will behave as described in the HTTP specification, returning an HTTP Precondition Failed (412) error to indicate that the header does not match.
• If the HTTP If-Match header is present and it matches, but there is some other problem or conflict with the update then OSLC services MAY return an HTTP Conflict (409) to indicate that problem.

OSLC Services MAY use other techniques for resource update such as OSLC Core Guidance: Partial Update.

Common Properties

OSLC domains specifications are strongly encouraged to use the common properties defined by this Core specification (See Appendix A for Common Properties) rather than defining new properties.

Next we cover Resource Shapes, a way to provide a resource definition in a machine readable form.

---

Resource Shapes

In some cases, to create resources and to query those that already exist within an OSLC Service, OSLC clients needs a way to learn which properties are commonly used in or required by the service. Resource Shape Resources meet this need.

A Resource Shape describes the properties that are allowed or required by one type of resource. An OSLC Creation Factory can provide a Resource Shape so that you know what properties are allowed and required to create a resource. An OSLC Query Capability can provide a Resource Shape so that you know what properties are available for query. And, within a Resource Shape, a resource value-type can provide its own Resource Shape.

Conceptual Model

A Resource Shape is an resource that defines the allowed or required properties of one type of resource. As you can see in the diagram below a resource shape contains properties, and properties with Resource value-types can specify their own shapes.

The next sections define the Resource Shape and Property resources.

Resource: Resource Shape

A Resource Shape resource can have a title and a type.

• Name: Shape
• Suggested Prefix: oslc
• Namespace URI: http://open-services.net/xmlns/oslc#
• Type URI: http://open-services.net/xmlns/oslc#Shape
• Version String: oslc-core-1.0
• Properties
  • rdf:type (Resource, exactly-one): a Query Resource MUST include one rdf:type property with value of http://open-services.net/xmlns/oslc#Shape
  • oslc:describes (Resource, exactly-one): Type URI of the resource described by this shape.=
  • dc:title (String, zero-or-one): a Query Resource SHOULD include a meaningful and non-empty title.
  • oslc:property (Local Inline Resource of type oslc:Property, zero-or-more): the properties that are allowed or required by this shape.
  • Other properties MAY be specified by OSLC Services

Resource: Allowed Values

• Name: AllowedValues
• Suggested Prefix: oslc
• Namespace URI: http://open-services.net/xmlns/oslc#
• Type URI: http://open-services.net/xmlns/oslc#AllowedValues
• Properties
  • rdf:type (Resource, zero-or-more): a Query Resource MUST include one rdf:type property with value of http://open-services.net/xmlns/oslc#AllowedValues
  • oslc:allowedValue (Any value-type, one-or-many): value allowed for a property
  • Other properties MAY be specified by OSLC Services

Value-type: Property

A Property resource describes one allowed or required property of a resource.

• Name: Property
• Suggested Prefix: oslc
• Namespace URI: http://open-services.net/xmlns/oslc#
• Type URI: http://open-services.net/xmlns/oslc#Property
• Properties
  • rdf:type (Resource, exactly-one) - The type of property being defined
  • oslc:name (String, exactly-one) - Name of property being defined
  • oslc:namespace (Resource, exactly-one) - Namespace of property
  • dc:title (National Language String, one-or-more): name of the property
  • dc:description (String, at-most-one): description of the property
  • oslc:extended (Boolean, at-most-one): indicates that property is an extended property
  • oslc:hidden (Boolean, at-most-one): a hint that indicates that property MAY be hidden when presented in a user interface
  • oslc:valueType (Resource, one-or-many) - may be any of the value types listed above in OSLC Defined Resources, in URI form:
    • Literal value-types
      • String - http://www.w3.org/2001/XMLSchema#string
      • MultiLangageString - http://open-service.net/xmlns/oslc-core-1.0#MultiLanguageString
      • *Integer - http://www.w3.org/2001/XMLSchema#integer
      • Decimal - http://www.w3.org/2001/XMLSchema#decimal
      • Float - http://www.w3.org/2001/XMLSchema#float
      • Double - http://www.w3.org/2001/XMLSchema#double
      • Boolean - http://www.w3.org/2001/XMLSchema#boolean
      • DateTime - http://www.w3.org/2001/XMLSchema#dateTime
      • URI - http://www.w3.org/2001/XMLSchema#anyURI
      • XMLLiteral - http://www.w3.org/1999/02/22-rdf-syntax-ns#XMLLiteral
    • Resource value-types
      • Resource - http://open-service.net/xmlns/oslc-core/resource-types#Resource
      • Local Resource - http://open-service.net/xmlns/oslc-core/resource-types#LocalResource
      • Inline Resource - http://open-service.net/xmlns/oslc-core/resource-types#InlineResource
      • Local Inline Resource - http://open-service.net/xmlns/oslc-core/resource-types#LocalInlineResource
  • oslc:shape (Resource, zero-or-one) - if the value-type is a resource type, then Property MAY provide a shape value to indicate the Resource Shape that applies to the resource.
  • oslc:occurs (String, exactly-one) - may be "exactly-one", "at-most-one", "zero-or-many" or "one-or-many"
  • oslc:allowedValue (Any value-type, zero-or-more) - value allowed for property
  • oslc:allowedValues (Resource of type oslc:AllowedValues, zero-or-more) - resource with allowed values for a property
  • oslc:defaultValue (String, zero-or-one) - default value for property
  • oslc:maxSize (Number, zero-or-one) - for String properties only, specifies maximum characters allowed. If not set, then there is no maximum or maximum is specified elsewhere.
  • oslc:readOnly (Boolean, zero-or-one) - true if property is read-only. If not set or false, then property is not read-only.
  • oslc:isMemberProperty (Boolean, zero-or-one) - true if the property is a membership property (e.g. like rdfs:member). If not set or false, then the property is not a membership property. The set of all membership properties of a resource SHOULD be used as the default value for the oslc.from query parameter in member list pattern queries.
  • Other properties MAY be specified by OSLC Services

---

Service Provider Catalog and Service Provider Resources

OSLC services are accessible via a Service Provider Resources that describes each service, which domain specifications the service implements as well as the creation, query and delegated UI capabilities of each service.

Additionally, a provider may offer a Service Provider Catalog that lists related Service Providers.

Conceptual Model

The conceptual model of Service Provider Catalog and Service Provider resources is simple. They are both resources with property values. The values allowed and required in each type of resource are defined below.

The diagram below illustrates the Service Provider Catalog and Service Provider concepts and relationships. As you can see there are two Resources defined: Service Provider Catalog and Service Provider. There are also a set of Local In-Line Resources that are used inside the Resources to define namespaces, OAuth configurations, contributors as well as services and their capabilities.

Next, we will formally define the Service Provider Catalog and Service Provider resources.

Resource: Service Provider Catalog

Service Provider Catalogs are used in the discovery of OSLC Service Providers, to simplify the configuration of tools that will integrate with providers of OSLC-defined services. These catalogs may contain contain other nested catalogs as well as service providers.

• Name: ServiceProviderCatalog
• Suggested Prefix: oslc
• Namespace URI: http://open-services.net/xmlns/oslc#
• Type URI: http://open-services.net/xmlns/oslc#ServiceProviderCatalog
• Properties:
  • dc:title (String, at-most-one) - title of the service provider catalog
  • dc:contributor (Local Inline Resource of type oslc:Contributor, at-most-one): describes the software product that provides the implementation.
  • oslc:domain (Resource, one-or-many) - namespace URI of the OSLC domain specification that may be implemented by referenced services
  • oslc:serviceProvider (Resource of type oslc:ServiceProvider, one-or-many): describes a service offered by the service provider.
  • oslc:serviceProviderCatalog (Resource of type oslc:ServiceProviderCatalog, one-or-many): describes a service offered by the service provider.
  • oslc:oauthAuthorization (Local Inline Resource of type oslc:OAuthAuthorization): defines the three OAuth URIs required for a client to act as an OAuth consumer.
  • A Service Provider Catalog MAY provide other property values.

Resource: Service Provider

A Service Provider describes a set of services offered by an OSLC implementation.

• Name: ServiceProvider
• Suggested Prefix: oslc
• Namespace URI: http://open-services.net/xmlns/oslc#
• Type URI: http://open-services.net/xmlns/oslc#ServiceProvider
• Properties:
  • dc:title (String, at-most-one) - title of the service provider
  • dc:contributor (Local Inline Resource of type oslc:Contributor, at-most-one): describes the software product that provides the implementation.
  • oslc:service (Local Inline Resource of type oslc:Service, one-or-many): describes a service offered by the service provider.
  • oslc:namespaceDefinition (Local Inline Resource of type oslc:NamespaceDefinition): defines a namespace prefix for use in JSON representations and in forming OSLC Query Syntax strings.
  • oslc:oauthAuthorization (Local Inline Resource of type oslc:OAuthAuthorization): defines the three OAuth URIs required for a client to act as an OAuth consumer.
  • A Service Provider MAY provide other property values.

Resource: Service

A Service describes the specific services offered by an implementation of an OSLC specification.

• Name: Service
• Suggested Prefix: oslc
• Namespace URI: http://open-services.net/xmlns/oslc#
• Type URI: http://open-services.net/xmlns/oslc#Service
• Properties:
  • oslc:domain (Resource, exactly-one) - namespace URI of the OSLC domain specification that is implemented by this service.
  • creationFactory (Local Inline Resource of type oslc:Factory, zero-or-many): enables clients to create new resources
  • queryCapability (Local Inline Resource of type oslc:QueryCapabiity, zero-or-many): enables clients query across a collection of resources
  • selectionDialog (Local Inline Resource of type oslc:Dialog, zero-or-many): enables clients to select a resource via UI
  • creationDialog (Local Inline Resource of type oslc:Dialog, zero-or-many): enables clients to create a resource via UI
  • A Service Resource MAY provide other property values.

Resource: Creation Factory

A Creation Factory describes a creation factory, capable of creating new resources via HTTP GET.

• Name: CreationFactory
• Suggested Prefix: oslc
• Namespace URI: http://open-services.net/xmlns/oslc#
• Type URI: http://open-services.net/xmlns/oslc#CreationFactory
• Properties:
  • dc:title (String, exactly-one) - title string that could be used for display
  • oslc:label (String, at-most-one) - very short label for use in menu items
  • oslc:creation (Resource, exactly-one) - to create a new resource via the factory, post it to this URI
  • oslc:shape (Resource, exactly-one) - a Creation Factory MUST provide a Resource Shape that describe shape of the resource against which queries are executed.
  • A Creation Factory MAY provide other property values.

Resource: Query Capability

A Query Capability describes a query capability, capable of querying resources via HTTP GET or POST.

• Name: QueryCapability
• Suggested Prefix: oslc
• Namespace URI: http://open-services.net/xmlns/oslc#
• Type URI: http://open-services.net/xmlns/oslc#QueryCapability
• Properties:
  • dc:title (String, exactly-one) - title string that could be used for display
  • oslc:label (String, at-most-one) - very short label for use in menu items
  • oslc:queryBase (Resource, exactly-one) - the base URI to use for queries. Queries may be invoked either by HTTP GET or HTTP POST. For HTTP GET, a query URI is formed by appending query parameters to the base URI. For HTTP POST, the query parameters are encoded as content with media type application/x-www-form-urlencoded and sent in the request body. The base URI MAY accept other query languages and media types in the request body, e.g. application/sparql-query for SPARQL queries.
  • oslc:shape (Resource, zero-or-one) - the Query Capability SHOULD provide a Resource Shape that describes the query base URI.
  • A Query Capability MAY provide other property values.

Resource: Dialog

A Dialog describes a delegated user interface (UI) which can be used to allow a user to interactively create a new resource or pick a resource.

• Name: Dialog
• Suggested Prefix: oslc
• Namespace URI: http://open-services.net/xmlns/oslc#
• Type URI: http://open-services.net/xmlns/oslc#Dialog
• Properties:
  • dc:title (String, exactly-one): title string that could be used for dialog title
  • oslc:label (String, at-most-one): very short label for use in menu items
  • oslc:dialog (Resource, exactly-one): the URI of the dialog
  • oslc:hintWidth (String, at-most-one): valid values for these attributes is defined by the CSS 2 width attribute (reference: CSS2)
  • oslc:hintHeight (String, at-most-one): valid values for these attributes is defined by the CSS 2 height attribute (reference: CSS2)
  • There MAY be other property values.

Resource: Contributor

A Contributor identifies and describes the software product that provides the OSLC implementation.

• Name: Contributor
• Suggested Prefix: oslc
• Namespace URI: http://open-services.net/xmlns/oslc#
• Type URI: http://open-services.net/xmlns/oslc#Contributor
• Properties:
  • dc:title (String, exactly-one): title string that could be used for display
  • oslc:label (String, at-most-one): very short label for use in menu items
  • dc:identifier (String, exactly-one): A URN that uniquely identifies the implementation
  • oslc:icon (URL, exactly-one): URL to an icon file that represents the provider. This icon should be a favicon format and 16x16 pixels in size
  • A Contributor Resource MAY provide other property values.

Resource: Namespace Definition

Service Providers MUST provide a Namespace Definition for each namespace supported by the service. Each Namespace Definition defines a namespace prefix that clients MAY use in forming OSLC Query Syntax strings and that JSON Representations MUST use in all property names.

• Name: NamespaceDefinition
• Suggested Prefix: oslc
• Namespace URI: http://open-services.net/xmlns/oslc#
• Type URI: http://open-services.net/xmlns/oslc#NamespaceDefinition
• Properties:
  • oslc:prefix (String, exactly-one): namespace prefix to be used for this namespace
  • oslc:namespaceURI (Resource, exactly-one): the URI of the namespace

Resource: OAuth Configuration

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.

• Name: OAuthConfiguration
• Suggested Prefix: oslc
• Namespace URI: http://open-services.net/xmlns/oslc#
• Type URI: http://open-services.net/xmlns/oslc#OAuthConfiguration
• Properties:
  • oslc:oauthAccessTokenURI (Resource, exactly-one): URI for obtaining OAuth request token
  • oslc:authorizationURI (Resource, exactly-one): URI for obtaining OAuth authorization
  • oslc:oauthAccessTokenURI (Resource, exactly-one): URI for obtaining OAuth access token

The next sections cover the Creation Factory and Query Capability in more detail.

---

Creation Factories

An OSLC Service can provide one or more creation factory to enable the creation of new resources. A creation factory provides a Creation URI used to create new resources via HTTP POST and may also provide Resource Shapes that describe the types of resources that may be created. To create a new OSLC Resource, an OSLC client POSTs a representation of that resource to a Creation Factory's Creation URI.

• An HTTP POST of content to a Creation URI SHOULD result in the creation of a new resource or an explanation of why creation did not occur via the appropriate HTTP status code.
• The response to a successful HTTP POST of content to a Creation URI SHOULD include a HTTP Location header that specifies the URI of the newly created resource.

Creating an OSLC Defined Resource

To create an OSLC Defined Resource, an OSLC Client first forms an representation of that resource including the desired and required property values and following the rules set out in the OSLC Representation section below. A client can learn what properties are allowed in a new OSLC Defined Resource via the OSLC specification that defines or, in some cases via a Resource Shape resource. Next the client uses HTTP POST to post that representation to a Creation URI.

• The response to a successful HTTP POST of a representation to a Creation Resource URI MAY include a representation of the newly created resource.
• The resource returned MAY contain changes to properties made by the server or new properties added by the server.

Query Capabilities

An OSLC Service may provide one or more Query Capabilities to enable query of resources. A Query Capability provides a base URI for forming Query Resource URIs and MAY provide Resource Shapes that describe the property values that may be expected in the resources that are queryable via the query capability. Thus, Query Capabilities provide a way to discover the resources managed by an OSLC Service.

In a Query Capability, the base URI, as defined by the oslc:queryBase property, is itself a resource managed by the service and it acts as the starting subject resource for the queries based on it. The RDF/XML representation of the query result begins with a node element whose rdf:about attribute value is equal to the base URI. Typically, the base URI is a container resource that may have a long list of members, e.g. the list of all defects in a bug tracking system. Since the list may contains hundreds of thousands of members, queries are used to filter the list for members that satisfy certain conditions, e.g. the bugs that have high priority and were created this week.

Conceptual Model

To perform a query an OSLC client first creates a URI by starting with a Query Capability's base URI as a base and adding a URI Query String to express the query criteria. The OSLC client then uses HTTP GET to request a Query Resource representation of the query results. The Query Resource representation will contain property values about the query and a collection of resources that match the query criteria.

HTTP GET Queries

To perform an HTTP GET query, an OSLC client starts with the base URI as defined by the oslc:queryBase property of a Query Capability, and appends to it query parameters in a syntax supported by the service. The resulting URI is the query URI. The OSLC client sends an HTTP GET request to the query URI, optionally specifying the preferred content media type for the query response in the HTTP Accept header. OSLC services MUST support query responses in RDF/XML format (media type application/rdf+xml) and MAY support other formats. OSLC services SHOULD support the Query Syntax defined in this specification, but MAY support other syntaxes.

HTTP POST Queries

Alternatively, the client MAY encode the query parameters in the HTTP request body as media type application/x-www-form-urlencoded, and send an HTTP POST request to the base URI. An OSLC service MAY support other query languages using other media types in the request body, e.g. SPARQL (media type application/sparql-query).

Resource: ResponseInfo

A ResponseInfo Resource describes information about the HTTP response body in which it appears. This specification defines its use for query result paging.

• Name: !ResponseInfo
• Namespace URI: http://open-services.net/xmlns/oslc#
• Suggested Prefix: oslc
• Type URI: http://open-services.net/xmlns/oslc#ResponseInfo
• Properties:
  • dc:title (String, zero-or-one): a ResponseInfo Resource SHOULD include a meaningful and non-empty title.
  • dc:description (String, zero-or-one): a ResponseInfo Resource MAY include a meaningful and non-empty description.
  • rdf:type (Resource, exactly-one): a ResponseInfo Resource MUST include one rdf:type property with value of http://open-services.net/xmlns/oslc#ResponseInfo and MAY include other instances of the rdf:type property with other values.
  • oslc:nextPage (String, zero-or-one): link to the resource representing the next page of logical response of which this response is a physical page (see Query Resource Paging below)
  • Other properties MAY be specified by OSLC Services

Query Resource Paging

Frequently, a query result may be so large that a server may not be able to return the entire resource in one HTTP response. In these cases OSLC Services can use a mechanism called paging. The entire query result is the logical response of the query. The server MAY return the logical response as sequence of physical responses, referred to as pages.

In RDF terms, the pages SHOULD partition the logical response into disjoint subsets of triples. The union of the triples in all the pages MUST contain all the triples in the logical response, i.e. every triple that is part of the logical response MUST appear in some page. However, in practice it may be very difficult for the server to eliminate all duplication of triples, i.e. some triples MAY appear in more than one page. This duplication of triples is harmless since the semantics of RDF is that triples form a set, not a bag (aka multi-set). The union of the triples MAY only include additional non-significant triples, such as those used to describe paging, beyond those that are part of the logical response.

When a query URI is requested (via HTTP GET or POST), an OSLC Service MAY return the logical response as a sequence of physical response pages. Each page has a link to the next page, if any, in the sequence. The logical response is the union of all the pages in the sequence (after omitting the paging information).

A page is a partial resource representation, i.e. it is a representation that includes only a subset of the resource's property values. When a page is returned it, and it is NOT the last page in the sequence, then it SHOULD include an OSLC ResponseInfo resource that contains a resource-valued property oslc:nextPage that links to a resource that represents the next page of property values.

In RDF/XML representations, the OSLC ResponseInfo resource, if present, MUST be included as follows:

• If the document root is rdf:RDF then the paging information MUST appear in a child node element of type oslc:ResponseInfo.
• Otherwise, the document root is a node element for some subject resource, and the paging information MUST appear as the value of an oslc:responseInfo property whose value is an object node element of type oslc:ResponseInfo. The oslc:responseInfo property MUST appear exactly once.

The OSLC ResponseInfo resource, if present, SHOULD appear as either the first child element of an rdf:RDF document root element, or the first property of a subject node document root element so that the client is aware that another page is available as soon as possible. However, in some cases the server may be processing the response as a stream and not be aware that an additional page is needed. Therefore the OSLC ResponseInfo, if present, MAY appear later in the response.

In order to simplify client-side processing of the pages, each logical page SHOULD contain the complete content of one or more child elements of the physical RDF/XML document. Each child element that appears in the physical RDF/XML document SHOULD appear completely within exactly one logical page.

Unstable Paging

Because HTTP is a stateless protocol and OSLC Services manage resources that can change frequently, OSLC clients SHOULD assume that resources can change as they page through them using the oslc:nextPage mechanism.

Stable Paging

Some OSLC Services might wish to guarantee stable paging, meaning that the chain of oslc:nextPage links in a resource represent a snapshot in time and wil not change as the client pages through them. OSLC specification that require stable paging SHOULD state this requirement and specify to which resources it applies.

Note that because stable paging implementations are based on server-side state, it is possible that such state will expire. Implementations can use the HTTP Code 410 (Expired) to indicate to clients that the next-page link they requested has expired.

Query Syntax

A query URI can be formed by adding a query string to the end of the Query Capability's base URI (or by sending the query string in the request body when using HTTP POST). The syntax used to express the query criteria in that string is specified by each OSLC domain specification.

• OSLC domain specifications MAY define their own syntax for expressing query criteria in a string.
• OSLC domain specifications MAY require the OSLC Core Query Syntax as specified below.

This section of the Core specification defines a standard set of OSLC query parameters that other OSLC domain specifications MAY use to query resources.

Graph Patterns

The OSLC standard query parameters define graph patterns that are matched against the resources managed by the service, which we view as comprising an RDF graph. The pattern matching process begins at some starting subject resource and matches a set of triples in the RDF graph. The starting subject resources used for pattern matching are determined by the the Query Capability. A Query Capability defines a starting subject resource, namely the base URI itself. The result of the query is the set of all triples matched by the pattern, beginning the matching processing with the starting subject resource defined by the Query Capability.

The full graph pattern defined by the query parameters is composed of two kinds of graph pattern, which we refer to as property tree patterns and member list patterns. These patterns MAY be used individually or MAY be combined in a single query, but one or the other MUST be present. The result of matching the full graph pattern is the union of the results of matching each kind of pattern.

Property Tree Patterns

A property tree pattern is defined by the presence of the oslc.properties query parameter. In RDF, the data model of a resource is viewed as consisting of a set of properties of the resource. The values of these properties are either literal values, such as numbers, strings, and dates, or links to other resources, which may have their own properties. Linked resources may link to other resources, and so on, to arbitrary depths. However, the scope of the query is limited to the boundaries of the service as defined by the appropriate domain specification. Properties of linked resources may be viewed as nested properties of the initial resource. The oslc.properties query parameter lets you match both the immediate and nested properties of a starting subject resource.

Member List Patterns

A member list pattern is defined by the presence of at least one of the following query parameters: oslc.from, oslc.where, oslc.searchTerms, oslc.orderBy, oslc.offset, oslc.limit, and oslc.select. In this pattern, the starting subject resource is viewed as a container of other resources. The members of the container are defined by one or more multi-valued membership properties of the starting subject resource. The membership properties are either given by the oslc.from query parameter, or default to the properties described as membership properties (via oslc:isMemberProperty) in the Resource Shape of the starting subject resource. The pattern matching process is defined by the following sequence of steps. Default processing is done in steps where the corresponding query parameter is not present:

1. oslc.from - create the member list defined by membership properties of the starting subject resource, and arrange it in some order
2. oslc.where - filter the member list, keeping only those member resources that satisfy the boolean test on the member resource properties
3. oslc.searchTerm - score each member resource using a full text search on it text-valued properties, and sort them in descending order of score
4. oslc.orderBy - sort the members using the sort keys, using the full text search score as the primary key
5. oslc.offset - discard the specified number of member resources from the start of the list
6. oslc.limit - discard any member resources beyond the specified number from the end of the list
7. oslc.select - match the immediate and nested properties of the member resources (like in oslc.properties)

Prefixed Names

In addition to the preceeding query parameters, we also define oslc.prefix which is used to define the prefixes for prefixed names that appear in the other query parameters. The oslc.prefix query parameter is not itself part of the graph pattern. Other specifications MAY use oslc.prefix to define prefixes for prefixed name used other query parameters.

Query Parameters

The query parameters defined here are intended to satsify simple query requirements, and be easy to both use and implement. More complex query requirements should be satisfied using a full query language, e.g. SQL or SPARQL.

This specification formally defines the syntax of the query parameters using Backus-Naur Form (BNF) and informally illustrates their semantics with simple examples. For a more complete definition of the semantics see OSLC Simple Query Semantics V1.

The query parameters MAY contain characters that MUST be URL encoded when transmitted in an HTTP request. The examples below show unencoded query parameters for clarity. See URL Encoding for a further discussion of this topic.

This specification defines the syntax of a set of related query parameters that MAY be used to perform queries. We have adopted a consistent naming convention for these query parameters to identify them as common across all OSLC specifications, namely all query parameter names are prefixed with the characters " oslc. " The following sections define these query parameters.

An OSLC domain specification MAY use some or all of these query parameters, and SHOULD use these rather than defining new query parameters that have the same or very similar meanings.

Each of these query parameters SHOULD appear at most once in a query. The behavior is undefined when a query parameter appears more than once.

In the following sections, syntax is formally defined using a common extended form of BNF. Informal definitions and comments are delimited by /* and */.

oslc.prefix

This query parameter does NOT define a graph pattern. It is used by other query parameters that contain prefixed names.

In the following examples, property names include a URI prefix, i.e. dc: or foaf:. An OSLC service SHOULD predefine URI prefixes for its properties. Here we assume that OSLC has predefined the Dublin Core ( dc:) 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 queries. The oslc.prefix query parameter 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 query parameter to define it:

http://example.com/bugs/4242?oslc.prefix=foaf=<http://xmlns.com/foaf/0.1/>&oslc.properties=foaf:lastName,...

Syntax

The syntax of the oslc.prefix query parameter 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 Lanaguage 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.properties

This query parameter defines a property tree pattern.

The oslc.properties query parameter lets you specify the set of properties to match in a property tree pattern. 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 dc:title, dc:description, and dc:creator, and that dc: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 dc:title and the foaf:givenName and foaf:familyName of the person refered to by its dc:creator. The following URL illustrates the use of the oslc.properties query parameter to include those properties:

http://example.com/bugs/4242?oslc.properties=dc:title,dc:creator{foaf:givenName,foaf:familyName} 

Syntax

The oslc.properties query parameter is defined by the oslc_properties term in the following BNF grammar:

oslc_properties ::= "oslc.properties=" properties
properties      ::= property ("," property)*
property        ::= identifier | nested_prop | wildcard
identifier      ::= PrefixedName 
PrefixedName    ::= /* see "SPARQL Query Lanaguage for RDF", http://www.w3.org/TR/rdf-sparql-query/#rPrefixedName */
nested_prop     ::= property "{" properties "}"
wildcard        ::= "*"

oslc.from

This query parameter defines part of a member list pattern. If a member list pattern is defined but this query parameter is not present then it defaults to the set of all membership properties defined in the Resource Shape of the starting subject resource, i.e. the member list is the set of all resources that are related to the starting subject resource by one or more of the membership properties.

The OSLC resource data model is defined in terms of the properties that a given type of resource may have. Some properties define attributes of resources and some define links to other related resources. Membership is an important kind of link property. Membership properties are in general multi-valued and relate a given subject resource to zero or more member resources. A resource may have more than one kind of membership property, in which case the members are all resources that are linked to the subject resource by some membership property.

In general, there may be a very large number of member resources associated with a given subject resource, and it is often useful to search this set for member resources that satify some conditions. The oslc.from query parameter lets you specify which membership properties to use for this search. It is like the FROM clause in a SQL statement. The set of member resources thus defined may be further refined using boolean conditions specified in the oslc.where query parameter.

The oslc.from query parameter is not restricted to membership properties. It MAY contain any property.

For example, suppose the following URL represents the set of all change requests managed by a service:

http://example.com/requests

Suppose that this service manages two kinds of change requests, namely bugs and features, and that these are related to the base URL via the membership properties cm:memberBug and cm:memberFeature. An HTTP GET request on the base URL would return all the bugs and features.

The following query would also return all the bugs and features since the base resource has only the two specified membership properties:

http://example.com/requests?oslc.from=cm.memberBug,cm:memberFeature 

However, the following query would return only the bugs:

http://example.com/requests?oslc.from=cm:memberBug

Syntax

The syntax of the oslc.from query parameter is defined by the oslc_from term in the following BNF grammar:

oslc_from   ::= "oslc.from=" identifiers
identifiers ::= identifier ("," identifier)* 

oslc.where

This query parameter defines part of a member list pattern. If a member list pattern is define but this query parameter is not present then it defaults to the boolean condition true, i.e. it matches all members of the member list.

As discussed in the section on oslc.from, a resource may have an associated set of related resources defined by one or more membership properties. Service consumers often need to search for subsets of these related resources that satisfy certain conditions. The oslc.where query parameter lets you specify the conditions that these related resources must satisfy. It is like the WHERE clause of a SQL statement.

For example, suppose that the following URL represents the set of all bug resources managed by a service, and that is has a single membership property, cm:memberBug:

http://example.com/bugs 

Suppose bug reports have a dc:identifier property that gives their bug number, e.g. "4242". The following URL filters this set and selects only those bugs that have a dc:identifier property whose value is "4242":

http://example.com/bugs?oslc.where=dc:identifier="4242" 

Note that in the preceding query, the oslc.from query parameter is absent so it defaults to all the membership properties, and in this case there is only one, namely cm:memberBug.

Conditions may use the usual binary comparison operators and be combined using the boolean conjunction operator, " and ". For example, suppose bugs have cm:severity and dc:created properties. The following example finds high severity bugs created after April 1, 2010:

http://example.com/bugs?oslc.where=cm:severity="high" and dc:created>"2010-04-01"

The following URL illustrates the use of nested properties. It finds the set of bugs created by John Smith:

http://example.com/bugs?oslc.where=dc:creator{foaf:givenName="John" and foaf:familyName="Smith"}

Syntax

The syntax of the oslc.where query parameter is defined by the oslc_where term in the following BNF grammar:

oslc_where    ::= "oscl.where=" compound_term
compound_term ::= simple_term (space? boolean_op space? simple_term)*
simple_term   ::= term | scoped_term
space         ::= " " /* a space character */
boolean_op    ::= "and"
term          ::= identifier_wc comparison_op value | identifier_wc space in_op space? in_val
scoped_term   ::= identifier_wc "{" compound_term "}"
identifier_wc ::= identifier | wildcard
comparison_op ::= "=" | "!=" | "<" | ">" | "<=" | ">="
in_op         ::= "in"
in_val        ::= "[" value ("," value)* "]"
value         ::= uri_ref_esc | literal_value
literal_value ::= boolean | decimal | string_esc (LANGTAG | ("^^" PrefixedName))?
boolean       ::= "true" | "false"
decimal       ::= /* see "XML Schema Part 2: Datatypes Second Edition", http://www.w3.org/TR/xmlschema-2/ */
string_esc    ::= /* a string enclosed in double quotes, with certain characters escaped. See below. */
LANGTAG       ::= /* see "SPARQL Query Lanaguage for RDF", http://www.w3.org/TR/rdf-sparql-query/#rLANGTAG */

boolean_op

The boolean_op term represents a boolean operation that lets you combine simple boolean expressions to form a compound boolean expression.

The only boolean operation allowed is " and " which represents conjunction. The boolean operator " or " for disjunction is not allowed in the interests of keeping the syntax simple. The effect of " or " in the simple case of testing a property for equality with one of several values can be achieved through the use of the " in " operator. For example, the following query finds bugs with severity " high " or " medium ":

 http://example.com/bugs?oslc.where=cm:severity in ["high","medium"]

space

The space term represents a single space character. A space character MAY be used to delimit the binary_op term in the compound_term term to improve readability.

comparison_op

The comparison_op term represents one of the following binary comparison operators:

=	test for equality
=	test for inequality
<	test less-than
>	test greater-than
<=	test less-than or equal
>=	test greater-than or equal

in_op

The in_op term represents the operator " in " which is a test for equality to any of the values in a list. The list is a comma-separated sequence of values, enclosed in square brackets, whose syntax is defined by the term in_val.

value

The value term represents either a URI reference ( uri_ref_esc) or a literal value ( literal_value).

literal_value

The literal_value term represents either a plain literal or a typed literal.

A plain literal is a quoted string ( string_esc), optionally followed by a language tag ( LANGTAG). For example, "Bonjour"@fr is a plain literal with a language tag for French. If the range of a property is National Language strings and no language tag is provided in a literal value, then the service SHOULD infer the language tag from the HTTP request or provide a default value.

A typed literal is formed by suffixing a quoted string ( string_esc) with "^^" followed by the prefixed name ( PrefixedName) of a datatype URI. If the range of a property includes literal values from more than one datatype, then a typed literal MUST be used in order to avoid ambiguity. Otherwise a plain literal MAY be used and the service SHOULD infer the datatype.

The terms boolean and decimal are short forms for typed literals. For example, true is a short form for "true"^^xsd:boolean, 42 is a short form for "42"^^xsd:integer and 3.14159 is a short form for "3.14159"^^xsd:decimal.

decimal

The decimal term represents a decimal number as defined in XML Schema Part 2: Datatypes Second Edition. As mentioned above, this term is a short form for typed literals whose datatype URIs are either xsd:integer or xsd:decimal. An integer literal value is a special case of a decimal literal value, namely one in which the decimal point is omitted from the lexical representation. For example, 42 is a valid decimal number which happens also to be a valid integer and so it is a short form for the typed literal "42"^^xsd:integer.

string_esc

The string_esc term represents an arbritrary sequence of characters. The sequence of characters is enclosed in double quote (") characters. Therefore, the double quote character itself MUST be escaped. All occurances of the double quote character in the string MUST be replaced by the sequence \" and all occurances of the backslash character (\) MUST be replaced by the sequence \\. This escaping MUST be undone to give the actual value of the string.

oslc.searchTerms

This query parameter defines part of a member list pattern. If a member list pattern is defined but this query parameter is not present then the matching process assigns an effective score of 0 to each member of the list and does NOT change the order of the member list

Resource properties often contain text so it is useful to search for resources that contain specified terms. The oslc.searchTerms query parameter lets you perform a full text search on a set of resources. In a full text search, each resource is matched against the list of search terms and assigned a numeric score. A high score indicates a good match. The matching resources are returned in the response, sorted by the score in descending order. Each resource that is returned in the response is annoted with a special property, oslc:score, that gives its match score.

An OSLC domain specification that supports full text search SHOULD specify which resource properties are indexed so that search results are consistent across implementations.

When oslc.searchTerms is used in the request, each matching resource (hit) in the response MAY contain an oslc:score property. Note that oslc:score is not purely a property of the resource since it also depends on the search terms. It is therefore a pseudo-property whose validity is limited to the HTTP response.

The oslc:score property MUST be a non-negative number and SHOULD be in the range from 0-100. Results MUST be ordered with the entry with the largest oslc:score occuring first.

The oslc.orderBy query parameter MAY be used with oslc.searchTerms. When oslc.orderBy is used with oslc.searchTerms the result MUST be first sorted in descending order by the oslc:score pseudo-property, and then by the other sort keys specified in oslc.orderBy. This behavior is like prepending the list of sort keys specified in oslc.orderBy with the key -oslc:score. However, the pseudo-property oslc:score MUST NOT appear explicitly in oslc.orderBy.

The oslc.limit and oslc.offset query parameters MAY be used in combination with oslc.searchTerms. For example, the following query returns the top 10 bugs that deal with database performance:

http://example.com/bugs?oslc.limit=10&oslc.searchTerms="database","performance" 

The oslc.where query parameter MAY be used with oslc.searchTerms. When oslc.where is used with oslc.searchTerms then the set of resources searched for matches MUST be restricted to only those resources that satisfy the conditions in oslc.where. For example, the following query returns the top 10 high severity bugs that deal with database performance:

http://example.com/bugs?oslc.where=cm:severity="high"&oslc.limit=10&oslc.searchTerms="database","performance" 

Syntax

The syntax of the oslc.searchTerms query parameter is defined by the oslc_searchTerms terms in the following BNF grammar:

oslc_searchTerms ::= "oslc.searchTerms=" search_terms
search_terms     ::= string_esc (, string_esc)* 

oslc.orderBy

This query parameter defines part of a member list pattern. If a member list pattern is define but this query parameter is not present then there are no sort keys and the matching process does NOT change the order of the member list.

The oslc.orderBy query parameter lets you sort the result set. It is like the ORDER BY clause of a SQL statement.

You can specify a list of one or more immediate or nested properties of the resources in the member list, and a sort direction for each where " + " means ascending order and " -" means descending order. The following example sorts the high severity bugs by the family and given names of the creator, with most recently created first:

http://example.com/bugs?oslc.orderBy=dc:creator{+foaf:familyName,+foaf:givenName},-dc:created
    &oslc.where=cm:severity="high"

The properties in the oslc.orderBy list are sort keys. The member list is sorted by the sort keys, in the indicated direction. The sorting order of the property values MUST be the same as that used for evaluating the binary comparison operators in the oslc.where query parameter.

Each sort key SHOULD be the name of a single-valued property of the each resource in the result set. The sorting behavior is undefined if the sort key properties are not single-valued.

Syntax

The syntax of the oslc.orderBy query parameter is defined by the oslc_orderBy term in the following BNF grammar:

oslc_orderBy        ::= "oslc.orderBy=" sort_terms
sort_terms          ::= sort_term ("," sort_term)* 
sort_term           ::= scoped_sort_terms | ("+" | "-") identifier
scoped_sort_terms   ::= identifier "{" sort_terms "}" 

oslc.offset

This query parameter defined part of a member list query. If a member list query is defined but this query parameter is not present then it has an effective value of 0 and the matching process does NOT discard any resources from the start of the member list.

The oslc.offset query parameter lets you specify where in result set to begin the contents of the HTTP response. An oslc.offset of 0 omits no members of the result set. When you use oslc.offset used in conjunction with oslc.limit, you can break up the member list into chunks that will be returned in the HTTP response.

For example, the following query returns the next 100 most recent high severity bugs:

http://example.com/bugs?oslc.where=cm:severity="high"&oslc.orderBy=-dc:created&oslc.limit=100&oslc.offset=100

oslc.limit

This query parameter defines part of a member list pattern. If a member list pattern is defined and this query is not present then it has an effective value of infinity and the matching process does NOT discard any resources from the end of the member list.

In practice, a result set may contain a large number of resources, so it is useful to limit the number of resources that are returned in the HTTP response. The oslc.limit query parameter lets you limit the number of resources included in the response.

For example, the following query returns the 100 most recently created high severity bugs:

http://example.com/bugs?oslc.where=cm:severity="high"&oslc.orderBy=-dc:created&oslc.limit=100

Syntax

The syntax of the oslc.limit query parameter is defined by the oslc_limit term in the following BNF grammar:

oslc_limit      ::= "oslc.limit=" positiveInteger
positiveInteger ::=  /* see "XML Schema Part 2: Datatypes Second Edition", http://www.w3.org/TR/xmlschema-2/ */

positiveInteger

The positiveInteger term represents a positive integer value (reference: XSD Datatypes).

Syntax

The syntax of the oslc.offset query parameter is defined by the oslc_offset term in the following BNF grammar:

oslc_offset        ::= "oslc.offset=" nonNegativeInteger
nonNegativeInteger ::=  /* see "XML Schema Part 2: Datatypes Second Edition", http://www.w3.org/TR/xmlschema-2/ */

nonNegativeInteger

The nonNegativeInteger term represents a non-negative integer value (reference: XSD Datatypes).

oslc.select

This query parameter defines part of a member list pattern. If a member list pattern is defined but this query parameter is not present then the matching process does NOT match any properties of the resources in the member list.

The oslc.select query parameter lets you specify which immediate and nested properties of the resources in the member list to match. It is like the SELECT clause of a SQL statement.

The syntax of the oslc.select query parameter is the same as that of the oslc.properties query parameter. However, the property names that appear in the oslc.select query parameter are those that belong to the resources in the member list as opposed to those that belong to the starting subject resource.

For example, the following URL finds the high severity bugs and includes their creation date and the family name of the creator in the HTTP response:

 http://example.com/bugs?oslc.select=dc:created,dc:creator{foaf:familyName}&oslc.where=cm:severity="high"

Syntax

The oslc.select query parameter is defined by the term oslc_select in the following BNF grammar:

oslc_select ::= "oslc.select=" properties

The oslc.select query parameter uses the same syntax as the oslc.properties query parameter. The difference between them is in the meaning of the identifers. In oslc.properties, the identifiers are the names of properties of the starting subject resource. In oslc.select, the starting subject resource has an associated list of member resources, and the identifers are the names of properties of the resources that are contained in the member list

For example, suppose that a bug resource has the membership property cm:comment that relates it to comment resources, and that the bug and each comment have dc:modified properties that give their last modification dates. The following query specifes that the response should include the modification date of bug 4242 and the modification date of each of its comments:

 http://example.com/bugs/4242?oslc.properties=dc:modified&oslc.from=cm:comment&oslc.select=dc:modified

wildcard

As in the case of oslc.properties, the wildcard is equivalent to the list of all properties of the member resources. The query parameter oslc.select=* specifies that pattern MUST match all the properties of the resources in the member list.

URL Encoding

The query parameter syntax defined in this specification permits the use of characters that MUST be properly encoded when transmitted in HTTP requests. For example:

Not encoded:

?oslc.where=dc:title="test case 1" and dc:modified>="2008-12-02T18:42:30"

Encoded:

?oslc.where=dc%3Atitle%3D%22test%20case%201%22%20and%20dc%3Amodified%3E%3D%222008-12-02T18%3A42%3A30%22

---

Delegated User Interface Dialogs

In theory, if each OSLC service offered a comprehensive HTTP interface, one that enabled clients to access and operate on every type of resource managed by the service, then OSLC could support every imaginable ALM and PLM integration. But in reality, OSLC specifications target specific integration scenarios and will never offer that type of comprehensive interface. That is why, in some cases, allowing one product to delegate to a user interface defined in another product is a more effective way to achieve integration than providing an HTTP interface that can only be accessed programmatically. There are two cases where this is especially true:

• Resource creation. When a user is using a web application needs to create a new resource in an OSLC Service Provider. In this case the web application asks the service provider to provide a UI for resource creation and the provider notifies the application when the creation has been completed or canceled by the user.
• Resource selection. When a user is using web application and needs to pick a resource managed by a OSLC Service Provider. In this case the web application asks the service provider to provide a UI for resource selection and the provider notifies the application when a resource or resources has been selected or if the selection was canceled.

To support these two cases, below we define OSLC Delegated User Interface (UI) Dialogs. Delegated UI Dialogs are a technique where one provider can embed a creation or selection UI into another using a combination of an HTML <iframe> and JavaScript code. The diagram below illustrates how delegated UI dialogs work in a scenario where Provider A wants to allow a user to select or create a resource managed by Provider B.

Next, the details of the Delegated UI Dialog protocol.

Terminology

The following terms are used in discussions of Delegated UI Dialogs:

• UI Consumer - a web application that is embedding a Delegated UI Dialog from an OSLC Service Provider. This consumer could be a web page, with the Delegated UI Dialog loaded into an iframe or a native application, e.g. an IDE like Eclipse, that is embedding a web browser component.

• UI Provider - an OSLC Service provider that offers one or more Delegated UI Dialogs. These dialogs will be specified in the provider's Service Provider resource.

The next sections explain how Delegated UI Dialogs work.

Post Message and Window Name protocols

To support the widest range of web browsers, we define two different protocols for communicating the information about the user's action from the UI Provider and back to the UI Consumer. These are the Post Message and Window Name protocols described below.

In both the Post Message and Window Name protocols, the way that a UI Consumer includes a Delegated UI Dialog in an HTML page is to create an iframe and specify the src as the URI of the Delegated UI Dialog to be included plus. The UI Consumer indicates the protocol to be used by appending one of the two fragment identifiers below to the URI:

• #oslc-core-postMessage-1.0 - Indicates that the Post Message protocol is to be used
• #oslc-core-windowName-1.0 - Indicates that the Window Name protocol is to be used

The JavaScript code example below shows now a UI Provider can determine which protocol is in use:

    if (window.location.hash == '#oslc-core-windowName-1.0') {       
        // Window Name protocol in use
    } else if (window.location.hash == '#oslc-core-postMessage-1.0') {
        // Post Message protocol in use
    } 

iframe Creation Considerations

Regardless of the protocol in effect, it is recommended that UI Consumers follow the below iframe creation guidelines to provide a more seamless user experience:

• Embed the iframe within a div element, with height and width set to the values specified in the Service Resource that declares the Delegated UI Dialog. The iframe itself should be set to width and height of '100%.'
• Set the iframe border size to '0'
• Set the iframe scrolling to 'auto'

Next, the details for each of the two protocols.

Post Message Protocol

The Post Message protocol relies on the HTML5 function window.postMessage() (reference: HTML5), available in the latest or pending releases of most browsers. UI Consumers must anticipate other, unrelated uses of postMessage(), and should ignore messages not conforming to this protocol.

Typically, the embedded page will be loaded in a window inside another window, such as a iframe inside some surrounding webpage. In such cases, postMessage() must be called on that parent window. But in a native application, an outer page is not needed and the embedded page may be shown directly in the browser's "root" window. When the embedded page has no parent window, it must call postMessage() on its own window.

Here are the responsibilities of the UI Consumer and UI Provider in Post Message protocol.

The UI Consumer's responsibilities

1. Include the Delegated UI Dialog via iframe (i.e setting iframe src to the URI of the Delegated UI Dialog) or via an embedded browser. Append the fragment identifier #oslc-postMessage-1.0 to the URL to indicate that Post Message is the desired protocol.
2. Add a 'message' listener to the outer window to receive messages from the Delegated UI Dialog.
3. Listen for window 'message' events, ignoring events from other sources or not prefixed with "oslc-response:"
4. When message from Delegated UI Dialog indicates user completed action, free resources and handle action.

The UI Provider's responsibilities

1. Provide Delegated UI Dialog, an HTML page that provides a user interface for resource creation or selection.
2. Allow user to perform resource creation or selection.
3. Once user has created, selected or canceled, send notification using postMessage() to the page's parent window, passed in event.data string, must be prefixed with "oslc-response:" See below for the two possible response formats, one for resource selection and one for creation.
4. If the page is not parented, then the message is posted to the page's own window. The page must ignore this message to itself.

The below JavaScript code example shows how a UI Provider page would send a response using postMessage() and taking into account the fact that some pages are not parented.

   function respondWithPostMessage(/*string*/ response) {
      (window.parent | window).postMessage("oslc-response:" + response, "*");
   }

Now, the Window Name protocol.

Window Name Protocol

The Window Name protocol uses the HTML DOM window.name property to communicate the response (reference: Window Object) from the UI Provider to the UI Consumer. This special property of window maintains its value even as the window navigates to a different origin, but the ifame's window.name can only be read when the accessing window shares the same origin. For this to happen, when the embedded page is finished it must set the window.name and also change the window.location to a page with the same origin as the outer frame. This not only allows the UI Consumer to access the result, but also fires an event telling the UI Consumer when to do so. This return location is passed to the embedded page using the window.name property.

Here are the responsibilities of the UI Consumer and UI Provider in Window Name protocol.

The UI Consumer's responsibilities

1. Include the Delegated UI Dialog via iframe (i.e setting iframe src to the URI of the Delegated UI Dialog) or via an embedded browser. Append the fragment identifier #oslc-core-windowName-1.0 to the URL to indicate that Window Name is the desired protocol.
2. On the iframe, set the frame's window.name to indicate the Return URL.
3. On the iframe, Listen for 'onload' events
4. When an 'onload' event occues an the frame's location is equal to the Return URL then read the response from the window.name and finish.

The following Javascript code illustrates the protocol. The code for the destroyFrame(), handleMessage() and displayFrame() methods are not provided in this example, but should be obvious to a JavaScript developer. The UI Consumer must provide these methods.

function windowNameProtocol(/*string*/ dialogURI, onDataReceived) {

   // Step #1: create iframe for Delegated UI Dialog, 
   // adding fragment to indicate the protocol
   var frame = doc.createElement('iframe');
   frame.src= url + #oslc-core-postMessage-1.0';

   // Step #2: set the iframe's window.name to indicate the Return URL
   frame.name = "http://localhost/blank.html";

   // Step #3: listen for onload events on the iframe
   frame.onload = function() {

      try { // May throw an exception if the frame's location is still a different origin

         // Step #4: when frame's location is equal to the Return URL 
         // then read response and return.
         if (frame.contentWindow.location == returnLocation) {
            var message = frame.contentWindow.name;
            destroyFrame(frame);
            handleMessage(message);
         }
      } catch(e) {
         // ignore: access exception when trying to access window name
      };
   };
   displayFrame(frame);
}

The UI Provider's responsibilities

As soon as the embedded page has loaded, perform the following:

1. Provide Delegated UI Dialog, an HTML page that provides a user interface for resource creation or selection.
2. Read the Return URL from the window.name variable
3. Allow user to perform resource creation or selection.
4. Once user has created, selected or canceled, communicate the user's response by setting the window.name variable to the response. See below for the two possible response formats, one for resource selection and one for creation.
5. Indicate that user has responded by setting the window.location to the Return URL specified by the UI Consumer.

The JavaScript example below shows how a UI Provider might notify its UI Consumer after a user has responded.

function respondWithWindowName(/*string*/ response) {
   // Step #2: read the return URL
   var returnURL = window.name;

   // Step #4: send the response via the window.name variable
   window.name = response;

   // Step #5: indicate that user has responded
   window.location = returnURL;
}

Resource Selection

Resource Selection can be used when a UI Consumer wants to allow a user to pick a resource that is managed by an OSLC Service. Using either the Post Message or Window Name protocols defined above, the UI Consumer uses an iframe to embed a selection dialog that is provided by the service, then awaits notification that the user has selected a resource.

To enable Resource Selection, an OSLC Service MUST provide in its Service Resource a value for the oslc:selectionDialog property. The property value will include a oslc:dialogURI property that indicates the URI of the selection dialog.

Regardless of how the response from the UI Provider is conveyed to the UI Consumer, the response SHOULD be formatted as follows:

• Name: results
• Suggested Prefix: oslc
• Type URI: http://open-services.net/xmlns/oslc#results
• Properties:
  • rdf:resource (URI, exactly-one) URI of the resource selected or created
  • oslc:label (String, exactly-one) Short label describing the resource selected

An empty array indicates that the resource selector has been canceled

An example Resource Selection response:

{
    "oslc:results" : [{
            "oslc:label": "Bug 123: Server crash",
            "rdf:resource": "http://example.com/bug123" 
        }, {
            "oslc:label": "Bug 456: Client hangs on startup",
            "rdf:resource": "http://example.com/bug456" 
        }
    ]
} 

Resource Creation

Resource Creation can be used when a UI Consumer wants to allow a user to create a new resource that is managed by an OSLC Service. Using either the Post Message or Window Name protocols defined above, the UI Consumer uses an iframe to embed a creation dialog that is provided by the service, then awaits notification that the user has created a resource.

To enable Resource Creation, an OSLC Service MUST provide in its Service Resource a value for the oslc:creationDialog property. The property value will include a oslc:dialogURI property that indicates the URI of the creation dialog.

Regardless of how the response from the UI Provider is conveyed to the UI Consumer, the response SHOULD be formatted as defined by oslc:results

Example:

{
    "oslc:results" : [ {
            "oslc:label": "Bug 123: Server crash",
            "rdf:resource": "http://example.com/bug123" 
        }, {
            "oslc:label": "Bug 456: Client hangs on startup",
            "rdf:resource": "http://example.com/bug456" 
        }
    ]
} 

Prefilling Creation Dialogs

Service providers MAY support receiving a POST request whose content body is a change request resource definition to the {Creation Dialog URI} to retrieve a URI that represents the embedded page to be used. Service providers MUST respond with a response status of 201 (Created) with the response header Location whose value is the URI to request the newly created form. Service providers MAY NOT maintain the created form in a persistent storage. Clients SHOULD expect that after some elapsed time, a GET on these transient response URIs MAY result with response status codes of 404 (Not found) or a 3xx (Redirect).

That brings us to the end of the Delegated UI section. Next up: Authentication.

---

Authentication

OSLC Services use standard web protocols for authentication. OSLC Services can use HTTP Basic Authentication, OAuth or both.

HTTP Basic Authentication

OSLC Services MAY protect resources with HTTP Basic Authentication. OSLC Services that use HTTP Basic Authentication SHOULD do so only via SSL.

OAuth Authentication

OSLC Services MAY protected resources with OAuth Authentication.

Form Based Authentication

OSLC Services MAY use other authentication mechanisms, including those common described as Form Based Authentication. OSLC Services that choose to use other authentication mechanisms are responsible for specifying how those mechanisms work.

---

Error Responses

OSLC Services the standard mechanisms of HTTP to report status and error codes to clients. When an error occurs and useful information can be provided to clients OSLC Services SHOULD return error information in the body of the response.

OSLC Services SHOULD use the Error resource defined below as the basis for forming error responses. OSLC Services SHOULD return an Error resource using the same representation requested by the client via the HTTP Accept header.

Conceptual Model

The following OSLC Defined Resource can be used as the basis for forming an error response.

Resource: Error

• Name: Error
• Suggested Prefix: oslc
• Namespace URI: http://open-services.net/xmlns/oslc#
• Type URI: http://open-services.net/xmlns/oslc#Error
• Properties
  • oslc:statusCode (Decimal, exactly-one): the HTTP status code reported with the error.
  • oslc:message (String, exactly-one): an informative message describing the error that occurred.
  • oslc:exendedMessage (Resource or Local Inline Resource of type oslc:ExtendedMessage)
  • Other properties MAY be specified by OSLC Service.

Resource: Extended Error

• Name: ExendedError
• Suggested Prefix: oslc
• Namespace URI: http://open-services.net/xmlns/oslc#
• Type URI: http://open-services.net/xmlns/oslc#ExtendedError
• Properties
  • oslc:url (Resource, zero-or-one) a resource giving more information on the error SHOULD be of an HTML content-type.
  • oslc:rel (Resource, zero-or-one) if present and set to 'alternate' then indicates that work-around is provided, behavior for other values is undefined.
  • oslc:hintWidth (Decimal, zero-or-one): hint indicates pixel width of extended error window.
  • oslc:hintHeight (Decimal, zero-or-one) hint indicates pixel height of extended error window.
  • Other properties MAY be specified by OSLC Service.

---

Specification Versioning

One of the goals of the OSLC initiative is to mitigate or eliminate the need for lock-step version upgrades, where clients or services target one version of a specification and break when new versions are introduced -- requiring all services to be upgraded simultaneously.

In this section we specify a version header that will enable old "Version 1" OSLC clients to continue to work and share the same resource URIs as used by clients that specifically target the Core. And we establish rules that will enable clients to continue to work as new versions of specifications are introduced.

Supporting pre-Core clients

We anticipate that the OSLC Core and domain specifications will each be versioned independently and each version will be assigned a version number, but we would like to avoid exposing version numbers in OSLC implementations. There is one use case that requires version information to be exposed. We must ensure that old OSLC "Version 1" clients continue to work.

To enable OSLC Service specifications to evolve without breaking existing clients, we introduce an HTTP Header, OSLC-Core-Version set to the Core specification version number "2.0". We expect clients that target the Core to send this HTTP header.

• If the OSLC-Core-Version header is present and set to a version that the service can support, then the service MUST return a representation that is complies with the specified version.
• If the OSLC-Core-Version header is present and indicates a specification version that the service cannot support, the service SHOULD respond with what it determines is the most compatible version that it can return.
• If the OSLC-Core-Version header is not present then the OSLC Service SHOULD respond by returning a resource that conforms to the earliest or most compatible (as determined by the implementation) specification version's representation. Services that never offered an OSLC Version 1 interface can ignore this restriction.
• When returning an OSLC Defined Resource, OSLC Services MUST return the OSLC-Core-Version header set to the Core specification with which the representation complies.

Rules for new versions of OSLC specifications

When specifying a new version of an OSLC specification the rule is this:

* A new version of an OSLC specification is not allowed to introduce changes that will break old clients.

Here are some guidelines for OSLC workgroups defining new specifications or upgrades to existing ones:

• If you believe that you need a property but cannot agree on the value-type, then this is a strong indication that you should not attempt to standardize

on the property. Once decide on a value-type you are stuck with it forever. Wait until you have the scenarios or implementation experience needed to agree on type.

• When introducing a new capability in a new version of a specification, e.g. a creation factory, query capability or delegated UI dialog; one that works differently than those specified in the Core spec or older versions of your own specification, you should create a new resource type to represent the service. This will enable old clients to continue to work against old services. and new clients to work with your new capabilities.
• When defining resources, do not remove, change the meaning or the value-type of any properties that you defined in earlier versions of the specification. You can add new properties but not change those that already exist.
• It is possible to relax restrictions on clients, because relaxing restrictions should not break clients. But it us not possible to relax restrictions on services, because clients expect to find the required fields and if they are missing, clients will break.

Migrating to the Core Specification

Most of the first OSLC specifications were developed before this Core specification existed and do not implement versioning as described above and so must use some other mechanism to migrate to the OSLC Core v1.0 specification.

OSLC implementations that wish to continue to support old pre-Core OSLC or OSLC v1.0 specifications can do so by keeping the old implementation in place and adding the new OSLC Core v1 implementation with different service provider, query capability and creation factory URIs.

---

OSLC Defined Resource Representations

This section specifies how representations of OSLC Defined Resources are created. The rules in this section apply to all of the resources defined in this specification and can be used in other OSLC specifications.

To encourage interoperability across OSLC domains and implementations, OSLC requires that services provide an RDF/XML representation. Services can also choose to provide additional representations: HTML, Turtle, JSON or Atom.

Use standard content-types

Note that existing standard content-types are used, e.g. application/rdf+xml in this document and no new content-types are introduced. Those writing OSLC specifications are strongly encouraged to follow this pattern -- use standard and existing content-types and avoid inventing new content-types.

Order of property values insignificant

This specification defines how OSLC property values are to be represented in a variety of formats. Except in the case of a sorted Query Response, the ordering of property values is insignificant. OSLC clients and service providers MUST not place any significance on the ordering of property values in representations.

Use Absolute URIs

OSLC representations MUST use absolute URIs in all cases except XML representations, where the xml:base attribute may be used to allow relative URIs to be resolved to absolute form (reference: XML Base).

Before a resource representation that uses xml:base is posted to an OSLC Service for creation, it may include relative URIs that cannot be resolved until the OSLC Service has received, created and assigned a URI to the new resource.

RDF/XML Representations

An OSLC Service MUST provide and accept RDF/XML representations of all OSLC Defined Resources and according to the rules below (reference: RDF/XML Syntax).

When a client requests an OSLC Defined Resource and specifies via HTTP Accept header an application/xml, application/rdf+xml or does not specify a content-type then an OSLC Service SHOULD respond by returning an RDF/XML representation. OSLC Services SHOULD return RDF/XML representations using the content-type application/rdf+xml.

Rules for representing resources in RDF/XML

We define these rules and place constraints on how the RDF/XML is formed for the purposes of interoperability with XML parsing tools and readability. The rules are expressed as a set of instructions. Instead of using an <rdf:RDF> root and <rdf:Statements> elements, OSLC Defined Resources are represented as XML elements with QNames formed using the Resource's Prefixed Name.

Use these rules to form an RDF/XML representation of an OSLC Defined Resource.

• 1.0 Open the XML root element using the Resource's QName
  • 1.1 Add to the XML element the rdf:about attribute set to the URI of the resource
• 2.0 Represent the properties of the resource (using the property rules below)
• 3.0 Close the XML root element

These are the property rules referred to above. OSLC property values are represented as XML elements with QNames formed using the Resource's QName namespace prefix and name.

• 1.0 For each property value of the resource
  • 1.1 Open XML element using QName of property
  • 1.2 If property value is a Literal value-type
    • 1.2.1 Inside the XML element add the value as a string with proper escaping
    • 1.2.1 If property value is one value of a National Language String, then use the xml:lang attribute to indicate the language
  • 1.3 If property value is a Resource value-type
    • 1.3.1 Add to the XML element the rdf:resource attribute set to URI
  • 1.4 If property value is a Local Resource value type
    • 1.4.1 Add to the XML element the rdf:nodeID attribute set to local ID of the resource referred to
  • 1.5 If property value is an In-Line Resource value-type:
    • 1.5.1 Open XML element using QName of resource
    • 1.5.2 Add to the XML element the rdf:about attribute set to URI of resource
    • 1.5.3 Inside the XML element represent property values of the linked resource (using these same rules)
    • 1.5.4 Close the XML element
  • 1.6 Else if property value is a Local Inline Resource value-type:
    • 1.6.1 Open XML element using QName of the resource
    • 1.6.1 Add to the XML element to rdf:ID set to the local ID you wish to assign to the resource. Only needed when Local Resource needs to refer to this resource.
    • 1.6.3 Inside the XML element represent property values of the resource (using these same rules)
    • 1.6.4 Close the XML element
  • 1.7 Close XML element

JSON Representations

An OSLC Service MAY provide and accept JSON representations of some OSLC Defined Resources. OSLC Services that provide JSON presentations MUST respond to HTTP requests that request application/json with a JSON representation as specified below. OSLC Services that provide JSON presentations of OSLC Defined Resources MUST return them with content-type application/json.

Note that JSON representations MUST use the namespace prefix names that are defined by the Service Provider that provides them.

Rules for representing OSLC Defined Resources in JSON format

Use these rules to form an JSON representation of an OSLC Defined Resource.

• 1.0 Create a JSON object with the following fields:
  • qname set to the QName of the resource
  • uri set to the URI of the resource
• 2.0 For each namespace used in the JSON representation:
  • 2.1 Add a field =oslc:namespaceDefinition set to a JSON Object with these fields:
    • prefix set to the namespace prefix
    • namespaceURI set to the namespace’s URI
• 3.0 Add to the JSON object fields to represent the property values of the resource using the property rules below)

These are the property rules referred to above. For each property:

• 1.0 For each property of a resource
  • 1.1 Add field to resource's JSON object with name set to QName of property
    • 1.1.1 If there is only a single value of this property, then make field's value literal or JSON Object
    • 1.1.2 If there are multiple values of this property, then make field's value JSON Array
  • 12 If value-type is National Language String
    • 1.2.1 Set field's value to object with one field per language provided
    • 1.2.2 Set field's name to locale code, name must be valid xml:lang value
    • 1.2.3 Set field's value to string value for locale specified by field name
  • 1.3 Else if value-type is Literal
    • 1.3.1 Set field's value to string representation of property value
  • 1.4 Else if value-type is Resource
    • 1.4.1 Set field's value to JSON object with field:
      • resource set to URI of resource
  • 1.5 Else if value-type is Local Resource with fields:
    • 1.5.1 Set field's value to JSON object with field:
      • rdf:nodeId set to local ID of resource
  • 1.6 Else if value-type is Inline Resource
    • 1.6.1 Set field's value to JSON object with fields:
      • about set to URI of resource whose values are being inlined
      • Represent properties of inlined resource (using these same rules)
  • 1.7 Else if value-type is Local Inline Resource
    • 1.7.1 Set field's value to JSON object with fields:
      • rdf:id set to local ID you wish to assign to this resource. Only needed when Local Resource needs to refer to this resource.
      • Represent properties of inlined resource (using these same rules)

Turtle Representations

An OSLC Service MAY provide and understand Turtle representations of some OSLC Defined Resources and according to the rules below.

• Returned when these content types requested: application/x-turtle
• Returned as content-type: application/x-turtle

Rules for forming a Turtle representation

TBD

Atom Representations

An OSLC Service MAY provide and accept Atom Syndication Format representations of OSLC Defined Resources and according to the rules below (reference: Atom Format).

Rules for forming an Atom format OSLC Defined Resource representation

Note that there are special rules below for creating an OSLC Query Resource representation in Atom format.

When a client requests an Atom representation of an OSLC Defined Resource and specifies via HTTP Accept header content-type application/atom+xml or application/atom+xml;type=entry then an OSLC Service SHOULD respond with an Atom representation.

To represent an OSLC Defined Resource in Atom format we use an Atom <entry> element as document root, we map some OSLC properties to Atom elements and inside the Atom <content> element, we place an RDF/XML representation (as defined above) of the resource that we are representing. Atom representations MUST comply with the rules of Atom Syndication Format (reference: Atom format).

• 1.0 Open an Atom <entry> element
  • 1.1 Add Atom <id> element. Atom requires a unique ID here and in the form of a URN, the resource URI MAY be used here.
  • 1.2 Add Atom <title> element. Atom requires a non-empty title value. A dc:title value MAY be used here.
  • 1.3 Add Atom <updated> element. Atom requires an updated date-time value. In cases where an updated-time value is difficult or expensive to compute, OSLC domain specifications might wish to declare this value to be insignificant.
  • 1.4 Add Atom <content> element. Atom representations MUST provide a content element that contains an RDF/XML of the resource being represented.
  • 1.5 Add Atom <author> element. Atom requires an author element.
• 2.0 Close Atom <entry> element

Rules for forming an Atom format OSLC Query Resource representation

When a client requests an Atom representation of an OSLC Defined Resource and specifies via HTTP Accept header content-type application/atom+xml or then an OSLC Service SHOULD respond with an Atom representation as described below.

To represent an OSLC Query Resource in Atom format we use an Atom <feed> element as document root, add the required properties and then represent each resource returned in the query response as an Atom <entry> element.

• 1.0 Open an Atom <feed> element
  • 1.1 To that element add as children the required Atom elements:
    • atom:id Must be a unique URN. The query resource URI may be used (i.e. same as oslc:ResponseInfo value for oslc:self)
    • atom:title With same value as the query's oslc:ResponseInfo value for dc:title
    • atom:updated Set to time that query result was generated
    • atom:author This element is not meaningful but Atom requires it, so provide only a dummy value.
  • 1.2. To that element add optional Atom elements that you wish to provide:
    • atom:summary Set to oslc:ResponseInfo value for dc:description
    • atom:link With rel="self" set to same value as the query's oslc:ResponseInfo value for oslc:self
    • atom:link With rel="next" set to same value as the query's oslc:ResponseInfo value for oslc:nextPage
  • 1.3 For each member property value returned by the query:
    • 1.3.1 Open an Atom <entry> element
    • 1.3.2 Add to that element the required Atom elements:
      • atom:id Must be a unique URN. The member value's URI may be used.
      • atom:title If the member value has a dc:title value, then use that. Otherwise provide a non-empty string with only a dummy value.
      • atom:updated If the member value has a dc:modified value then use that. Otherwise use same value used at feed level.
      • atom:author If the member value provides dc:creator values, then each should be represented as an atom:author element. Map either to or use both and together to form an = value seto to given name, comma and then family name.
    • 1.3.3 Add to the that element the atom:content element.
      • Set the atom:content element's src attribute to the URI of the member value
      • Set the atom:content element's type attribute to application/rdf+xml
      • Inside the content element, include a complete RDF/XML representation of the member value as specified by the query, i.e. may be a subset of the resource's values as specified by the query syntax string. Set the rdf:about attribute of the root element to the URI of the query base URI of the query.
    • 1.3.x Close the Atom </entry> element
• 2.0 Close the Atom </feed> element

Appendix A: Common Properties

This is a list of common properties and resources defined by the Core spec for use in OSLC Defined Resources. OSLC Workgroups are encouraged to consult this list when defining new resources and make use of common properties where appropriate.

Dublin Core Properties

These are the Dublin Core Metadata Element Set properties that are considered common (reference: Dublin Core).

• Namespace URI: http://purl.org/dc/terms
• Suggested Namespace Prefix: dc

Prefixed Name	Type	Typically Occurs	Title	Description
dc:title	XMLLiteral	exactly-one	Title	Title (reference: Dublin Core) of the resource represented as rich text in XHTML content. SHOULD include only content that is valid inside an XHTML <span> element.
dc:description	XMLLiteral	at-most-one	Description	Descriptive text (reference: Dublin Core) about resource represented as rich text in XHTML content. SHOULD include only content that is valid and suitable inside an XHTML <div> element.
dc:identifier	String	exactly-one	Identifier	A unique identifier for a resource. Typically read-only and assigned by the service provider when a resource is created. Not typically intended for end-user display -- it is often accompanied by a dc:name property.
dc:name	XMLLiteral	at-most-one	Name	Short name identifying a resource, often used as an abbreviated identifier for presentation to end-users. SHOULD include only content that is valid inside an XHTML <span> element.
dc:subject	String	zero-or-many	Subject	Tag or keyword for a resource. Each occurrence of a dc:subject property denotes an additional tag for the resource.
dc:creator	Resource or Local Inline Resource of type foaf:Person	zero-or-many	Creator	Creator or creators of resource (reference: Dublin Core)
dc:contributor	Resource or Local Inline Resource of type foaf:Person	zero-or-many	Contributor	Contributor or contributors to resource (reference: Dublin Core)
dc:created	Date Time	at-most-one	Created	Timestamp of resource creation (reference: Dublin Core)
dc:modified	Date Time	at-most-one	Modified	Timestamp last latest resource modification (reference: Dublin Core)

RDF Properties

These are the RDF/XML properties that are considered common.

• Namespace URI: http://www.w3.org/1999/02/22-rdf-syntax-ns#
• Suggested Namespace Prefix: rdf

Prefixed Name	Type	Typically Occurs	Title	Description
rdf:type	Resource	one-or-many	Type	The resource type URIs

OSLC Properties

These are the OSLC defined properties that are considered common.

• Namespace URI: http://open-services.net/xmlns/oslc#
• Suggested Namespace Prefix: oslc

Prefixed Name	Type	Typically Occurs	Title	Description
oslc:serviceProvider	Resource of type ServiceProvider	zero-or-many	Service Provider	The scope of a resource is a link to the resource's OSLC Service Provider.
oslc:instanceShape	Resource of type ResourceShape	at-most-one	Instance Shape	Resource Shape that specifies allowed and required fields.

Common Resource definitions

The OSLC Core specification may define common resource definitions, available for use in OSLC domain specifications as value-types. Currently, there is only one common resource: Person. Person is a common resource because a Person resource is required as the value for a dc:creator or dc:contributor property.

• Name: Person
• Suggested Prefix: foaf
• Namespace URI: http://xmlns.com/foaf/0.1/ (reference: FOAF)
• Properties
  • foaf:name (String, zero-or-one) - the full name of a person expressed as simple text string.
  • foaf:givenName (String, zero-or-one) - given name of person expressed as simple text string.
  • foaf:familyName (String, zero-or-one) - family name of person expressed as simple text string.
  • Other properties MAY be specified by OSLC Services

There is an additional constraint for foaf:Person. Implementations MUST specify either a non-empty foaf:name value or both a non-empty foaf:givenName and foaf:familyName values.

Appendix B: RDF/XML Representation examples

In this appendix we introduce a fictional service with two resource types and then provide examples representations of those resources, a Resource Shape, a Query Resource Shape, a Service Provider and query results in RDF/XML format. These example representations conform to the OSLC Core rules for RDF/XML representations.

Example Resources: fictional OSLC Blog Service

For the sole purpose of providing representation examples, we will define a fictional OSLC Blog Service with two resources: Blog Comment and Blog Comment. Each resource has a small set of required properties and each Comment is associated with an Entry. We will use these definitions in the RDF/XML examples in this appendix and in the JSON, Atom XML and Turtle examples that follow.

For example, we will define the blog entry and blog comment resources as follows:

• Name: Entry
• Namespace URI: http://open-services.net/xmlns/bogus/blogs#
• Type URI: http://open-services.net/xmlns/bogus/bogus/blogs#Entry
• Properties:
  • dc:title (XML Literal, exactly-one) title of Podcast
  • dc:modified (DateTime, exactly-one) - date/time that comment was created
  • dc:creator (Local In-Line Resource of type foaf:Person, exactly-one) - name of comment author
  • dc:content (XML Literal, exactly-one) - content of the comment

• Name: Comment
• Namespace URI: =http://open-services.net/xmlns/bogus/blogs=
• Type URI: http://open-services.net/xmlns/bogus/blogs#Comment
• Properties:
  • dc:modified (DateTime, exactly-one) - date/time that comment was created
  • dc:creator (In-Line Resource of type foaf:Person, exactly-one) - name of comment author
  • dc:content (XML Literal, exactly-one) - content of the comment
  • blog:entry (Resource, exactly-one of type blog:Entry) - link to the Blog Entry

Next, the RDF/XML examples for the key resources in our fictional OSLC Blog Service.

Resources

Below is an example RDF/XML representation of a blog entry.

Click HERE to see RDF/XML validation results, triples and RDF graph.

<oslc_blog:Entry
   rdf:about="http://example.com/blogs/entry/42"
   xmlns:oslc_blog="http://open-services.net/xmlns/oslc-core/bogus/blogs#" 
   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
   xmlns:foaf="http://http://xmlns.com/foaf/0.1/"
   xmlns:dc="http://purl.org/dc/elements/1.1/">

   <rdf:type 
      rdf:resource="http://open-services.net/xmlns/oslc-core/bogus/blogs#Entry" />

   <dc:title>I love trash</dc:title>
   <dc:modified>2002-10-10T12:00:00-05:00</dc:modified>
   <dc:content>
      Anything dirty or dingy or dusty. 
      Anything ragged or rotten or rusty.
   </dc:content>
   <dc:creator>
      <foaf:Person>
          <foaf:name>Oscar T. Grouch</foaf:name>
      </foaf:Person>
   </dc:creator>

</oslc_blog:Entry>

Below is an example RDF/XML representation of a blog comment.

Click HERE to see RDF/XML validation results, triples and RDF graph.

<oslc_blog:Comment 
   rdf:about="http://example.com/comments/883"
   xmlns:oslc_blog="http://open-services.net/xmlns/oslc-core/bogus/blogs#" 
   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
   xmlns:foaf="http://http://xmlns.com/foaf/0.1/"
   xmlns:dc="http://purl.org/dc/elements/1.1/" >

   <oslc_blog:entry rdf:resource="http://example.com/blogs/entry/42" />
   <dc:content>LOL! Tell us how you really feel, Oscar.</dc:content>
   <dc:modified>2002-10-10T12:12:23-05:00</dc:modified>
   <dc:creator>
      <foaf:Person>
          <foaf:name>William B. Bird</foaf:name>
      </foaf:Person>
   </dc:creator>

</oslc_blog:Comment>

Shape Resources

Below is an example RDF/XML representation of a Resource Shape for the Blog Comment resource defined above.

Click HERE to see RDF/XML validation results, triples and RDF graph.

<oslc:Shape
   rdf:about="http://example.com/shapes/commentshape"
   xmlns:oslc="http://open-services.net/xmlns/oslc-core#" 
   xmlns:oslc_blog="http://open-services.net/xmlns/oslc-core/bogus/blogs#" 
   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
   xmlns:foaf="http://http://xmlns.com/foaf/0.1/"
   xmlns:dc="http://purl.org/dc/elements/1.1/">

     <dc:title>Blog Comment Shape</dc:title>
     <rdf:type rdf:resource="http://open-services.net/xmlns/oslc#Shape" />

     <oslc:name>Comment</oslc:name>
     <oslc:namespace rdf:resource="http://open-services.net/xmlns/bogus/blog#" />
     <oslc:describes rdf:resource="http://open-services.net/xmlns/bogus/blog#Comment" />

     <oslc:property>
         <oslc:Property>
             <oslc:name>modified</oslc:name>
             <oslc:occurs>exactly-one</oslc:occurs>
             <oslc:namespace rdf:resource="http://purl.org/dc/terms#" />
             <rdf:type rdf:resource="http://purl.org/dc/terms#modified" />
             <oslc:valueType rdf:resource="http://www.w3.org/2001/XMLSchema#dateTime" />
         </oslc:Property>
     </oslc:property>

     <oslc:property>
         <oslc:Property>
             <oslc:name>creator</oslc:name>
             <oslc:occurs>exactly-one</oslc:occurs>
             <oslc:namespace rdf:resource="http://purl.org/dc/terms#"/>
             <rdf:type rdf:resource="http://purl.org/dc/terms#creator" />
             <oslc:valueType rdf:resource="http://open-service.net/xmlns/oslc-core/resource-types#LocalInlineResource" />
             <oslc:shape rdf:resource="http://example.com/blogs/personshape" />
         </oslc:Property>
     </oslc:property>

     <oslc:property>
         <oslc:Property>
             <oslc:name>content</oslc:name>
             <oslc:namespace rdf:resource="http://purl.org/dc/terms#" />
             <rdf:type rdf:resource="http://purl.org/dc/terms#content" />
             <oslc:valueType rdf:resource="http://www.w3.org/1999/02/22-rdf-syntax-ns#XMLLiteral" />
             <oslc:occurs>exactly-one</oslc:occurs>
         </oslc:Property>
     </oslc:property>

     <oslc:property>
         <oslc:Property>
             <oslc:name>entry</oslc:name>
             <oslc:namespace rdf:resource="http://purl.org/dc/terms#" />
             <rdf:type rdf:resource="http://purl.org/dc/terms#content" />
             <oslc:valueType rdf:resource="http://www.w3.org/1999/02/22-rdf-syntax-ns#XMLLiteral" />
             <oslc:occurs>exactly-one</oslc:occurs>
         </oslc:Property>
     </oslc:property>

</oslc:Shape>

Query Shape Resource

Below is a Resource Shape that specifies a Query Resource that can have blog entry and blog comment values.

Click HERE to see RDF/XML validation results, triples and RDF graph.

<oslc:Shape
     rdf:about="http://example.com/shapes/blogquery"
     xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
     xmlns:dc="http://purl.org/dc/terms#"
     xmlns:oslc="http://open-services.net/xmlns/oslc#">

     <dc:title>Blog Query Shape</dc:title>
     <rdf:type rdf:resource="http://open-services.net/xmlns/oslc#Shape" />

     <oslc:name>BlogQuery</oslc:name>
     <oslc:namespace rdf:resource="http://open-services.net/xmlns/bogus#" />
     <oslc:describes rdf:resource="http://open-services.net/xmlns/bogus#BlogQuery" />

     <oslc:property>
         <oslc:Property>
             <oslc:name>entry</oslc:name>
             <oslc:namespace rdf:resource="http://open-services.net/xmlns/blog#" />
             <oslc:occurs>zero-or-many</oslc:occurs>
             <oslc:shape rdf:resource="http://example.com/blogs/entryshape" />
             <rdf:type rdf:resource="http://open-services.net/xmlns/blog#Entry" />
             <oslc:valueType rdf:resource="http://open-service.net/xmlns/oslc-core/resource-types#InlineResource" />
             <oslc:isMemberProperty>true</oslc:isMemberProperty>
         </oslc:Property>
     </oslc:property>

     <oslc:property>
          <oslc:Property>
             <oslc:name>comment</oslc:name>
             <oslc:namespace rdf:resource="http://open-services.net/xmlns/blog#" />
             <oslc:occurs>zero-or-many</oslc:occurs>
             <oslc:shape rdf:resource="http://example.com/blogs/commentshape" />
             <rdf:type rdf:resource="http://open-services.net/xmlns/blog#Comment" />
             <oslc:isMemberProperty>true</oslc:isMemberProperty>
             <oslc:valueType rdf:resource="http://open-service.net/xmlns/oslc-core/resource-types#InlineResource" />
         </oslc:Property>
     </oslc:property>
 
     <oslc:property>
          <oslc:Property>
             <oslc:name>responseInfo</oslc:name>
             <oslc:namespace rdf:resource="http://open-services.net/xmlns/oslc#" />
             <oslc:occurs>zero-or-one</oslc:occurs>
             <oslc:shape rdf:resource="http://example.com/blogs/responseInfoShape" />
             <rdf:type rdf:resource="http://open-services.net/xmlns/oslc#ResponseInfo" />
             <oslc:valueType rdf:resource="http://open-service.net/xmlns/oslc-core/resource-types#InlineResource" />
         </oslc:Property>
     </oslc:property>
 
  </oslc:Shape>

Service Provider Resource

Below is an RDF/XML representation of a Service Provider resource for the fictional Blog Service.

Click HERE to see RDF/XML validation results, triples and RDF graph.

<oslc:ServiceProvider 
   rdf:about="http://example.com/service-provider"
   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
   xmlns:dc="http://purl.org/dc/terms#" 
   xmlns:oslc="http://open-services.net/xmlns/oslc#"
   xml:lang="en">

   <dc:title>Blogging Service</dc:title>  
   <dc:description>Example OSLC Blog Service</dc:description>

   <dc:contributor>
      <oslc:Contributor>
         <dc:title>OSLC Core Workgroup documentation department</dc:title>
         <dc:identifier>com.example.oslc.blogservice</dc:identifier>
         <oslc:icon rdf:resource="http://example.com/icons/blogservice.ico" />
      </oslc:Contributor>
   </dc:contributor>
   
   <oslc:namespaceDefinition>
      <oslc:NamepaceDefintion>
         <oslc:prefix>rdf</oslc:prefix>
         <oslc:namespaceURI>http://www.w3.org/1999/02/22-rdf-syntax-ns#</oslc:namespaceURI>
      </oslc:NamepaceDefintion>
   </oslc:namespaceDefinition>

   <oslc:namespaceDefinition>
      <oslc:NamepaceDefintion>
         <oslc:prefix>dc</oslc:prefix>
         <oslc:namespaceURI>http://purl.org/dc/terms#</oslc:namespaceURI>
      </oslc:NamepaceDefintion>
   </oslc:namespaceDefinition>

   <oslc:namespaceDefinition>
      <oslc:NamepaceDefintion>
         <oslc:prefix>oslc</oslc:prefix>
         <oslc:namespaceURI>http://open-services.net/xmlns/oslc#</oslc:namespaceURI>
      </oslc:NamepaceDefintion>
   </oslc:namespaceDefinition>

   <oslc:namespaceDefinition>
      <oslc:NamepaceDefintion>
         <oslc:prefix>oslc_blog</oslc:prefix>
         <oslc:namespaceURI>http://open-services.net/xmlns/bogus/blogs#</oslc:namespaceURI>
      </oslc:NamepaceDefintion>
   </oslc:namespaceDefinition>

   <oslc:service>
      <oslc:Service>
         <oslc:domain>http://example.com/xmlns/example-cm#</oslc:domain>

         <oslc:creationFactory>
            <oslc:CreationFactory>
               <dc:title>Location for creation of Blog Entries</dc:title>
               <oslc:label>Blog Entries</oslc:label>
               <oslc:creation rdf:resource="http://example.com/creation/entries" />
               <oslc:shape rdf:resource="http://example.com/shapes/blogentry" />
            </oslc:CreationFactory>
         </oslc:creationFactory>

         <oslc:creationFactory>
            <oslc:CreationFactory>
               <dc:title>Location for creation of Blog Comments</dc:title>
               <oslc:label>Blog Comments</oslc:label>
               <oslc:creation rdf:resource="http://example.com/creation/comments" />
               <oslc:shape rdf:resource="http://example.com/shapes/blogcomment" />
            </oslc:CreationFactory>
         </oslc:creationFactory>

         <oslc:queryCapability>
            <oslc:QueryCapability>
               <dc:title>Blog Entry and Comment Query</dc:title>
               <oslc:label>blogquery</oslc:label>
               <oslc:queryBase rdf:resource="http://example.com/query" />
               <oslc:shape rdf:resource="http://example.com/shapes/blogquery" />
            </oslc:QueryCapability>
         </oslc:queryCapability>

      </oslc:Service>
   </oslc:service>

</oslc:ServiceProvider>

Query Resource

Below is an example query resource, one which would be returned by the below query on our

Click HERE to see RDF/XML validation results, triples and RDF graph.

<oslc_blog:BlogQuery
     rdf:about="http://example.com/query;"
     xmlns:oslc_blog="http://open-services.net/xmlns/bogus/blogs#"
     xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
     xmlns:dc="http://purl.org/dc/terms#"
     xmlns:oslc="http://open-services.net/xmlns/oslc#">

    <oslc:responseInfo>
        <oslc:ResponseInfo>
            <dc:title>Blog Service Query Results for term [remote]</dc:title>
            <oslc:self rdf:resource="http://example.com/query?oslc.from [...] entry/42&gt;" />
        </oslc:ResponseInfo>
    </oslc:responseInfo>

    <oslc_blog:comment rdf:resource="http://example.com/blogs/comment/346" />
    <oslc_blog:comment rdf:resource="http://example.com/blogs/comment/344" />
    <oslc_blog:comment rdf:resource="http://example.com/blogs/comment/673" />
    <oslc_blog:comment rdf:resource="http://example.com/blogs/comment/232" />
    <oslc_blog:comment rdf:resource="http://example.com/blogs/comment/333" />

    <!-- etc. etc. -->

</oslc_blog:BlogQuery>

Appendix C: JSON Representation examples

In this appendix we provide examples representations of the examples resources defined in Appendix A. These example representations conform to the OSLC Core rules for JSON representations.

Resource

Below is an example JSON representation of the example blog entry.

{  
   "oslc:namespaceDefinition" : [{
      "qname" : "oslc:NamespaceDefinition"
      "prefix" : "dc",
      "namespaceURI" : "http://purl.org/dc/elements/1.1/" 
   },
   { "qname" : "oslc:NamespaceDefinition"
      "prefix" : "oslc_blog",
      "namespaceURI" : "http://open-services.net/xmlns/oslc-core/bogus/blogs#" 
   },
   { "qname" : "oslc:NamespaceDefinition"
      "prefix" : "foaf",
      "namespaceURI" : "http://http://xmlns.com/foaf/0.1/" 
   },
   {"qname" : "oslc:NamespaceDefinition"
      "prefix" : "rdf",
      "namespaceURI" : "http://www.w3.org/1999/02/22-rdf-syntax-ns#" 
   }],
   "qname" : "oslc_blog:Entry",
   "rdf:type" : { "uri" : "http://open-services.net/xmlns/oslc-core/bogus/blogs#Entry" },
   "uri" : "http://example.com/blogs/entry/42",
   "dc:title", "I love trash",
   "dc:modified" : "2002-10-10T12:00:00-05:00",
   "dc:content", "Anything dirty or dingy or dusty. \\nAnything ragged or rotten or rusty."
   "dc:creator" : {
      "qname" : "foaf:Person",
      "foaf:name" : "Oscar T. Grouch"
   },
}
 

Below is an example JSON representation of the example blog comment.

{  
   "oslc:namespaceDefinition" : [{
      "qname" : "oslc:NamespaceDefinition"
      "prefix" : "dc",
      "namespaceURI" : "http://purl.org/dc/elements/1.1/" 
   },
   { "qname" : "oslc:NamespaceDefinition"
      "prefix" : "oslc_blog",
      "namespaceURI" : "http://open-services.net/xmlns/oslc-core/bogus/blogs#" 
   },
   { "qname" : "oslc:NamespaceDefinition"
      "prefix" : "foaf",
      "namespaceURI" : "http://http://xmlns.com/foaf/0.1/" 
   },
   {"qname" : "oslc:NamespaceDefinition"
      "prefix" : "rdf",
      "namespaceURI" : "http://www.w3.org/1999/02/22-rdf-syntax-ns#" 
   }],
   "qname" : "oslc_blog:Comment",
   "rdf:type" : { "uri" : "http://open-services.net/xmlns/oslc-core/bogus/blogs#Comment" },
   "uri" : "http://example.com/comments/883",
   "dc:modified" : "2002-10-10T12:12:23-05:00",
   "dc:content", "LOL! Tell us how you really feel, Oscar."
   "dc:creator" : {
      "qname" : "foaf:Person",
      "foaf:name" : "William B. Bird"
   },
}
 

Service Provider Resource

Below is an example JSON representation of the example blog service provider.

{
   "qname" : "oslc:ServiceProvider",
   "uri" : "http://example.com/service-provider",

   "dc:title" : "Blogging Service",
   "dc:description": "Example OSLC Blog Service",

   "dc:contributor" : {
      "qname": "oslc:Contributor",
      "dc:title" : "OSLC Core Workgroup documentation department",
      "dc:identifier": "com.example.oslc.blogservice",
      "oslc:icon" : "http://example.com/icons/myprod.ico"
   },

   "oslc:namespaceDefinition" : [{
      "qname" : "oslc:NamespaceDefinition"
      "prefix" : "dc",
      "namespaceURI" : "http://purl.org/dc/elements/1.1/" 
   },
   { "qname" : "oslc:NamespaceDefinition"
      "prefix" : "rdf",
      "namespaceURI" : "http://www.w3.org/1999/02/22-rdf-syntax-ns#" 
   },
   { "qname" : "oslc:NamespaceDefinition"
      "prefix" : "oslc",
      "namespaceURI" : "http://open-services.net/xmlns/oslc#" 
   },
   {"qname" : "oslc:NamespaceDefinition"
      "prefix" : "oslc_blog",
      "namespaceURI" : "http://open-services.net/xmlns/bogus/blogs#" 
   }],

   "service" : {
         "qname": "oslc:Service",
         "oslc:domain": "http://open-services.net/xmlns/bogus/blogs#",

         "oslc:creationFactory": {
            "qname": "oslc:CreationFactory",
            "dc:title", "Location for creation of Blog Entries",
            "oslc:label", "Blog Entries",
            "oslc:creation" : { "uri" : "http://example.com/creation/entries" },
            "oslc:shape" : { "uri" : "http://example.com/shapes/blogentry" }
         },
         "oslc:creationFactory": {
            "qname": "oslc:CreationFactory",
            "dc:title", "Location for creation of Blog Comments",
            "oslc:label", "Blog Comments",
            "oslc:creation" : { "uri" : "http://example.com/creation/comments" },
            "oslc:shape" : { "uri" : "http://example.com/shapes/blogcomment" }
         },
         "oslc:queryCapability": {
            "qname": "oslc:QueryCapability",
               <dc:title> Blog Entry and Comment Query</dc:title>
               <oslc:label> blogquery </oslc:label>
               <oslc:creation rdf:resource="http://example.com/query" />
               <oslc:shape rdf:resource="http://example.com/shapes/blogquery" />
         },
     }
}

Query Resource

Below is an example JSON representation of the example blog query result.

{
   "oslc:namespaceDefinition" : [ { 
      "qname" : "oslc:NamespaceDefinition"
      "prefix" : "oslc_blog",
      "namespaceURI" : "http://open-serivces.net/xmlns/bogus/blog#" 
   },
   { "qname" : "oslc:NamespaceDefinition"
      "prefix" : "dc",
      "namespaceURI" : "http://purl.org/dc/elements/1.1/" 
   },
   { "qname" : "oslc:NamespaceDefinition"
      "prefix" : "rdf",
      "namespaceURI" : "http://www.w3.org/1999/02/22-rdf-syntax-ns#"
   },
   { "qname" : "oslc:NamespaceDefinition"
      "prefix" : "oslc",
      "namespaceURI" : "http://open-serivces.net/xmlns/core" 
   } ],
   "qname" : "oslc_blog:BlogQuery",
   "uri" : "http://example.com/query?oslc%3Aquery=remote",

   "oslc:responseInfo" : {
      "qname" : "oslc:ResponseInfo",
      "dc:title" : "Blog Service Query Results for term [remote]",
      "oslc:self" : "http://example.com/query?oslc%3Aquery=remote"
      "oslc:nextPage" : "http://example.com/query?oslc%3Aquery=remote&page=2"
   }, 

   "oslc_blog:comment" : [{
       "qname" : "oslc_blog:BlogComment",
       "uri" : "http://example.com/blogs/comment/346",
    },
    { "qname" : "oslc_blog:BlogComment",
       "uri" : "http://example.com/blogs/comment/344",
    },
    { "qname" : "oslc_blog:BlogComment",
       "uri" : "http://example.com/blogs/comment/673",
    },
    { "qname" : "oslc_blog:BlogComment",
       "uri" : "http://example.com/blogs/comment/232",
    },
    { "qname" : "oslc_blog:BlogComment",
       "uri" : "http://example.com/blogs/comment/333",
    }]
}

Appendix D: Atom Xml Representation examples

In this section we present example Atom format representations of the example resources defined in Appendix A.

Resource

Below is an example Atom entry representation of the example blog entry.

<entry>
   <id>http://example.com/blogs/entry/42</id>
   <title>I love trash</title>
   <author><name>Oscar T. Grouch</name></author>
   <content type="application/rdf+xml>

      <oslc_blog:Entry
         rdf:about="http://example.com/blogs/entry/42"
         xmlns:oslc_blog="http://open-services.net/xmlns/oslc-core/bogus/blogs#" 
         xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
         xmlns:foaf="http://http://xmlns.com/foaf/0.1/"
         xmlns:dc="http://purl.org/dc/elements/1.1/">
         <rdf:type 
            rdf:resource="http://open-services.net/xmlns/oslc-core/bogus/blogs#Entry" />
         <dc:title>I love trash</dc:title>
         <dc:modified>2002-10-10T12:00:00-05:00</dc:modified>
         <dc:content>
            Anything dirty or dingy or dusty. 
            Anything ragged or rotten or rusty.
         </dc:content>
         <dc:creator>
            <foaf:Person>
                <foaf:name>Oscar T. Grouch</foaf:name>
            </foaf:Person>
         </dc:creator>
      </oslc_blog:Entry>

   </content>
</entry>

Below is an example Atom entry representation of the example blog comment.

<entry>
   <id>http://example.com/comments/883</id>
   <title>Blog Comment</title>
   <author><name>William B. Bird</name></author>
   <content type="application/rdf+xml>

      <oslc_blog:Comment 
         rdf:about="http://example.com/comments/883"
         xmlns:oslc_blog="http://open-services.net/xmlns/oslc-core/bogus/blogs#" 
         xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
         xmlns:foaf="http://http://xmlns.com/foaf/0.1/"
         xmlns:dc="http://purl.org/dc/elements/1.1/" >
         <oslc_blog:entry rdf:resource="http://example.com/blogs/entry/42" />
         <dc:content>LOL! Tell us how you really feel, Oscar.</dc:content>
         <dc:modified>2002-10-10T12:12:23-05:00</dc:modified>
         <dc:creator>
            <foaf:Person>
               <foaf:name>William B. Bird</foaf:name>
            </foaf:Person>
         </dc:creator>
      </oslc_blog:Comment>

   </content>
</entry>

Query Resource

Below is an example Atom feed representation of the example blog query result.

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

<id>http://example.com/query?page=2&oslc.from [...] 42&gt;</id>
<title>Blog Query Results for term [remote]<title>
<updated>2009-10-10T12:00:00-05:00</updated>

<link rel="self" 
   href="http://example.com/query?oslc.from [...] entry/42>"> 
<link rel="next" 
   href="http://example.com/query?page=2&amp;oslc.from [...] entry/42>">

<entry> 
   <title>Blog Query Result for term [remote]<title>
   <updated>2009-10-10T12:00:00-05:00</updated>
   <content type="application/rdf+xml"> 
      <oslc_blog:BlogComment rdf:about="http://example.com/query">
         <oslc_blog:comment rdf:resource="http://example.com/blogs/comment/346" />
      </oslc_blog:BlogComment>
   </content> 
</entry>

<entry> 
   <title>Blog Query Result for term [remote]<title>
   <updated>2009-10-10T12:00:00-05:00</updated>
   <content type="application/rdf+xml"> 
      <oslc_blog:BlogComment rdf:about="http://example.com/query">
         <oslc_blog:comment rdf:resource="http://example.com/blogs/comment/344" />
      </oslc_blog:BlogComment>
   </content> 
</entry>

<entry> 
   <title>Blog Query Result for term [remote]<title>
   <updated>2009-10-10T12:00:00-05:00</updated>
   <content type="application/rdf+xml"> 
      <oslc_blog:BlogComment rdf:about="http://example.com/query">
         <oslc_blog:comment rdf:resource="http://example.com/blogs/comment/673" />
      </oslc_blog:BlogComment>
   </content> 
</entry>

<entry> 
   <title>Blog Query Result for term [remote]<title>
   <updated>2009-10-10T12:00:00-05:00</updated>
   <content type="application/rdf+xml"> 
      <oslc_blog:BlogComment rdf:about="http://example.com/query">
         <oslc_blog:comment rdf:resource="http://example.com/blogs/comment/232" />
      </oslc_blog:BlogComment>
   </content> 
</entry>

<entry> 
   <title>Blog Query Result for term [remote]<title>
   <updated>2009-10-10T12:00:00-05:00</updated>
   <content type="application/rdf+xml"> 
      <oslc_blog:BlogComment rdf:about="http://example.com/query">
         <oslc_blog:comment rdf:resource="http://example.com/blogs/comment/333" />
      </oslc_blog:BlogComment>
   </content> 
</entry>

</feed>

Appendix E: Turtle Representation examples

In this section we present example Atom format representations of the example resources defined in Appendix A.

Resource

Below is an example JSON representation of the example blog entry.

TBD

Below is an example JSON representation of the example blog comment.

TBD

Shape Resource

Below is an example JSON representation of the example blog comment shape.

TBD

Service Provider Resource

Below is an example JSON representation of the example blog service provider.

TBD

Query Resource

Below is an example JSON representation of the example blog query result.

TBD

Appendix F: References

These are the specifications referenced by the OSLC Core Specification.

• BNF Backus-Naur Form
• CSS - Cascading Style Sheets Level 2 Revision 2 v2.1
• Dublin Core - Dublin Core Metadata Element Set, Version 1.1
• FOAF - Friend of a Friend (FOAF)
• HTML5 Posting Message- W3C HTML5 postMessage
• HTTP - Hyper-text Transfer Protocol (HTTP/1.1)
• RDF/XML Concepts - RDF/XML Concepts and Abstract Syntax
• RDF/XML Syntax - RDF / XML Syntax Specification (Revised)
• URI Syntax - URI Generic Syntax
• Window Object - Window Object 1.0 Window.name
• XML Namespaces - Namespaces in XML 1.0 (Third Edition)
• XML Base - XML Base (Second Edition)
• XSD Datatypes - XML Schema Part 2: Datatypes Second Edition