History   View   Links to this page 2012 September 24 | 01:07 pm

REST API main topics: Architecture, Design, Data Model, Standard URIs

Contents

  • Occurrence
  • Edit Type
  • Standard Properties
  • {Entity} and {entity} Naming Convention
  • The Service Root
  • Domain Entity Lists
  • ems:service
  • ems:member{Entity}
  • Domain Entity List Data Models
  • Domain Entities
  • dcterms:identifier
  • ems:{entity}List
  • Domain Entity Data Models
  • Metric Entities
  • Probability Distributions

    • Status

    This document is a Draft Specification.

    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
    Range RDF/XML Representation
    resource The property element has an rdf:resource attribute that contains the URI of the resource.
    inline resource The property element contains a node element for the resource. The node element has an rdf:about or rdf:ID attribute that contains the URI of the resource.
    local resource The property element has an rdf:nodeID attribute that contains the local identifier of the resource. The local identifer MUST be defined on some node element within the representation.
    local inline resource The property element contains a node element for the resource. The node element MAY have an rdf:nodeID attribute that defines its local identifier.

    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
    Optional Mandatory
    Single-valued zero-or-one exactly-one
    Multi-valued zero-or-more one-or-more

    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
    Edit Type Description
    read-write Consumer may change value many times.
    write-once Consumer may set initial value.
    read-only Consumer may never directly change value.

    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
    Property Range Type Occurrence Edits Description
    dcterms:title datatype rdf:XMLLiteral exactly-one read-write A short title for the resource. Valid XHTML <span> element content.
    dcterms:description datatype rdf:XMLLiteral zero-or-one read-write A detailed description of the resource. Valid XHTML <div> element content.
    dcterms:creator resource foaf:Person exactly-one read-only The person who created the resource.
    dcterms:created datatype xsd:dateTime exactly-one read-only The timestamp of when the resource was created.
    dcterms:modifed datatype xsd:dateTime exactly-one read-only The timestamp of when the resource was last modified.

    {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:

    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
    Property Range Type Occurrence Edits Description
    ems:service resource ems:Service exactly-one read-only The service root that manages this list.
    ems:member{Entity} resource ems:{Entity} zero-or-more read-only A domain entity that belongs to this list.

    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:

    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
    Property Range Type Occurrence Edits Description
    dcterms:identifier datatype xsd:string exactly-one read-only The short identifier for this entity within its list.
    ems:{entity}List resource ems:{Entity}List exactly-one read-only The domain entity list that this domain entity belongs to.

    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:

    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:

    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:

    Category:Rest API main topics

    Categories