History   View   Links to this page 2013 June 20 | 09:45 am
OSLC_logo.png

Open Services for Lifecycle Collaboration
Architecture Management Specification Version 3.0

Status: WORKING DRAFT 3.0 Specification

This Version

Latest Version

PreviousVersion

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

Introduction

(this section is informative)

This specification defines a RESTful web services interface for Architecture Management (AM), the management of product design artifiacts, and models requests and relationships between those and related resources such as requirements, testing resources and change requestes. To support these scenarios, this specification defines a set of HTTP-based RESTful interfaces in terms of HTTP methods: GET, POST, PUT and DELETE, HTTP response codes, content type handling and resource formats.

The intent of this specification is to define the capabilities needed to support integration scenarios defined by the Architecture Management working group and not to provide a comprehensive interface to Architecture Management. The resource formats and operations may not match exactly the native artifacts supported by architecture management service providers but are intended to be compatible with them. The approach to supporting these scenarios is to delegate operations, as driven by service provider contributed user interfaces, as much as possible and not require a service provider to expose its complete data model and application logic.

Terminology

Architecture Management Resource (AMR) - Any design or modeling resource used as an abstract representation of all or part of an application or product under development. These include but are not limited to Unified Modeling Language (UML), Business Process Modeling Notation (BPMN), Topologym and Entity Relationship models.

Consumer - an implementation of the OSLC Architecture Management specifications as a client. OSLC AM Consumers invoke and use the services provided by service providers

Service Provider - an implementation of the OSLC Architecture Management specifications as a server. Provides AMR management services for OSLC AM clients to invoke and use.

Base Requirements

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.

The following table summarizes the requirements from OSLC Core Specification as well as some additional requirements specific to AM. Note that this specification further restricts some of the requirements for OSLC Core Specification. See further sections in this specification or the OSLC Core Specification to get further details on each of these requirements.

Requirement Level Meaning
Unknown properties and content MAY / MUST OSLC services MAY ignore unknown content and OSLC clients MUST preserve unknown content
Resource Operations MUST OSLC service MUST support resource operations via standard HTTP operations
Resource Paging MAY OSLC services MAY provide paging for resources. Clients MUST be able to process paging, which may be provided by the server whether specifically requested by client or not.
Partial Resource Representations MAY / MUST OSLC services MUST support request for a subset of a resource’s properties via the oslc.properties URL parameter retrieval via HTTP GET and MAY support via HTTP PUT
Partial Update MAY OSLC services MAY support partial update of resources using patch semantics
Service Provider Resources MAY / MUST OSLC service providers MAY provide a Service Provider Catalog and MUST provide a Service Provider resource
Creation Factories MUST OSLC service providers MUST provide creation factories to enable resource creation via HTTP POST
Query Capabilities MUST OSLC service providers MUST provide query capabilities to enable clients to query for resources
Query Syntax MUST OSLC query capabilities MUST support the OSLC Core Query Syntax and MAY use other query syntax
Delegated UI Dialogs MUST OSLC Services MUST offer delegated UI dialogs (creation and selections) specified via service provider resource
UI Preview SHOULD OSLC Services SHOULD offer UI previews for resources that may be referenced by other resources
HTTP Basic Authentication MAY OSLC Services MAY support Basic Auth and should do so only over HTTPS
OAuth Authentication SHOULD OSLC Services SHOULD support OAuth and can indicate the required OAuth URLs via the service provider resource
Error Responses MAY OSLC Services MAY provide error responses using Core defined error formats
Turtle Representations MUST OSLC services MUST provide a Turtle representations for requests. In the previous version of this specification RDF/XML was the only representation required, however in alignment with the Linked Data Base Profile recommendation is that Turtle be the favored representation.
RDF/XML Representations MAY OSLC services MAY provide an RDF/XML representation for requests. In the previous version of this specification this was required, however in alignment with the Linked Data Base Profile recommendations has been de-emphasized.
JSON Representations SHOULD OSLC services SHOULD provide JSON representations for HTTP GET, POST and PUT requests that conform to the Core Guidelines for JSON
HTML Representations SHOULD OSLC services SHOULD provide HTML representations for HTTP GET requests

Specification Versioning

NEEDS UPDATE

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 3.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 3.0. See section below on Version Compatibility with OSLC AM 2.0 Specifications.

Namespaces

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

This specification also uses these namespace prefix definitions:

  • oslc_rm : http://open-services.net/ns/rm# (Reference: OSLC RM)
  • oslc_qm : http://open-services.net/ns/qm# (Reference: OSLC QM)
  • oslc_cm : http://open-services.net/ns/cm# (Reference: OSLC CM)
  • dm : http://jazz.net/ns/dm# (Reference: Rational Design Management)

Resource Formats

NEEDS UPDATE

In addition to the requirements for OSLC Core Resource Formats section, this section outlines further refinements and restrictions.

For HTTP GET requests on all OSLC AM and OSLC Core defined resource types,

  • AM Providers MUST provide Turtle representations.
  • AM Providers SHOULD provide JSON representations.
  • AM Consumers requesting JSON SHOULD be prepared for representations that follow the guidelines outlined in the OSLC Core Representations Guidance.
  • AM Providers MAY provide RDF/XML and XML representations.
  • AM Consumers requesting RDF/XML SHOULD be prepared for any valid RDF/XML document. AM Consumers requesting XML SHOULD be prepared for representations that follow the guidelines outlined in the OSLC Core Representations Guidance.
  • AM Providers SHOULD support an [X]HTML representation and a user interface (UI) preview as defined by UI Preview Guidance

For HTTP PUT/POST request formats for resource type of !oslc_am:Resource:

  • AM Providers MUST accept Turtle representations.
  • AM Providers MAY accept RDF/XML representations. AM Providers SHOULD be prepared for any valid RDF/XML document.
  • AM Providers MAY accept JSON representations.
  • For JSON AM Providers SHOULD be prepared for representations that follow the guidelines outlined in the OSLC Core Representations Guidance.

For HTTP GET response formats for Query requests,

AM Providers MUST provide Turtle representations.

When AM Consumers request:

  • text/turtle AM Providers MUST respond with Turtle representation.
  • application/x-turtle AM Providers SHOULD respond with Turtle representation.

See Query Capabilities for additional information when Resource Shapes affect representation.

Content Negotiation

NEEDS UPDATE

OSLC Core Guidance clearly points to RDF representations as a convention that all OSLC Provider implementations minimally provide and accept. OSLC AM Provider implementations are strongly encouraged to adopt this convention. Future versions of this specification are expected to require RDF representations for all operations and relax requirements for specialized XML representations.

Turtle Representation - identified by the text/turtle or application/x-turtle content type. Format representation rules are outlined in Core OSLC Core Resource Formats section

XML Representation - identified by the application/xml content type. Format representation rules are outlined in Core OSLC Core Resource Formats section

RDF/XML Representation - identified by the application/rdf+xml content type. No additional guidance is given. The OSLC Core describes an algorithm for generating consistent formats that are used as examples only.

JSON Representation - identified by the application/json content type. Format representation rules are outlined in Core OSLC Core Resource Formats section.

Atom Syndication Format XML Representation - identified by the application/atom+xml content type. Format representation rules are outlined in Core OSLC Core Resource Formats section.

Authentication

See OSLC Core Authentication section. In addition to the OSLC Core authentication requirements, OSLC AM services providers SHOULD support OAuth.

Error Responses

See OSLC Core Error Responses section. OSLC AM puts no additional constraints on error responses.

Pagination

OSLC AM service providers SHOULD support pagination of query results and SHOULD support pagination of a single resource’s properties as defined by the OSLC Core Specification. A client may request pagination, however the service provide may provide paged results whether the client requested it or not. Client MUST be capable of accepting paged responses.

Requesting and Updating Properties

Requesting a Subset of Properties

A client MAY request a subset of a resource’s properties as well as properties from a referenced resource. In order to support this behavior a service provider SHOULD 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, 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.

If the parameter oslc.properties contains a valid resource property on the request that is not provided in the content, the server MUST set the resource’s property to a null or empty value. If the parameter oslc.properties contains an invalid resource property, then a 409 Conflict MUST be returned.

Updating Multi-Valued Properties

For multi-valued properties that contain a large number of values, it may be difficult and inefficient to add or remove property values. OSLC AM Service Providers 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

Resource AM Resource

The Architecture Management Resource is a generic resource definition used to define many kinds of AM resource types like designs and model elements. This specification does not attempt to detail how a model gets divided up into discrete model elements, each of which can be an AMR.

todo

The AMR properties are not limited to the ones defined in this specification, it is expected that resources will be multi-typed, and additional properties will be included in actual instance resources. It is recommended that any additional properties exist in their own unique namespace and not use the namespaces defined in these specifications.

  • Name: Resource
  • Type URI http://open-services.net/ns/am#Resource
Prefixed Name Occurs Read-only Value-type Representation Range Description
OSLC Core: Common Properties
oslc:shortTitle zero-or-one unspecified XMLLiteral n/a n/a 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.
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:title exactly-one unspecified XMLLiteral n/a n/a Title (reference: Dublin Core) or often a single line summary of the resource represented as rich text in XHTML content. SHOULD include only content that is valid and suitable inside an XHTML <div> element.
dcterms:identifier zero-or-one True 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:subject zero-or-many False String n/a n/a Tag or keyword for a resource. Each occurrence of a dcterms:subject property denotes an additional tag for the resource.
dcterms:creator zero-or-many unspecified Either Resource or Local Resource Either Reference or Inline any Creator or creators of resource (reference: Dublin Core). It is likely that the target resource will be a foaf:Person but that is not necessarily the case.
dcterms:contributor zero-or-many unspecified Either Resource or Local Resource Either Reference or Inline any The person(s) who are responsible for the work needed to complete the change request (reference: Dublin Core). It is likely that the target resource will be a 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).
rdf:type zero-or-many unspecified Resource Reference n/a The resource type URIs. One of at least has the value of http://open-services.net/ns/am#Resource
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.
oslc:discussedBy zero-or-one unspecified Resource Either oslc:Discussion A series of notes and comments about this change request.
Prefixed Name Occurs Read-only Value-type Representation Range Description
Dublin Core: Common relationships
dcterms:relation zero-or-many unspecified Resource Reference any A related resource. This property is the most generic type of relationship and can be used when there is no better defined property.
OSLC AM: SysML relationships
oslc_am:refines zero-or-many unspecified Resource Reference any This resource is a refinement of the referenced resource. For example, a Use Case scenario might be a refinement of a textual requirement that describes the interaction.
oslc_am:satisfies zero-or-many unspecified Resource Reference any This resource satisfies a requirement (the referenced resource). For example a UML Component satisfies a requirement to provide some type of functionality.
oslc_am:verifies zero-or-many unspecified Resource Reference any A dependency from a model element to a requirement that determines whether a system fulfills the requirement. For example a Sequence diagram verifies a requirement that describes a protocol.
Rational Design Management: Pre-defined relationships
dm:derives zero-or-many unspecified Resource Reference any The model element derives from a requirement.
dm:elaborates zero-or-many unspecified Resource Reference any The model element elaborates a change request.

Resource: Diagram

A Diagram is a graphical representation of a resource. It often includes references/representations of other AM Resources.

  • Name: Diagram
  • Type URI http://open-services.net/ns/am#Diagram
Prefixed Name Occurs Read-only Value-type Representation Range Description
dcterms:title exactly-one unspecified XMLLiteral n/a n/a Name of diagram (OSLC Common property)
dcterms:description zero-or-one unspecified XMLLiteral n/a n/a A short description of the diagram. (OSLC Common property)
oslc_am:area zero-or-many unspecified Either Resource or Local Resource Either Reference or Inline oslc_am:DiagramRectangle oslc_am:DiagramPolygon Areas in the diagram. May represent another resource internal or external (another resource managed by another server). May just represent some component of the diagram (i.e. legend, boundary, etc.)

Resource: Diagram Rectangle

A Diagram Rectangle is a simple rectangular visual element in a diagram. It may represent another resource, or it could be just an element in the diagram like a legend, or logo image.

  • Name: DiagramRectangle
  • Type URI http://open-services.net/ns/am#DiagramRectangle
Prefixed Name Occurs Read-only Value-type Representation Range Description
dcterms:title zero-or-one unspecified XMLLiteral n/a n/a A label that identifies the view, or what the view represents. (OSLC Common property)
oslc_am:represents zero-or-one unspecified Resource Reference any The uri of the resource that this view represents
oslc_am:x exactly-one unspecified integer n/a n/a The horizontal coordinate of the upper left hand corner of the area.
oslc_am:y exactly-one unspecified integer n/a n/a The vertical coordinate of the upper left hand corner of the area.
oslc_am:width exactly-one unspecified integer n/a n/a The width of the area.
oslc_am:height exactly-one unspecified integer n/a n/a The height of the area.
oslc_am:order zero-or-one unspecified integer n/a n/a The relative z-order that this area is compared to other areas. Lower values place this area under areas with higher values

Resource: Diagram Polygon

A Diagram Polygon is an irregularly shaped area in a diagram. It may represent another resource, or it could be just an element in the diagram. It is expressed as a sequence of points that represent the line segments that make up the polygon. It is expected that the first and last points are the same, and that the series of points forms a polygon where the line segments do not overlap.

  • Name: DiagramPolygon
  • Type URI http://open-services.net/ns/am#DiagramPolygon
Prefixed Name Occurs Read-only Value-type Representation Range Description
dcterms:title zero-or-one unspecified XMLLiteral n/a n/a A label that identifies the view, or what the view represents. (OSLC Common property)
oslc_am:represents zero-or-one unspecified Resource Reference any The uri of the resource that this view represents
oslc_am:coords exactly-one unspecified String n/a n/a A comma separated list of integers that represent the coordinates of the vertices of a polygon in the form of: x1,y1,x2,y2,..,xn,yn. If the first and last coordinate pairs are not the same, the client will add the last coordinate pair to close the polygon. See [ coords attribute of HTML <map> element][2]
oslc_am:order zero-or-one unspecified integer n/a n/a The relative z-order that this area is compared to other areas. Lower values place this area under areas with higher values

AM Service Provider Capabilities

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 MAY 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.

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

Creation Factories

OSLC AM service providers MAY support Creation Factories and list them in the Service Provider Resource as defined by OSLC Core. OSLC AM service providers MAY support Resource Shapes for Creation Factories as defined in OSLC Core Specification

Query Capabilities

OSLC AM service providers SHOULD support the Query Capabilities as defined by OSLC Core. OSLC AM service providers SHOULD support Resource Shapes for Query Capability as defined in OSLC Core Specification

If Query services are provided the Query Capability MUST support these parameters:

  • oslc.where
  • oslc.prefix

If shape information is NOT present with the Query Capability, service providers SHOULD use these default properties to contain the result: * For RDF/XML and XML, use rdf:Description and rdfs:member as defined in OSLC Core RDF/XML Examples

Delegated UIs

OSLC AM service providers MUST 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.

Usage Identifiers

OSLC AM service provider can 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 will be used to designate the default or primary service to be used by consumers when multiple entries are found.

The additional property values for oslc:usage are:

TODO

Version Compatibility with 2.0 Specifications

TODO

The goal is to provide a smooth transition to 3.0 for both Consumers and Providers. This section will clarify the usage of 2.0 media types so that Providers can support both 2.0 and 3.0 Consumers when HTTP requests are made for a resource with the same URI.

Network addressable resource URIs used for 2.0 resources for these types: !oslc_am:Resource, !ServiceDescriptor and !ServiceProviderCatalog, should not have to change. Consumers who support both 1.0 and 2.0, should only preserve these resource URIs. When a Provider starts to serve 2.0 resource formats, for instance the !ServiceProvider resource, it is recommended to update its locally stored or cached information about the contents of the !ServiceProvider resource as the URIs to various capabilities may have changed (query, delegated UIs, factories, etc).

Media Types

Representation Media Types
Turtle ‘text/turtle’ or ‘application/x-turtle’
JSON ‘application/json’
RDF/XML ‘application/rdf+xml’

Appendix A: Samples

(this section is informative)

See Specification 3.0 Samples

Appendix B: Resource Shapes

(this section is informative)

See Specification 3.0 Shapes

Appendix C: Notices and References

Contributors

TODO

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 Specification 3.0 issues

Intellectual Property Covenant

NEEDS UPDATE

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