Architecture Management - AM Resource Format

1.0 SPECIFICATION

Introduction

The general approach taken by the Architecture Management team follows the 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 resource format is XML. Extensions MUST NOT invalidate the document structure.

This specification makes use of RDF principles and concepts. While the resource format is strictly speaking not RDF nor RDF/XML it does use RDF terms and concepts.

Namespaces

XML namespace abbreviations used in this specification:

• rdf - RDF XML namespace - http://www.w3.org/1999/02/22-rdf-syntax-ns#
• dcterms - The Dublin Core Metadata Terms namespace - http://purl.org/dc/terms/
• foaf - Friend of a Friend namespace - http://xmlns.com/foaf/0.1/

Representation

The media type used for this representation SHOULD be application/rdf+xml.

The resource MUST be an XML document with the root element <rdf:RDF>.

The resource MUST include at least one <rdf:Description> and the rdf:about attribute MUST specify the absolute URI of the architecture resource.

The following table describes the RDF properties whose meaning is defined by this specification:

Service provides MAY support write. If the service provider does not support write or updating of AM resourcs through this API, then an appropriate status code is returned.

The creator and modified properties can be specified with a foaf:Person element. Clients that want to parse and use creator / modified properties SHOULD be prepared to parse any valid foaf:Person construct.

In general, service providers SHOULD be consistent in their use of foaf:Person elements. Only the elements returned in this resource can be expected to be referenceable in simple queries. This means that if a service provider returns the following properties for creator:

<dcterms:creator>
   <foaf:Person>
      <foaf:name>Dan Designer</foaf:name>
      <foaf:mbox rdf:resource="mailto:dan@acme.com" />
   </foaf:Person>
</dcterms:creator>

the following simple query MAY not work:

http://example.com/resources?oslc.where=dcterms:creator{foaf:givenName="Dan" and foaf:familyName="Designer"}

only the properties returned in this resource can be referenced in a simple query where clause, and there SHOULD be no expectation that the service provider

Additional Properties

Service providers MAY provide additional information or properties within the resource. These MUST be valid XML constructs.

Properties MAY be any valid XML element, and MAY have child elements.

Service providers MAY reject any modification or creation of properties for any reason, including but not limited to user permission and resource integrity.

Resource links, or references to other resources SHOULD appear as additional properties, and SHOULD include the rdf:resource attribute to specify the target (or object) of the relationship. Properties MAY be associated with the resource link itself, and if present will appear in a separate rdf:Description whos rdf:about attribute specifies the rdf:ID attribute of the link. (See guidance on managing links)

Examples

Example 1. Only Required properties returned

In this example on the required properties are returned.

<?xml version="1.0" encoding="UTF-8"?>
<rdf:RDF 
   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
   xmlns:dcterms="http://purl.org/dc/terms/">

    <rdf:Description rdf:about="https://acme.com/resources/res1">
      <dcterms:title>ServiceInterface</dc:title>
      <dcterms:identifier>res1</dc:identifier>
      <rdf:type rdf:resource="http://www.eclipse.org/uml2/3.0.0/UML/Interface" />
    </rdf:Description> 

</rdf:RDF>

Example 2. All optional properties returned

In this example all optional properties are returned. Creator and modifier values are specified with the FOAF vocabulary and include a URI.

Additional properties are specified, two of which reference an external URI.

<?xml version="1.0" encoding="UTF-8"?>
<rdf:RDF 
   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
   xmlns:dcterms="http://purl.org/dc/terms/"
   xmlns:foaf="http://xmlns.com/foaf/0.1/" 
   xmlns:acme="http://acme.com/">

    <rdf:Description rdf:about="https://acme.com/resources/res1">
      <dcterms:title>ServiceInterface</dcterms:title>
      <dcterms:identifier>res1</dcterms:identifier>
      <dcterms:description>This may come from the model element's documentation properties.</dcterms:description>
      <rdf:type rdf:resource="http://www.eclipse.org/uml2/3.0.0/UML/Interface" />
      <dcterms:source rdf:resource="https://acme.com/resources/source/res1"/>
   
      <dcterms:created rdf:datatype="http://www.w3.org/2001/XMLSchema#dateTime">2009-10-20T19:49:47-04:00</dcterms:created>
      <dcterms:creator>
        <foaf:Person>
           <foaf:name>Dan Designer</foaf:name>
           <foaf:mbox rdf:resource="mailto:dan@acme.com" />
           <foaf:img rdf:resource="https://acme.com/users/photo/dan" />
        </foaf:Person>
      </dcterms:creator>
   
      <dcterms:modified rdf:datatype="http://www.w3.org/2001/XMLSchema#dateTime">2009-11-03T08:53:00-04:00</dcterms:modified>
      <dcterms:contributor>
         <foaf:Person>
            <foaf:name>Ana Analyst</foaf:name>
            <foaf:mbox rdf:resource="mailto:ana@acme.com" />
            <foaf:img rdf:resource="https://acme.com/users/photo/ana" />
         </foaf:Person>
      </dcterms:contributor>

      <!-- Other properties not defined by the OSLC specification.  These include 
           relationships to other resources (links) -->

      <acme:accountCode>CUST123</acme:accountCode>

      <acme:elaborates rdf:resource="https://req.acme.com/reqs/req1"/>

      <dcterms:license rdf:ID="id1" rdf:resource="http://open-services.net/html/Terms.html"/>

    </rdf:Description>

    <rdf:Description rdf:about="#id1">
         <acme:status>reviewed</acme:status>
         <dcterms:description>This resource is subject to the terms in this document.</dcterms:description>
    </rdf:Description>

</rdf:RDF> 

Example 3. All Simple optional properties returned

In this example all optional properties are returned. Creator and modifier values are specified as simple strings.

<?xml version="1.0" encoding="UTF-8"?>
<rdf:RDF 
   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
   xmlns:dcterms="http://purl.org/dc/terms/">

    <rdf:Description rdf:about="https://acme.com/resources/res1">

       <dcterms:title>ServiceInterface Diagram</dcterms:title>
       <dcterms:identifier>res1</dcterms:identifier>
       <dcterms:description>This may come from the model element's documentation properties.</dcterms:description>

       <rdf:type rdf:resource="http://www.eclipse.org/uml2/3.0.0/UML/SequenceDiagram" />
       <dcterms:source rdf:resource="https://acme.com/resources/source/res1"/>
   
       <dcterms:created rdf:datatype="http://www.w3.org/2001/XMLSchema#dateTime">2009-10-20T19:49:47-04:00</dcterms:created>
       <dcterms:creator>Dan Developer</dc:creator>
   
       <dcterms:modified rdf:datatype="http://www.w3.org/2001/XMLSchema#dateTime">2009-11-03T08:53:00-04:00</dcterms:modified>
       <dcterms:contributor>Ana Analyst</dc:contributor>

       <acme:accountCode>CUST123</acme:accountCode>

    </rdf:Description>

</rdf:RDF> 

Back to Architecture Management Resource Definitions