This family of documents defines the Open Services for Lifecycle Collaboration Key Performance Indicators (KPIs) Management and Definition specification, also known as OSLC KPI. These documents collectively define the OSLC KPI 1.0 specification. This specification supports key REST APIs for Key Performance Indicator systems. OSLC KPI 1.0 takes an open, loosely coupled approach to specific lifecycle integration scenarios. The scenarios and this V1.0 specification were created by the Knowledge Reuse Group (UC3M) and The Reuse Company (TRC).

This specification builds on the Open Services for Lifecycle Collaboration (OSLC) Core v2.0 Specification to define the resources, properties and operations supported by an OSLC KPIs Definition and Management (OSLC-KPI) provider.

Key Performance Indicator resources include Indicators, Indicators Collection, Observations and supporting resources defined in the OSLC Core specification. The properties defined describe these resources and the relationships between resources. Operations are defined in terms of HTTP methods and MIME type handling. The resources, properties and operations defined do not form a comprehensive interface to Key Performance Indicator Definition and Management, but instead target specific integration use cases.

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. Domain name examples use RFC2606.

This document defines a Key Performance Indicators Specification. It is based on existing Open Services for Lifecycle Collaboration (OSLC) documents following a similar structure and reusing some of the common contents.

This document has also followed the guidelines by W3C and its tool Respec to provide a common visual format to other existing specifications.

If you wish to make comments regarding this document, please send them to this repository. All comments are welcome.

This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

Introduction

Public and private bodies are continuously seeking new analytical tools and methods to assess some policy, change, specification, quality, etc. and to support their decisions. Nevertheless the sheer mass of data now available is raising a new dynamic and challenging environment in which traditional tools are facing major problems to deal with data-sources diversity, structural issues or complex processes of estimation. New paradigms and tools are required to take advantage of the existing data-based environment to design and estimate actions in this dynamic context according to needs of transparency, standardization, adaptability and extensibility among others with the aim of providing new context-aware and added-value services that can help a deepen and broaden understanding of the impact of a policy (or a requirement change) in a more fast and efficient way. As a consequence common features can be extracted from the existing situation:

• Data sources. Data and information are continuously being generated as observations from social networks, public and private institutions, NGOs, services and applications, etc. creating a tangled environment of sources, formats and access protocols with a huge but restricted potential for exploitation. Nevertheless data processing, knowledge inferring, etc. are not mere processes of gathering and analyzing, it is necessary to deal with semantic and syntactic issues, e.g. particular measurements and dimensions or name mismatches, in order to enable a proper data/information re-use and knowledge generation.
• Structure. Quantitative indexes are a common practice and are usually defined (a mathematical model) by experts to aggregate several indicators (in a hierarchy structure) in just one value to provide a measure of the impact or performance of some policy in a certain context. The structure of these indexes is obviously subjected to change over time to collect more information or adjust their composition and relationships (narrower/broader). That is why technology should be able to afford adequate techniques to automatically populate new changes in an efficient way.
• Computation process. This feature refers to the calculation of a quality index. Observations are gathered from diverse data sources and aligned to an structure (commonly indicators) that is processed through various mathematical operators to generate a final index value. Nevertheless the computation process is not always described neither open (any minor change can imply a long time for validation) implying that cannot be easily replied for third-parties with other purposes, for instance research, preventing one of the most wanted characteristics such as transparency. Furthermore it is necessary to ensure that the computation process is sound and correct.
• Documentation. New policy-making or quality management strategies go ahead of a simple and closed value and it is necessary to bring new ways of exploiting data and information. Moreover the use of the Web-based protocols as a dissemination channel represents a powerful environment in which information should be available taking into account the multilingual and multicultural character of information. In this context documentation mechanisms must necessarily cover all the aforementioned features to afford a detailed explanation of a quantitative index-based policy to both policymakers and final users. However existing initiatives usually generates some kind of hand-made report which is not easy to keep up-to-date and deliver to the long-tail of interested third-parties.

Motivation and Objectives

Obviously semantic-based technologies, as underlying concepts of the OSLC initiative, can partially address this challenging environment for supporting new quality-checking strategies. A common and shared data model based on existing standardized semantic web vocabularies and datasets can be used to represent indicators, unit metrics, or observations from both, structural and computational, points of view enabling a right exploitation of meta-data and semantics. That is why the present section introduces: a high-level model on top of the RDF Data Cube Vocabulary, a shared effort to model statistical data in RDF reusing parts (the cube model) of the Statistical Data and Metadata Exchange Vocabulary (SDMX), to represent the structure and computation (if needed) of indicators and observations.

Terminology

Essentially a quantitative index or just a set of KPIs (without any underlying structured) is comprised of several components. In the same way, a component can also be composed of the aggregation of indicators that keep concrete observations. From this initial definition some characteristics and assumptions can be found:

1. Although observations can be directly mapped to an index or a component, they are frequently computed applying a bottom-up approach from an indicator to a component and so on.
2. An observation is a real numerical value (general speaking, a resource value) extracted from some agent or tool out under a precise context. Generally observations only take one measure and are considered to be raw without any pre-processing.
3. Before aggregating observation values, components and indexes can estimate missing values to finally normalize them in order to get a quantitative value.

According to the aforementioned characteristics and assumptions an observable element (index, component or indicator) comprises a dataset of observations under a specific context (dimensions and/or meta-data) that can be directly gathered from external sources or computed by some kind of OWA (Ordered Weighted Averaging) operator.

• Definition 1 (Observation o). It is a tuple{v,m,s}, where v is a numerical value for the measure m with an status s that belongs to only one dataset of observations O.
• Definition 2 (Dataset q). It is a tuple{O,m,D,A,T}, where O is a set of observations for only one measure m that is described under a set of dimensions D and a set of annotations A. Additionally, some attributes can be defined in the set T for structure enrichment.
• Definition 3 (Aggregated Dataset aq). It is an aggregation of n datasets q_i (identified by the set Q) which set of observations O is derivate by applying an OWA operator p to the observations O_(q_i )

As a necessary condition for the computation process, an aggregated dataset aq defined by means of the set of dimensions D_aq can be computed iif ∀ q_j ∈ Q: D_aq ⊆ D_qj. Furthermore the OWA operator p can only aggregate values belonging to the same measure m. As a consequence of the aforementioned definitions some remarks must be outlined in order to restrict the understanding of a quantitative index (structure and computation):

• The set of dimensions D, annotations A and attributes T for a given dataset Q is always the same with the aim of describing all observations under the same context.
• An index i and a component c are aggregated datasets. Nevertheless this restriction is relaxed if observations can be directly mapped to these elements without any computation process.
• An indicator in can be either a dataset or an aggregated dataset.
• All elements in definitions must be uniquely identified.
• An aggregated dataset is also a dataset.

Building on the aforementioned definitions, it is possible to describe a set of key performance indicators, observations, indicators composition and structure. In this light, a direct translation built on the top of the RDF Data Cube Vocabulary (represented using the prefix qb), SDMX and other semantic web vocabularies is presented in the next table. Thus, all concepts are described reusing existing definitions, taking advantage of previous efforts and pre-established semantics with the aim of being extended in the future to fit new context.

This approach is focused on publishing of statistical values without paying special attention to what type of indicators and observations are going to be generated. Thus, two major resources are defined, KPI and Observation, to create new constructors or primitives on top of the RDF Data Cube Vocabulary, see Figure 1.

Figure 1: Overview of the data model to represent KPIs and observations.

The main advantage of this approach lies on the separation of dimensions and attributes between indicators and observations. Obviously both can contain particular metaproperties (attributes) but main and common characteristics (dimensions and attributes) of all observations are refactored in the indicator structure. Besides, some positive side effects of this approach lies on the possibility of easing the versioning and tracking of observations on the same indicator. For instance, observations can be easily sliced by a dimension or an attribute. In the case of requirements quality, a dimension can be a project, an indicator, etc.

However, the main drawback of this approach is that is not closed (an intrinsic RDF characteristic), new dimensions or/and attributes could be automatically generated by third-party tools. That is why, it is completely necessary to merge the advantages of this approach with the existing OSLC specifications about “Performance Monitoring” and “Estimation and Measurement” that provide a closed shape for publishing metrics and observations.

Base Key Performance Indicators

Compliance

Specification Versioning

See Core Specification Version 2.0 - Specification Versioning.

Service providers that support the resource formats and services in this specification MUST add an HTTP response header of OSLC-Core-Version with a value of 2.0. Consumers SHOULD request formats and services defined in this document by providing a HTTP request header of OSLC-Core-Version with a value of 2.0. See section below on Version Compatibility with OSLC RM 1.0 Specifications.

This specification reserves, for possible future use, the use of the HTTP header OSLC-KPI-Version. OSLC Providers MUST NOT use this HTTP header.

Namespaces

In addition to the namespace URIs and namespace prefixes oslc, rdf, dcterms and foaf defined in the Core Specification Version 2.0, OSLC KPI defines the namespace URI of http://trc-research.github.io/spec/kpi/ with a preferred namespace prefix of oslc_kpi.

Furthermore, the RDF Data Cube Vocabulary, a W3C Recommendation, is also defined through the namespace: http://purl.org/linked-data/cube# and prefix: qb. Other semantic-based vocabularies will use the de facto namespace and prefix that can be searched using the service: Prefix.cc.

Resource Formats

In addition to the requirements for Core Specification Version 2.0 - OSLC Defined Resource Representations, this section outlines further refinements and restrictions.

For HTTP GET/PUT/POST requests on all OSLC RM and OSLC Core defined resource types,

• KPI Providers MUST support RDF/XML representations with media-type application/rdf+xml. KPI Consumers MUST be prepared to deal with any valid RDF/XML document.
• KPI Providers MUST support XML representations with media-type application/xml. The XML representations MUST follow the guidelines outlined in Core Specification Appendix B: Representations and Examples.
• KPI Providers MAY support JSON representations with media-type application/json. The JSON representations MUST follow the guidelines outlined in Core Specification Appendix B: Representations and Examples.

Additionally, for HTTP GET,

• KPI Providers SHOULD provide an [X]HTML representation and a user interface (UI) preview as defined by Core Specification Version 2.0 UI Preview

For HTTP GET response formats for Query requests,

• KPI Providers MUST support RDF/XML representations with meda-type application/rdf+xml.
• KPI Providers MUST support XML representations with media-type application/xml.
• KPI Providers MAY support JSON representations with media-type application/json.

OSLC Providers MAY refuse to accept RDF/XML documents which do not have a top-level rdf:RDF document element. The OSLC Core describes an example, non-normative algorithm for generating RDF/XML representations of OSLC Defined Resources.

In addition to the resource formats defined above, providers MAY support additional resource formats; the meaning and usage of these resource formats is not defined by this specification.

Authentication

See Core Specification Version 2.0 - Authentication. OSLC KPI places no additional constraints on authentication.

Error Responses

See Core Specification Version 2.0 - Error Responses. OSLC RM places no additional constraints on error responses.

Pagination

OSLC KPI service providers SHOULD support pagination of query results as defined by the OSLC Core Specification. OSLC RM service providers MAY support pagination of a single resource's properties as defined by the OSLC Core Specification.

Requesting and Updating Properties

Requesting Selected Properties

A client may want to request a subset of a resource's properties as well as properties from a referenced resource. In order to support this behaviour a service provider MUST support the oslc.properties and oslc.prefix URL parameter on a HTTP GET request on individual resource request or a collection of resources by query. If the oslc.properties parameter is omitted on the request, or if the value of this parameter is "*", then all resource properties MUST be provided in the response. See OSLC Core Specification - Selective Property Values.

Updating Selected Properties

A provide MAY accept oslc.properties on a PUT with the meaning that only that subset of the resource's properties be updated.

If the parameter oslc.properties contains a valid resource property on the request that is not provided in the content, the server MUST treat that as a request to remove that property from the resource. If the parameter oslc.properties contains an invalid resource property, then a 409 Conflict MUST be returned.

KPI Resource Definitions

Property value types that are not defined in the following sections, are defined in Core Specification Version 2.0 - Defining OSLC Properties.

The meaning of the columns in the following table is defined as follows. See also OSLC Core Specification Appendix A: Common Properties for further details on Resource Shapes.

• Occurs: The multiplicity of the property (corresponds to "oslc:occurs" on an "oslc:Property" resource).
• Read-only: Whether the Provider will accept value changes (corresponds to "oslc:readOnly" on an "oslc:Property" resource). "Unspecified" indicates that this specification places no requirements on a Provider's behaviour in this regard.
• Value-type: Corresponds to "oslc:valueType" on an "oslc:Property" resource.
• Representation: Corresponds to "oslc:representation" on an "oslc:Property" resource.
• Range: Corresponds to "oslc:range" on an "oslc:Property" resource. "Any" indicates that this specification places no "oslc:range" constrains on a property. Consumers in particular should not make assumptions about the range of such properties.
• Description: A textual description of the meaning of the property.

KPI Resource

This is a resource to represent a key performance indicator about which observations will be generated. It contains the common context (dimensions and attributes) for all generated observations such as unit metrics, tool, project, etc.

This approach is based on the promotion of statistical data following the principles of the W3C Recommendation "The RDF Data Cube Vocabulary".

Observation Resource

A single observation that is linked to a KPI through a dataset or slice and only contains a value (commonly a double value).

Relationship labels

When an KPI relationship property is to be presented in a user interface, it may be helpful to provide an informative and useful textual label for that relationship instance. (This in addition to the relationship property URI and the object resource URI, which are also candidates for presentation to a user.) To this end, OSLC providers MAY suppport a dcterms:title link property in RM resource representations where a relationship property is permitted, using the anchor approach outlined in the OSLC Core Links Guidance.

Providers and consumers should be aware that the dcterms:title of a link is unrelated to the dcterms:title of the object resource. Indeed, links may carry other properties with names in common to the object of the link, but there is no specified relationship between these property values.

KPI Service Provider Capabilities

Service Provider Resources

Service providers MUST provide one or more oslc:ServiceProvider resources as defined by Core Specification Version 2.0 - Service Provider Resource. Discovery of OSLC Service Provider Resources MAY be via one or more OSLC Service Provider Catalog Resources, or may be discovered by some other and/or additional Provider-specific means outwith the scope of this specification. The oslc:Service resources referenced by this oslc:ServiceProvider MUST have an oslc:domain of http://trc-research.github.io/spec/kpi/.

Service providers MAY provide one more more oslc:ServiceProviderCatalog resources as defined by Core Specification Version 2.0 - Service Provider Resources. Any such catalog resources MUST include at least one oslc:domain of http://trc-research.github.io/spec/kpi/. Discovery of top-level OSLC Service Provider Catalog Resources is outwith the scope of this specification.

Service providers MUST give an oslc:serviceProvider property on all OSLC Defined Resources. This property MUST refer to an appropriate oslc:ServiceProvider resource.

Creation Factories

Service providers supporting resource creation MUST do so through oslc:CreationFactory resources, as defined by Core Specification Version 2.0 - Creation Factories. Any such factory resources MUST be discoverable through oslc:Service resources. Providers SHOULD provide oslc:ResourceShape resources on oslc:CreationFactory resources as defined by OSLC Core Specification Appendix A: Common Properties - Resource Shapes.

Query Capabilities

Service providers MUST support query capabilities, as defined by Core Specification Version 2.0 - Query Capabilities. Providers SHOULD provide oslc:ResourceShape on oslc:QueryCapability resources as defined by OSLC Core Specification Appendix A: Common Properties - Resource Shapes.

The Query Capability MUST support these parameters:

• oslc.where
• oslc.select
• oslc.properties
• oslc.prefix

Where oslc:ResourceShape is not supported by the Query Capability, providers SHOULD use the following guidance to represent query results:

• For RDF/XML and XML, use rdf:Description and rdfs:member as defined by Core Specification Appendix B:Representations and Examples - RDF/XML Examples.
• For JSON the query results are contained within oslc:results array. See Core Specification Appendix B: Representations and Examples - Guidelines for JSON.

The stability of query results is OPTIONAL (see Core Specification Version 2.0 - Stable Paging)

Delegated UIs

OSLC KPI service providers MUST support the selection and creation of resources by delegated web-based user interface dialogs Delegated UIs as defined by OSLC Core.

OSLC KPI service providers MAY support the pre-filling of creation dialogs based on the definition at Delegated UIs.

Usage Identifiers

OSLC KPI service provider MAY identify the usage of various services with additional property values for the OSLC Core defined oslc:usage property on oslc:Dialog, CreationFactory and QueryCapability. The oslc:usage property value of http://open-services.net/ns/core#default SHOULD be used to designate the default or primary service to be used by consumers when multiple entries are found.

There are no additional usage identifiers defined by this specification. OSLC Providers MAY provide their own usage URIs. Such usage URIs MUST be in a non-OSLC namespace.

Media Types

To identify a format of RDF/XML, the media type used for RM resource representations MUST be application/rdf+xml. The usage of the OSLC RM 1.0 defined media types of application/x-oslc-kpi-kpi-1.0+xml, application/x-oslc-kpi-kpi-collection-1.0+xml, application/x-oslc-kpi-service-description-1.0+xml and application/x-oslc-disc-service-provider-catalog+xml is deprecated.

Requesting formats

RM 1.0 consumers wanting to request 1.0 resource formats will not need to change if they used 1.0 defined media types ( application/x-oslc-kpi*), see oslc-kpi 1.0. RM 2.0 consumers should use media types as defined in this specification for requests, excluding the OSLC RM 1.0 specific media types ( application/x-oslc-kpi*). RM consumers supporting both 1.0 and 2.0, should request request both 1.0 and 2.0 media types on HTTP GET requests as usually done with HTTP request parameter Accept giving appropriate quality (See HTTP Accept) weighting to help distinguish their preferred content.

For additional guidance, a KPI 1.0 consumer or provider MAY reference the OSLC-Core-Version HTTP header with a value of 1.0.

Open Issues

As it has been previously stated, the main advantage of this approach lies on the creation of a specific element, KPI, that serves to refactor the context of a set of observation in just one place. Any KPI can keep a list of datasets grouping observations according to a dimension such as time or tool. KPIs can be separately shared and combined.

Nevertheless, this framework for automatically populating observations as RDF contains a main drawback due to the fact that do not represent a closed shape. That is why, next version of this approach must merge the concept of KPI within the existing definitions in the “OSLC Performance Monitoring”, “OSLC Estimation and Measurement (EMS)” specifications (even some definitions of the “OSLC Quality Management” can be also re-used), see Figure 2, taking advantage of both sides to publish and exchange observations under a particular context and linked to an indicator.

Figure 2: OSLC KPIs as a combined specification of existing OSLC specifications.