History   View   Links to this page 2012 September 10 | 10:21 am

Status: 2.0 Specification - August 4, 2011

This Version

Latest Version

Authors

Contributors

Table of Contents

Contents

License

Creative Commons Attribution License
This work is licensed under a Creative Commons Attribution License.

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 RFC-2119. This document is a mixture of normative and informative text. See the the glossary below for definitions of these terms.

Overview

(this section is informative)

The general approach taken by the Architecture Management (AM) workgroup follows the OSLC Change Management team’s lead by not attempting to re-define model storage formats or even model or other architecture management resource notations, but rather extract out a least common denominator, that could be managed by an AM server, and still be useful to the overall goal of architecture management in a collaborative ALM environment. This does not prevent knowledgeable clients from getting and making use of internal resource content.

The AM resource properties are not limited to the ones defined in this specification. It is recommended to contribute resource properties in their own unique namespace. Service providers MUST NOT reuse or re-define properties or terms defined in this specification.

This specification is a OSLC Core 2.0 compliant specification, as such most of its content are references to the Core 2.0 specification.

Terminology

Resource - An artifact used in the ALM space. A resource is directly addressable with an absolute URL.

Architecture Management Resource (AMR) - Directly addressable resources of some domain/notation (i.e. UML, BMPN, ER) that represent an abstraction of some behavior or construct of a system under development. An AMR maintains its identity after refactoring. In the semantic web, an AMR might correspond to a graph that is an instance of some vocabulary or micro-theory.

Link - A logical relationship from one resource to another resource. An OSLC AM Link is uni-directional. The subject (source) of a link represents the resource that ‘knows about’ and is referencing another resource (target). The type of relationship is given by a predicate URI (link type). In semantic web terminology, a link would correspond to an RDF statement with a subject (source) a predicate (type) and object (target). The predicate could be defined by property in an RDF schema.

Link Type (LT) - A URI that represents the type of a link. In semantic web terminology it is the predicate of an RDF triple. It clarifies the type of relationship between two resources. Link Type URIs may be defined locally, within the OSLC, or externaly (i.e. Dublin Core terms). Link types could be defined in RDF Schemas.

Link Type Resource (LTR) - A resource that contains human consumable information about a Link Type, like its human readable name and description. The resource is managed by the AM provider. The information may be about a Link Type in a different domain (i.e. Dublin Core Terms or OWL). The main use of a LTR is for clients who want to build a UI for users that clearly labels potential link types.

Service Provider - An implementation of the OSLC Architecture Management specifications as a server. OSLC AM clients consume these service.

Service Description Resource - an informational resource describing the capabilities and contextual configuration needed for a set of Architecture Management-specific services.

Service Description Document - the representation of a Architecture Management Services Resource.

Base Requirements

The following is a summary of OSLC AM Service Provider Requirements.

Requirement Level Comment
Service provider resource MUST Service providers MUST provide a service provider resource (http://open-services.net/ns/core#ServiceProvider) for clients to discover service endpoints.
Absolute URIs MUST Service providers MUST use absolute URIs for all references to resources by properties.
RDF/XML format MUST Service providers MUST provide RDF/XML representations for all resources. Service providers MUST accept valid GET requests with application/rdf+xml Accept headers.
HTTP REST services MUST Service providers MUST provide standard HTTP based REST services using standard HTTP responses for resource access.
HTTP If-Match use MUST If service providers support update and delete of resources MUST support the standard HTTP If-Match header in PUT and DELETE for concurency protection of resources.
Resource Query Capability MUST Service providers MUST support a query interface for oslc_am:Resource resources.
Authentication SHOULD Service providers SHOULD provide at least one OSLC Core recognized form of authentication (Basic, Form, or OAuth).
Link Type Query Capability SHOULD Service providers SHOULD support a query interface for oslc_am:LinkType resources that support a GET for all link type resources. Such a GET does not require any simple query syntax parameters. Service providers MAY support the full query syntax for Link Type resources.
Delegated selection UI SHOULD Service providers SHOULD support the OSLC Core 2.0 Delegated UI specification for resource selection of oslc_am:Resource resources.
Error format SHOULD Service providers SHOULD support the OSLC Core 2.0 common error response format.
Paging of queries SHOULD Service providers SHOULD support paging of query results.
HTTP resource PUT/DELETE SHOULD Service providers SHOULD support resource modifications with standard HTTP PUT and DELETE methods. Service providers MAY limit modifications in any way they want.
Service provider catalog MAY Service providers MAY organize services they provide on a context or project basis and use the OSLC define catalog resource to organize them.
Creation Factory MAY Service providers MAY provide creation factories for resource formats that it supports. Service providers MAY support creation factories for OSLC AM defined resources formatted as application/rdf+xml. Service providers MAY support creation factories for other formats, and will indicate such with a non-default identifier in the oslc:usage property of the creation factory definition in the service provider document.
Ignore unknown content MAY Service providers MAY ignore unkown content, including link types that have not been registered with the server. Providers MAY discard such properties and continue the POST or PUT operation without warning to the client.
Partial update MAY Service providers MAY support partial updates of resources.
Paging of resource properties MAY Service providers MAY page the results of a GET on a AM resource that contains a large number of properties.
Selective properties MAY Service providers MAY support selective properties on resource GET calls.
Delegated creation UI MAY Service providers MAY support the OSLC Core 2.0 Delegated UI specification for resource creation.
Basic authentication MAY Service providers MAY support standard HTTP Basic authentication.
Oauth authentication MAY Service providers MAY support OAuth authentication.
Form authentication MAY Service providers MAY support standard HTTP Form based authentication.

The following is a summary of OSLC AM Client Requirements

Requirement Level Comment
Unknown properties and content MUST OSLC AM Clients MUST preserve unknown content when PUTing updates to resources.

Compliance

This specification is based on OSLC Core Specification. OSLC AM consumers and service providers MUST be compliant with both the core specification and this AM specification, and SHOULD follow all the guidelines and recommendations in both these specifications.

Specification Versioning

See OSLC Core Specification Versioning section.

Service providers that support the resource formats and services in this specification MUST use HTTP response header of OSLC-Core-Version with a value of 2.0. Consumers MAY request formats and services defined in this document by providing a HTTP request header of OSLC-Core-Version with a value of 2.0.

Namespaces

In addition to the namespace URIs and namespace prefixes oslc, rdf, dcterms and foaf defined in the OSLC Core specification, this specification defines the namespace URI http://open-services.net/ns/am# with a namespace prefix of oslc_am.

Resource Formats

OSLC AM service providers MUST provide and accept RDF/XML formats in accordance with OSLC Core Resource Formats.

Resource Operations

OSLC AM clients MUST include the OSLC Core Version header (OSLC-Core-Version: 2.0) in all HTTP request to OSLC AM service providers.

OSLC AM service providers MUST support HTTP GET requests on Architecture Management Resources (AMR), with an Accept header of application/rdf+xml, and return the RDF/XML representation of the resource.

OSLC AM service providers SHOULD support HTTP GET requests on Architecture Management Resources (AMR), with an Accept header of an HTML type ( application/html, application/xhtml), and return either an HTML/XHTML representation of the resource or redirect the client to another URL that can (i.e. 302 Redirect).

OSLC AM service providers SHOULD support HTTP GET requests for user interface (UI) preview of Architecture Management Resources (AMR) as defined by UI Preview Guidance. (see Delegated UIs).

OSLC AM Service providers SHOULD support resource modifications on Architecture Management Resources (AMR) with standard HTTP PUT and DELETE methods. Service providers MAY limit modifications in any way they want. For example a service provider may limit updates to resources to simple link properties of link types already defined in the provider. Modification methods SHOULD use the If-Match header for concurency management. Providers MAY discard such properties and continue a PUT operation without warning to the client.

OSLC AM Service providers SHOULD support resource modifications on Link Type Resources (LTR) with standard HTTP PUT and DELETE methods. Service providers MAY limit modifications in any way they want. For example a service provider may not support additional properties. Modification methods SHOULD use the If-Match header for concurency management.

Authentication

See OSLC Core Authentication section. OSLC AM puts no additional constraints on authentication.

Error Responses

See OSLC Core Partial Update. OSLC AM puts no additional constraints on error responses.

Pagination

OSLC AM service providers SHOULD support pagination of query results and MAY support pagination of a single resource’s properties as defined by the OSLC Core Specification.

Requesting and Updating Properties

Requesting a Subset of Properties

A service provider MAY support the oslc.properties 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, then all resource properties MUST be provided in the response.

Updating a Subset of Properties

A client MAY request that a subset of a resource’s properties be updated by identifying those properties to be modified using the oslc.properties URL parameter on a HTTP PUT request.

Updating Multi-Valued Properties

A service provider MAY provide support for a partial update of the multi-valued properties as defined by OSLC Core Partial Update.

AM Resource Definitions

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

There are two OSLC AM defined resources; Architecture Management Resource and Link Type Resource. OSLC AM defines a least common set of properties for resources, however service implementations are free to extend this set of properties. Clients MUST preserve properties it does not recognize when updating resources. Service providers MAY ignore properties that it does not recognize. Additional properties may come from existing vocabularies (ie. Dublin Core, OWL). When additional properties do not come from a known vocabulary, it is recommended that they exist in their own unique namespace, and providers SHOULD NOT reuse namespaces defined in these specifications.

All RDF/XML resources that include links with annotations MUST begin with an outer <rdf:RDF> element. This outer XML element is required to support the ability to include annotations on ‘link’ properties with additional <rdf:Description> elements reifying statements about the link.

Service implementations and clients MUST be prepared to accept any form of valid RDF/XML. For example the following two resource forms are equivalent.

<rdf:RDF 
   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
   xmlns:oslc="http://open-services.net/ns/core#"
   xmlns:oslc_am="http://open-services.net/ns/am#"
   xmlns:dcterms="http://purl.org/dc/terms/">

    <oslc_am:Resource rdf:about="https://acme.com/resources/res1">
      <dcterms:title>Service Interface</dcterms:title>
      <dcterms:identifier>res1</dcterms:identifier>
      <oslc:serviceProvider rdf:resource="http://open-services.net/ns/am#"/>
    </oslc_am:Resource>

</rdf:RDF></verbatim> is equivalent to <verbatim><rdf:RDF 
   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
   xmlns:oslc="http://open-services.net/ns/core#"
   xmlns:dcterms="http://purl.org/dc/terms/">

    <rdf:Description rdf:about="https://acme.com/resources/res1">
      <dcterms:title>Service Interface</dcterms:title>
      <dcterms:identifier>res1</dcterms:identifier>
      <rdf:type rdf:resource="http://open-services.net/ns/am#Resource" />
      <oslc:serviceProvider rdf:resource="http://open-services.net/ns/am#"/>
    </rdf:Description>

</rdf:RDF>

Resource: Architecture Management Resource (AMR)

An Architecture Management Resource (AMR) is a generic resource format that can be used to represent any type of specific architecture resource like a UML Class, Use Case, or Business Process Diagram. Links from AMR resources are managed in accordance with the OSLC Core Guidance on Links and Relationships. They appear as simple properties in the resource. Links MAY include inlined values for the target and MAY include properties on the link itself. Service providers SHOULD support Link Type Resources for clients to get a list of known and acceptable link properties.

  • Name: Resource
  • Type URI http://open-services.net/ns/am#Resource
Prefixed Name Occurs Read-only Value-type Representation Range Description
dcterms:title exactly-one unspecified XMLLiteral n/a n/a Title (reference: Dublin Core) of the resource represented as rich text in XHTML content. 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.
rdf:type zero-or-many unspecified Resource Reference n/a The resource type URIs. If the resource is not in the form where the XML element defines the rdf:type of the resource (i.e. uses rdf:Description instead of oslc_am:Resource) then a rdf:type element with a value of http://open-services.net/ns/am#Resource is required to type the resource.
dcterms:identifier exactly-one unspecified String n/a n/a A unique identifier for a resource. Assigned by the service provider when a resource is created. Not intended for end-user display.
dcterms:description zero-or-one unspecified XMLLiteral n/a n/a 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.
dcterms:type zero-or-many unspecified String n/a n/a A short string representation for the type, example ‘Defect’.
dcterms:source zero-or-one unspecified Resource Reference any The resource URI a client can perform a get on to obtain the original non-OSLC AM formatted resource that was used to create this resource. The source resource is usually a binary or proprietary format that the service provider can consume and convert into an OSLC AM format. The service may use content negotiation with the Accept header to obtain the desired content type.
dcterms:creator zero-or-many unspecified Resource Either any Creator or creators of resource (reference: Dublin Core). It is likely that the target resource will be an foaf:Person but that is not necessarily the case.
dcterms:contributor zero-or-many unspecified Resource Either any Constributor or contributors of resource (reference: Dublin Core). It is likely that the target resource will be an foaf:Person but that is not necessarily the case.
dcterms:created zero-or-one True DateTime n/a n/a Timestamp of resource creation (reference: Dublin Core).
dcterms:modified zero-or-one True DateTime n/a n/a Timestamp last latest resource modification (reference: Dublin Core).
oslc:serviceProvider zero-or-many unspecified Resource Reference oslc:ServiceProvider The scope of a resource is a URI for the resource’s OSLC Service Provider.
oslc:instanceShape zero-or-one unspecified Resource Reference oslc:ResourceShape Resource Shape that provides hints as to resource property value-types and allowed values.

A Link Type Resource (LTR) represents type of link that is or can be used when defining links from AM resources. The type has an ID (expressed as a string), whose universally accepted semantics may be defined elsewhere. This resource represents the definition as it is used by this service provider. This resource is meant as a convenience for clients to get a list of known/registered link types with human readable labels and definitions that can be used in client user interfaces when links are being created.

The resource defines the properties rdfs:label and rdfs:comments for the link type URI. The link type URI is made type: http://open-services.net/ns/am#LinkType via an rdf:type property. The remaining properties may be properties of the link type URI, or on a separate resource managed by the service provider. In the case where the service provider owns the domain of the link type URI these can be the same, and all properties can be on the same link type URI.

  • Name: LinkType
  • Type URI http://open-services.net/ns/am#LinkType
Prefixed Name Occurs Read-only Value-type Representation Range Description
rdfs:label exactly-one unspecified String n/a n/a The human readable name for this link type. This value is expected to be used in drop down lists and in tables where a link of this type is involved.
rdfs:comment zero-or-one unspecified String n/a n/a Descriptive text about link type. Provides a description of this link type that could be used in hover help or other areas of the UI where the user wants to understand more about what a link of this type means.
dcterms:identifier exactly-one unspecified String n/a n/a A unique identifier for a resource. Assigned by the service provider when a resource is created. Not intended for end-user display.
dcterms:creator zero-or-many unspecified Resource Either any Creator or creators of resource (reference: Dublin Core). It is likely that the target resource will be an foaf:Person but that is not necessarily the case.
dcterms:contributor zero-or-many unspecified Resource Either any Constributor or contributors of resource (reference: Dublin Core). It is likely that the target resource will be an foaf:Person but that is not necessarily the case.
dcterms:created zero-or-one True DateTime n/a n/a Timestamp of resource creation (reference: Dublin Core).
dcterms:modified zero-or-one True DateTime n/a n/a Timestamp last latest resource modification (reference: Dublin Core).
oslc:serviceProvider zero-or-many unspecified Resource Reference oslc:ServiceProvider The scope of a resource is a URI for the resource’s OSLC Service Provider.
oslc:instanceShape zero-or-one unspecified Resource Reference oslc:ResourceShape Resource Shape that provides hints as to resource property value-types and allowed values.

AM Service Provider Capabilities

Resource Shapes

OSLC AM services providers SHOULD support Resource Shapes as defined in OSLC Core Specification

Service Provider Resources

OSLC AM service providers MUST provide a Service Provider Resource that can be retrieved at a implementation dependent URI.

OSLC AM service providers MUST provide a Service Provider Catalog Resource that can be retrieved at a implementation dependent URI.

OSLC AM service providers MUST provide a oslc:serviceProvider property for their defined resources that will be the URI to a Service Provider Resource. This does not prevent service providers from providing multiple servie provider properties with different values, if the service provider supports multiple OSLC domain specifications, and the resource is applicable to multiple domains.

OSLC AM service providers MUST supply a value of http://open-services.net/ns/am# for the property oslc:domain on either oslc:ServiceProvider or oslc:ServiceProviderCatalog resources.

Creation Factories

OSLC AM service providers MAY support Creation Factories as defined by OSLC Core.

OSLC AM service Providers MAY discard properties it does not recognize and continue the POST operation without warning to the client. The returned resource will contain the accepted properties (and server generated properties like the dcterms:identifer) so clients will be able to confirm if required what was accepted.

If OSLC AM service providers support the creation of resources from the OSLC defined oslc_am:Resource format, there MUST be at least one Creation Factory entry in the Services definition, and its oslc:usage property MUST be set to http://open-services/ns/core#default. The oslc:resourceType MUST be set to http://open-services.net/ns/am#Resource.

If OSLC AM service providers support the creation of resources from a resource other than oslc_am:Resource, there MUST be a separate creation services definition whose oslc:usage property MUST NOT be set to http://open-services/ns/core#default.

Query Capabilities

OSLC AM service providers SHOULD support the Query Capabilities as defined by OSLC Core for both oslc_am:Resource and oslc_am:LinkType resources.

If the service provider supports query capability for oslc_am:Resource resources, it MUST support the following query parameters:

  • oslc.where
  • oslc.searchTerms

OSLC AM service providers SHOULD support query capability for oslc_am:LinkType resources. If supported then service providers MUST support a simple GET without any simple query parameters that returns all link type resources. Service providers SHOULD support the full simple query syntax.

Delegated UIs

OSLC AM service providers SHOULD support the selection of resources by delegated web-based user interface dialogs Delegated UIs as defined by OSLC Core.

OSLC AM service providers MAY support the creation of resources by delegated web-based user interface dialogs Delegated UIs as defined by OSLC Core.

In oslc:Dialog elements, the two optional child elements; oslc:hintWidth and oslc:hintHeight specify the suggested size of the dialog or frame to render the HTML content in. Expected for the size values are defined by CSS length units.

Appendix A: Samples

See OSLC Architecture Management 2.0 Appendix A: Samples

Appendix B: Resource Shapes

See OSLC Architecture Management Specification Version 2.0 Appendix B: Resource Shapes

Appendix C: Notices and References

Authors and Contact Information

Reporting Issues on the Specification

The working group participants who author and maintain this working draft specification, monitor a distribution list where issues or questions can be raised, see Architecture Management Mailing List

Also the issues found with this specification and their resolution can be found at OSLC Architecture Management v2.0 Specification Issues.

Intellectual Property Covenant

The members of the Working Group (or as appropriate, their employers) have documented a Patent Non-Assertion Covenant for implementations of the AM 2.0 Specification, as described in the open-services.net Terms of Use. Details of the Covenant may be found here.

References