Introduction

This specification defines a REST API that provides estimation and measurement capabilities. Web applications may either implement or use these interfaces. We refer to an implementation of these interfaces as a service provider and user of these interfaces as a service consumer.

In practice, PPM and software estimation tools may be either service consumers or providers. That decision is up to the tool architect. For example, a desktop-based tool may be a consumer while a server-based tool may be either a consumer or a provider.

The EM Service

In order to separate tool architecture concerns from the specification of the EMS 1.0 REST API, it is useful to imagine that a standalone Web application is the service provider. We will refer to such an application simply as an EM service. The following diagram illustrates the context of an EM service:

Packaging the EM Service with Products

The above diagram treats all collaboratoring tools on an equal footing with respect to the EM service and the EMS 1.0 REST API is described from the point of view of the EM service. However, as noted above, it is likely that the EM service would be included as part of a more comprehensive product, either integrated with a single tool or shared among a suite of related tools. For example, the following context diagram illustrates a software estimation product that includes an EM service:

Tool Collaborations

The following discussion briefly illustartes how PPM and software estimation tools might use an EM service to collaborate.

The portfolio management tool initiates projects. A portfolio manager creates the project proposal, which includes all relevant project contraints such as size, duration, or peak staffing, sends them to the EM service, and requests an estimate. The software estimator receives this request, launches the software estimation tool, produces an estimate, sends it back to the EM service, and notifies the portfolio manager. The portfolio manager then gets estimate from the EM service, completes the project business case, and submits the project proposal to the approval process. The EM service maintains a persistent record of the project proposal and estimates for future use. If the project gets approved, the portfolio management system hands off the project to the project management system.

The project management tool plans, monitors, and controls projects. As the project executes, measurements are collected by the performance management tool. The project manager runs reports from the performance management tool that show the measurements relative to the estimates. If the measurements vary too much from the estimates, the project manager takes corrective action. Periodically, the project manager sends revised project constraints to the EM service and requests the software estimator to reestimate the project to completion, taking into account the measurements to date. The new estimates become part of the project baseline and the project manager continues on to the next phase of the project.

The performance management tool collects measurements from the software development and PPM tools, and provides a business intelligence user interface for managers and other team members to view and explore the data, e.g. to diagnose problems. The performance management tool also collects estimates from the EM service so that the measurements can be compared to the estimates. The performance management system can display dashboards, scorecards, control charts, and other presentations of the data to allow team members to track the performance of the project. The performance management tool also provides measurements to the EM service to enable both reestimation of project plans and calibration of software estimation models based on past completed projects.

The software estimation tools get project contraints and measurements from the EM service, and send it estimates. Software estimation tools are used for calibrating models, providing initial cost estimates and plans, and reestimating project plans.

In practice, performance management tools use Extract-Transform-Load (ETL) processes to collect data. A REST API can act as a source of data for ETL, and the EM service will provide a REST API that is suitable for use by ETL processes, mainly so that the performance management tool can load the estimates and make them available for use in reports. Performance management tools provide reporting mechanisms for accessing data. In principle, any application could access measurement data directly from the performance management tool through its reporting interface, however that approach would result in a replication of business logic. A better approach is to use the EM service as a proxy to the performance management tool.

Given the above considerations, software estimation, portfolio management, and project management tools will be read-write consumers of the EM service, but the performance management tool will be a read-only consumer. The EM system will be a consumer of the performance management tool’s native reporting interface in order to access measurements.

Introduction

The following sections discuss the general design principles used in this specification.

Implementation-Dependent Features

Before discussing the design further, it is appropriate to define the scope of this specification by listing those general features of a service that are not specified here.

Authentication

This specification does not define an authentification mechanism. Service providers SHOULD support some authentication mechansim but are free to support a variety of authentication mechanisms. However, in order to ensure interoperability with a broad set of other applications, some standard mechanism such as [[!OAuth]] SHOULD be supported.

Authorization and Access Control

This specification does not define an authorization mechanism. Service providers SHOULD support some authorization mechanism to control access to resources and the operations that service consumers may perform on them.

Work Flow and Policy Enforcement

This specification does not define a work flow or policy enforcement mechanism. Service providers SHOULD support some mechanism to enforce work flow and policy.

Revision History and Auditing

This specification does not define a revision history or auditing mechanism. Service providers SHOULD provide support for recording the revision history of all resources including their states, the timestamp of the change, and the identity of the entity making the change.

Events and Notification

This specification does not define an event or notification mechanism. Service providers SHOULD support Atom format as a resource representation to enable change monitoring by feed readers.

The Role of RDF

This specification describes the EMS 1.0 resource data model using [[!RDF]]. Briefly, the RDF data model describes information as statements of the form (subject, predicate, object) which are often referred to as triples. The predicate of a statement either describes a relation between the subject and object resources or an attribute of the subject resource whose value is the object.

The choice of RDF for this purpose, instead of other equally valid approaches such as UML or Entity-Relationship, is motivated by the goal of aligning the data model with Web architectural principles. This use of RDF in no way implies any restriction on how EM services or clients are implemented. We expect tool developers to be able to add support for the EMS 1.0 REST API to existing tools without any need to rewrite those tools using RDF-based techologies.

This specification also defines RDF/XML representations for resources. In general, there are many equivalent ways to serialize a set of RDF triples as RDF/XML. This specification prescribes the way to serialize resources as RDF/XML so that these representations are well-formed XML and may be processed with any of the many available XML processing technologies (e.g. DOM, SAX, !StAX, XSLT, XQuery, etc.). There is no requirement to use a general RDF/XML parser.

The RDF/XML representation is used in examples. However, EM services should support other important formats such as JSON and HTML, as may support other RDF formats, e.g. [[!N3]] and [[!Turtle]].

An EM client SHOULD use standard HTTP content negotiation to indicate a preference for specific formats.

Resource Types

An EM service manages access to resources that support the estimation and measurement uses cases. The EM service manages the creation, retrieval, update, and deletion of these resources, and maintains their mutual data integrity constraints in the process of doing so.

The EMS 1.0 data model defines several resource types. The data model for each resource type and the data integrity constraints that hold among resources are defined in detail later in this specification. Each EMS 1.0 resource type is identified by a URI that begins with the following URI:

http://open-services.net/ns/ems#
      

Througout this specification, we use the prefix ems: to abbreviate this URI. For example, ems:Service is an abbreviation for the following URI:

http://open-services.net/ns/ems#Service
      

EMS 1.0 defines three kinds of resource type, namely domain entities, domain entity lists, and the service root. The domain entity resource types are ems:Project, ems:Scenario, ems:Estimate, ems:Baseline, and ems:Measurement. For each domain entity type, there is an associated list type, i.e. ems:ProjectList, ems:ScenarioList, ems:EstimateList, ems:BaselineList, and ems:MeasurementList. Finally, the ems:Service resource type represents the EM service as a whole.

An EM service contains information about a set of resources of the above types. We will use RDF to describe this information. In RDF terms, the information forms a graph. Each resource is a node in this graph and each triple is an arc in it.

The EM service graph may contain zero or more instances of each domain entity resource type. EM clients may create and delete instances using the REST API. The graph also contains exactly one instance of each associate entity list type and exactly one instance of the service root type. The list and service resources are built-in to the EM service. EM clients may not create or delete the list or service root resources.

Resource Properties

Each resource type has a set of properties which will be described in detail later in this specification. Some of these properties are automatically maintained by the EM service and may not be modified by EM clients. We refer to these as read-only properties. Some read-only properties such as creation date, creator, etc. are system properties that apply to all resources. Other read-only properties, such as list membership, are specific to a given resource type. For example, when a new domain entity resource is created, a membership property that references it is added to its associated list resource.

We refer to properties that may be directly set or modified by EM clients as read-write properties.

HTTP Methods

The REST API supports the usual HTTP methods: GET, PUT, POST, DELETE. In addition, query parameters MAY be appended to resource URLs in order to modify the response of a GET request. The syntax of these query parameters is specified in OSLC Simple Query Syntax V1.

An EM client may retrieve a representation any resource using GET and may modify its read-write properties using PUT. A representation of information about any resource, possibly including information about related resources, may be retrieved using GET with query parameters that specify the properties to include.

An EM client may create a new domain entity resource by POSTing a representation of it to its associated list resource. Any domain entity resource may be deleted using DELETE.

A domain entity list resource contains membership links to each of its associated domain entity resources. An EM client may retrieve a representation that contains a subset of these membership links, and specified properties of the referenced domain entity resources via GET with query parameters. We refer to this as “GET sublist” in the table below.

The following table summarizes the HTTP methods used in the REST API:

Resource Representation Formats

This specification defines RDF/XML representations for all resource types. An EM service MUST support RDF/XML representations. An EM service MAY support other representation formats such as JSON, XHTML, Atom, etc. An EM client SHOULD indicate a preference for specific formats using standard HTTP content negotiation.

This specification defines RDF/XML representations for all resource types. An EM service MUST support RDF/XML representations. An EM service MAY support other representation formats such as JSON, XHTML, Atom, etc. An EM client SHOULD indicate a preference for specific formats using standard HTTP content negotiation.

Distributed Computing

Any domain entity resource is either an ems:Project resource or is related to a unique ems:Project resource. For example, each ems:Scenario resource has exactly one ems:project property that links it to a unique ems:Project resource, and each ems:Estimate resource has exactly one ems:scenario property that links it to a unique ems:Scenario resource, therefore each ems:Estimate resource is related to a unique ems:Project resource. Similarly, ems:Baseline and ems:Measurement resources are related to unique ems:Project resources.

This specification defines behavior in the simple case where all domain entity resources that are related to a given ems:Project resource are managed by the same service. This is a simplifying assumption and affects how resources are discovered and baselined. For example, to find all the estimates for a given project, a query is run on the ems:EstimateList resource that is linked to the same ems:Service resource that is linked to the ems:ProjectList resource that contains the ems:Project resource. Also, when an ems:Baseline resource is created, the service automatically updates the ems:currentBaseline property of the related ems:Project resource.

While it is certainly possible to define a fully distributed REST API for coordinating queries and updates across a group of collaborating EMS service providers, doing so for a 1.0 specification would add a premature level of complexity and cost for implementers.

As more products add support for the EMS 1.0 REST API, it is anticipated that there may be more than EMS 1.0 service provider in a given deployment. An EMS 1.0 service consumer may interact with multiple EMS 1.0 service providers. This causes no difficulty as long as all the resources related to a project are created in the same service provider instance.

In order to build in an evolution path towards a fully distributed REST API, this specification will adopt that policy of specifying that resources related to a given project or intermediate resource SHOULD be created in the same service. If the project or intermediate resource is in a different service then the behavior is undefined. If there is sufficient demand for a fully distributed REST API, then a future EMS specification will define this behavior.

Introduction

The data model consists of a set of resource types and literal XML datatypes. Each resource type is described by listing and describing its properties. Each resource type and literal XML datatype is described in detail below.

Properties

Each property is described by specifying its range, its occurrence, and its edit type.

Range

The range of a property is the set of objects that may appear in statements (triples) that have the given property as their predicate. In this specification, the range of each property is either a set of resources of some RDF type, or a set of literal values that belong to some XML datatype, e.g. strings, numbers, XHTML fragments.

When the range is a resource, the value of the property is frequently a URI that is a link to the resource. In RDF/XML, the URI value is given using the rdf:resource attribute on the property element.

However, some resources do not have document URIs and are represented inline in some parent resource representation. Within an RDF/XML representation, an inline resource MAY be identified using the rdf:ID attribute on its node element, and be the object of other properties using the rdf:resource attribute on the property element. The value of the rdf:ID attribute MUST be unique within the RDF/XML representation. If the resource is local, then it does not have any URI, i.e. it is a blank node in the RDF data model. Within an RDF/XML representation, a blank node may be identified and referenced using the rdf:nodeID attribute.

The following table summarizes how resources are represented in RDF/XML:

Table of Resource Ranges

XHTML

We use [[!XHTML]] to describe formatted textual literal XML datatypes. In this specification, the prefix xhtml: is associated with the XHTML namespace URI:

http://www.w3.org/1999/xhtml

For example, the datatype xhtml:span means the XHTML content that may appear in an xhtml:span element.

XML Schema

We use XML Schema Datatypes to describe some literal XML datatypes. In this specification, the prefix xsd: is associated with the XML Schema namespace URI:

http://www.w3.org/2001/XMLSchema

Occurrence

The occurrence of a property is the number of triples that may exist for a given subject with the given property as the predicate. Properties may be either optional (may not occur) or mandatory (must occur), and may be either single-valued (at most once) or multi-valued (an unbounded number of times). We use the following terms to describe the most common occurrence constraints:

Table of Occurrence Names

Edit Type

The edit type of a property specifies how it may be directly modified by a service consumer.

Some properties may be freely modified. These are called read-write properties.

Some properties may only be modified once, e.g. at resource creation time. These are called write-once properties.

Finally, some properties may not be modified driectly because they are either generated or maintained by the EM service. These are called read-only properties. For example, creation date is a read-only property.

The following table summarizes the edit types:

Table of Edit Types

Standard Properties

Some properties are used by all resources. We refer to these as standard properties and define them here.

In the specification, the prefix rdf: stands for the Resource Description Framework (RDF) Vocabulary, which has the following namespace URI:

http://www.w3.org/1999/02/22-rdf-syntax-ns#

In the specification, the prefix rdfs: stands for the RDF Vocabulary Description Language 1.0, which has the following namespace URI:

http://www.w3.org/2000/01/rdf-schema#

In this specification, the prefix dcterms: stands for the Dublin Core Metadata Initiative (DCMI) Metadata Terms, which has the following namespace URI:

http://purl.org/dc/terms/

In this specification, the prefix foaf: stands for the Friend of a Friend (FOAF) Vocabulary, which has the following namespace URI:

http://xmlns.com/foaf/0.1/

Table of Standard Properties

{Entity} and {entity} Naming Convention

This specification uses a uniform naming convention for several resource types and properties. When the string {Entity} appears in a name it stands for one of the domain entity names, i.e. Project, Scenario, Estimate, etc. For example, ems:{Entity}List stands for ems:ProjectList, ems:ScenarioList, etc.

The string {entity} stands for a domain entity name with an initial lowercase letter. For example, ems:{entity}List stands for ems:projectList, ems:scenarioList, etc.

The Service Root

Every EMS 1.0 service has a service root resource that provides links to the domain entity list resources and some descriptive information. The service root can be neither created nor deleted. Only its descriptive properties, e.g. dcterms:title, dcterms:description, may be modified via PUT.

Service Data Model

The following topic describes the service data model:

• ems:Service - the service root

Domain Entity Lists

A domain entity list resource is associated with each domain entity type. The list resource serves two main purposes. First, it provides a way to create new domain entity resources via POST. Second, it provides a way to search for domain entity resources via GET with query parameters.

All list resources have a similar structure. In addition to the standard properties, they have the following properties:

Table of Standard ems:{Entity}List Properties

ems:service

The ems:service property links each domain entity list to its service root. The service root contains links to all of its domain entity lists. Therefore, given any domain entity list URL, a consumer can navigate from it to the service root, and from there to all the other domain entity lists.

This read-only property is automatically maintained by the service. It cannot be modified.

ems:member{Entity}

The ems:member{Entity} property is a membership property that links each domain entity list to all of its member domain entities. Each domain entities has a link back to its domain entity list. Therefore, given any domain entity URL a consumer can navigate from it to its domain entity list, and from there to all the other domain entities in the list.

This read-only property is automatically maintained by the service. When a new domain entity is POSTed to a domain entity list, the service automatically adds an ems:member{Entity} property that links to it. When the domain entity is DELETEd, the service removes the link to it.

Domain Entity List Data Models

The following topics describe the domain entity list data models:

• ems:ProjectList - project list
• ems:ScenarioList - scenario list
• ems:EstimateList - estimate list
• ems:BaselineList -baseline list
• ems:MeasurementList - measurement list

Domain Entities

A domain entity resource describes a specific project, scenario, estimate, etc.

All domain entities have the following properties:

Table of Standard ems:{Entity} Properties

dcterms:identifier

The dcterms:identifier property provides a short, human-friendly, identifer for the resource.

This identifier uniquely identifies the resource within its list.

This read-only property is automatically maintained by the service. When a new domain entity is POSTed to its list, the service assigns it a unique identifier.

ems:{entity}List

The ems:{entity}List property links each domain entity to its list.

This read-only property is automatically maintained by the service. When a new domain entity is POSTed to its list, the service adds this property to the resource.

Domain Entity Data Models

The following topics describe the domain entity data models:

• ems:Project - project
• ems:Scenario -scenario
• ems:Estimate -estimate
• ems:Baseline - baseline
• ems:Measurement -measurement

Metric Entities

A metric entity is a resource that represents some aspect of a project that can be measured or estimated. Metric entities are assumed in scenarios, predicted in estimates, and observed in measurements.

A measure is a simple metric entity that consists of a single value such as the total cost of a project.

Measures may be organized into fact tables that analyze the composition of the measures along dimensions such as time and role.

Some dimension values, such as role, may have standard values. A map resource lets you describe how custom dimension values have been mapped to standard values.

Measures and fact tables may be either definite values that result from observations, or probability distributions that occur in assumptions or predictions.

Work breakdown structures are a common project management tool to describe the work to be performed on a project, including their effort, duration, and schedule.

Metric Entity Data Models

The following topics describes the metric entity data models:

• ems:Measure - measure
• ems:MeasureDistribution - measure distribution
• ems:FactTable - fact table
• ems:FactDistributionTable -fact distribution table
• ems:Map - dimension value map
• ems:WorkBreakdownStructure - work breakdown structure

Probability Distributions

A probability distribution is a resource that defines the likelihood that a measurement of some value (a random variable) will fall within some given range. Probability distributions are used in scenario assumptions and estimate predictions.

The use of probability distributions to describe measurements of individual metrics (i,e. univariate probability distributions) is a simplification that discards information about how the individual metrics are correlated with each other. A software development project is a single, complex, entity and therefore measurements of different metrics are not in general independent.

For example, consider effort broken down by labor role. An estimate would give probability distributions for the amounts of coding and testing effort. A high measurement of coding effort and a low measurement of testing effort might both be within acceptable control limits. However, in practice we expect more code to require more testing, i.e. the coding and testing effort measurements should be correlated. Correlation information can be represented by multivariate probability distributions, however they are not currently included in the EMS 1.0 specification. If an estimate gave a multivariate probability distribution for effort by role, then a high measurement for coding combined with a low measurement for testing might fall outside the control limits and alert the project manager to a potential problem. Multivariate probability distributions therefore have potential value and should be considered in

There are several commonly occuring probability distributions, such as the triangular and normal distributions. Any probablility distribution may be approximated by its quantile function for a sufficiently large number of quantiles.

ems:ProbabilityDistribution

ems:ProbabilityDistribution denotes the abstract class of all probability distribution resources. This specification defines several concrete subclasses of probability distribution resources.

Probability Distribution Data Models

The following topics describe the probability distribution data models:

• ems:PointEstimate - point estimate
• ems:UniformDistribution - uniform distribution
• ems:TriangularDistribution - triangular distribution
• ems:NormalDistribution - normal distribution
• ems:PoissonDistribution - Poisson distribution
• ems:QuantileFunction - quantile function
• ems:CumulativeDistributionFunction -cumulative distribution function