This specification defines the OSLC Asset Management domain, a RESTful web services interface for the management of domain specifica and supporting resources defined in the OSLC Core specification. 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.

Introduction

This section is non-normative.

Asset management systems allow enterprises to catalog, govern, manage, search for, and maintain assets. An asset is anything tangible or intangible that provides value through reference or reuse across a wide audience over an extended period of time. Assets typically have a lifecycle and require a formal process to govern both modification and access. Cataloging assets with standardized taxonomies controls usage and discovery by end users. Assets may also have relationships to and dependencies on other assets.

The term asset in this specification generally refers to either software, documentation, or representations of equipment. While other definitions of an asset may be appropriate, financial instruments are not considered an asset in this specification.

Example software assets may include but are not limited to the final binary output from a software development process, libraries such as a Java archive (JAR) or dynamic-link library (DLL), and installable packages that are distributed through digital distribution platforms such as a repository or app store. Documentation assets may include presentation materials, reports, specifications, blue prints, and instructions. Assets may also represent any type of equipment or structure such as computer hardware, automobiles, pumps, buildings, etc.

Assets are described by a set of properties and zero or more artifacts. An artifact is a file of any type and a set of properties that describe the file.

This specification builds on the Open Services for Lifecycle Collaboration (OSLC) Core v2.0 Specification to define the resources, properties and operations supported by an OSLC Asset Management (OSLC-Asset) provider. Asset Management resources include Assets, Artifacts and supporting resources defined in the OSLC Core specification. The properties defined describe these resources and the relationships between resources. Operations are defined in terms of HTTP methods and MIME type handling. The resources, properties and operations defined do not form a comprehensive interface to Asset Management, but instead target specific integration use cases documented by the OSLC-Asset workgroup.

This specification also defines how Assets and Artifacts are represented in OSLC Services. The [[!OSLCAssetResourceDefinition]] is a set of properties for an Asset, and includes properties that describe Artifacts of an Asset.

Asset Management Resources Overview

This version of the OSLC Asset specification is demonstrated in the [[!OSLCAssetSamples]].

IPR Policy

This Committee Specification Public Review Draft is being developed under the RF on Limited Terms Mode of the OASIS IPR Policy, the mode chosen when the Technical Committee was established. For information on whether any patents have been disclosed that may be essential to implementing this specification, and any offers of patent licensing terms, please refer to the Intellectual Property Rights section of the TC’s web page ( https://www.oasis-open.org/committees/oslc-domains/ipr.php).

Terminology

Asset Consumer - A tool or user that performs asset searching and retrieval activities outlined in the search and retrieve scenarios.

Asset Resource - An Asset Resource has a set of properties representing an asset. These properties include such things as name, description, classification, and the Artifact properties for an Asset.

Asset Query Resource - When filtering using simple query, the representation of a list of Asset Resources.

Asset Submitter - A tool or user that performs asset preparation activities outlined in the publish scenario.

Artifact - This term refers to the properties that describe an Asset Artifact and potentially the Artifact Media referenced by this Artifact. An Asset may have zero or more Artifacts.

Artifact Fragment - Fragment within an Asset Resource that describes an Artifact Media Resource. The term fragment is associated with an Artifact instead of resource because Artifacts are referenced by the Asset’s URL with a fragment identifier. Artifacts are considered to be contained within the asset and when the asset is deleted the artifact is also deleted. While two different Artifacts in separate Assets may reference to the same Artifact Media Resource, two different Assets may not contain the same Artifact.

Artifact Media Resource - The Artifact Media Resource represents the actual artifact content. The content can be a presentation, a test case, a binary software component, or any other kind of file.

Property - An attribute of a resource. Typically a property is a name/value pair that describes a certain aspect of the resource. For example, an asset has many properties such as the asset title, subject/short description, version.

Service Provider - An implementation of the OSLC Asset Management specification as a server. OSLC Asset Management clients consume these services.

Work product - This term is often used interchangeably with ‘artifact’ or ‘file’. An asset may have zero or more work products.

References

Base Requirements

The following sub-sections define the mandatory and optional requirements for an OSLC Asset Management (OSLC Aseet) server.

Base Compliance

This specification is based on [[!OSLCCore3]]. OSLC Asset Management servers MUST be compliant with both the core specification, MUST follow all the mandatory requirements in the normative sections of this specification, and SHOULD follow all the guidelines and recommendations in both these specifications.

An OSLC Asset Management server MUST implement the domain vocabulary defined in OSLC Asset Management Version 2.1. Part 2: Vocabulary

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

Number Requirement Level Meaning
ASSET-1 Unknown properties and content MAY / MUST OSLC services MAY ignore unknown content and OSLC clients MUST preserve unknown content
ASSET-2 Resource Operations MUST OSLC service MUST support resource operations via standard HTTP operations
ASSET-3 Resource Paging MAY OSLC services MAY provide paging for resources but only when specifically requested by client
ASSET-4 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
ASSET-5 Partial Update MAY OSLC services MAY support partial update of resources using patch semantics and MAY support via HTTP PUT
ASSET-6 Discovery MUST / MAY / SHOULD OSLC servers MUST support OSLC Core 3.0 Discovery, MAY provide a ServiceProviderCatalog and SHOULD provide a ServiceProvider resource for Core v2 compatibility.
ASSET-6 Creation Factories MUST OSLC servers MUST provide LDPC creation factories to enable resource creation of Quality Management resources via HTTP POST
ASSET-7 Query Capabilities SHOULD OSLC servers SHOULD provide query capabilities to enable clients to query for resources
ASSET-8 Query Syntax SHOULD / MAY OSLC query capabilities SHOULD support the OSLC Core Query Syntax and MAY use other query syntax
ASSET-9 Delegated UI Dialogs MUST / SHOULD OSLC Services MUST offer delegated UI dialogs (creation and selections) specified via OSLC Core 3.0 Delegated Dialogs and SHOULD include discovery through a ServiceProvider resource for OSLC v2 compatibility
ASSET-10 UI Preview SHOULD OSLC Services SHOULD offer UI previews for resources that may be referenced by other resources specified via OSLC Core 3.0 Preview and SHOULD include discovery through a server resource for OSLC v2 compatibility
ASSET-11 HTTP Basic Authentication MAY OSLC Services MAY support Basic Auth and should do so only over HTTPS
ASSET-12 OAuth Authentication SHOULD OSLC Services SHOULD support OAuth and can indicate the required OAuth URLs via the ServiceProviderCatalog or ServiceProvider resources
ASSET-13 Error Responses SHOULD OSLC Services SHOULD provide error responses using OSLC Core 3.0 defined error formats
ASSET-14 Turtle Representations MUST OSLC services MUST provide a Turtle representation for HTTP GET requests and SHOULD support Turtle representations on POST and PUT requests.
ASSET-15 RDF/XML Representations SHOULD OSLC services SHOULD provide an RDF/XML representation for HTTP GET requests and SHOULD support RDF/XML representations on POST and PUT requests
ASSET-16 XML Representations SHOULD OSLC services SHOULD provide a XML representation for HTTP GET, POST and PUT requests that conform to the Core 2.0 Guidelines for XML.
ASSET-17 JSON Representations MUST OSLC services MUST provide JSON-LD representations for HTTP GET, POST and PUT requests that conform to the Core Guidelines for JSON-LD
ASSET-18 HTML Representations SHOULD OSLC services SHOULD provide HTML representations for HTTP GET requests

Specification Versioning

See [[!OSLCCore2]] 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 and OSLC-Asset-Version with a value of 2.1. 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. See section below on Version Compatibility with OSLC Asset 1.0 Specifications.

Namespaces

In addition to the namespace URIs and namespace prefixes oslc, rdf, dcterms and foaf defined in the [[!OSLCCore2]], OSLC Asset Management defines the namespace URI of http://open-services.net/ns/asset# with a namespace prefix of oslc_asset

Resource Formats

In addition to the requirements for [[!OSLCCore2]] Resource Formats section, this section outlines further refinements and restrictions.

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

For HTTP PUT/POST request formats for resource type of Asset:

For HTTP GET response formats for Query requests,

Asset Management Providers MUST provide RDF/XML representations, SHOULD provide JSON and Atom Syndication Format XML representations, and MAY provide XML representations.

When Asset Management Consumers request:

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

Content Negotiation

OSLC Core Guidance clearly points to RDF representations (and specifically RDF/XML) as a convention that all OSLC Provider implementations minimally provide and accept. OSLC Asset 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.

XML Representation - identified by the application/xml content type. Format representation rules are outlined in Core [[!OSLCCore2RepresentationGuidance]] 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 [[!OSLCCore2RepresentationGuidance]] Resource Formats section.

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

Authentication

See [[!OSLCCore2]] Authentication section. Asset Management puts no additional constraints on authentication.

Error Responses

See [[!OSLCCore2]] Error Responses section. Asset Management puts no additional constraints on error responses.

Pagination

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

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

Labels for Relationships

Asset relationships to other resources are represented as properties whose values are the URI of the object or target resource. When an Asset relationship property is to be presented in a user interface, it may be helpful to provide an informative and useful textual label for that relationship instance. (This in addition to the relationship property URI and the object resource URI, which are also candidates for presentation to a user.) To this end, OSLC providers MAY support a dcterms:title link property in Asset resource representations, using the anchor approach outlined in the OSLC Core Links Guidance. In addition to the textual label, the Asset resource definition defines several properties that can be used to describe the relationship from one Asset resource to another Asset resource.

RDF/XML and XML example using reified statement:

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

      <oslc_asset:Asset rdf:about="http://example.com/assets/CDFE4153-9271-5CA6-425A-4CA6BE7BD7CA/1.0">
           <dcterms:relation rdf:ID="relationship1" rdf:resource="http://example.com/assets/52C4702C-7CA2-E46E-D373-620482ECBEED/1.0"/>
      </oslc_asset:Asset>

      <rdf:Description rdf:about="#relationship1">
          <dcterms:title>Build Configuration</dcterms:title>
     </rdf:Description>
  </rdf:RDF>

Custom Properties

Asset management providers SHOULD allow consumers to define custom properties. If providers allow consumers to define custom properties, they MUST allow the consumer to optionally specify an HTTP URI for that data element, and the specified URI MUST be used in the RDF representation of all resources that contain the data element. The specified URI MAY be part of an industry standard such as DC, FOAF, or OSLC, or it MAY be defined by the user’s organization. If the URI is defined by the user’s organization, then they SHOULD make it dereferencable as per the [[!W3CBestPractices]].

If the user does not specify the optional URI, then the provider MUST use a default generated HTTP URI. The generated URI SHOULD be as human-readable as possible. One method for achieving human-readability is to apply a human-friendly name mangling algorithm to the user-defined label for the data element. The tool SHOULD make the generated URI dereferencable as per the [[!W3CBestPractices]]. The published RDF vocabulary SHOULD include any relevant descriptive information provided the user as part of the data element definition, e.g. the label and description.

Vocabulary Terms and Constraints

OSLC Asset Management Resources 2.1 Defines the vocabulary terms and constraints for OSLC Automation resources. These terms and constraints are specified according to [[!OSLCCoreVocab]].

Asset Management Service Provider Capabilities

Service Discovery and Description

OSLC Asset Management service providers MUST provide a [[!OSLCCore2]] Service Provider Resource that can be retrieved at a implementation dependent URI.

OSLC Asset Management service providers MAY provide a [[!OSLCCore2]] Service Provider Catalog Resource that can be retrieved at a implementation dependent URI.

OSLC Asset Management service providers MUST provide a oslc:serviceProvider property for their defined resources that will be the URI to a [[!OSLCCore2]] Service Provider Resource.

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

Creation Factories

OSLC Asset Management service providers MUST support [[!OSLCCore2]] Creation Factories and list them in the Service Provider Resource as defined by OSLC Core. OSLC Asset Management service providers SHOULD support [[!OSLCCore2]] Resource Shapes for Creation Factories as defined in [[!OSLCCore2]] OSLC Core Specification

Query Capabilities

OSLC Asset Management service providers MUST support the [[!OSLCCore2]] Query Capabilities as defined by OSLC Core. OSLC Asset Management service providers SHOULD support [[!OSLCCore2]] Resource Shapes for Query Capability as defined in [[!OSLCCore2]] Specification

The Query Capability MUST support these parameters:

If shape information is NOT present with the Query Capability, service providers SHOULD use these default properties to contain the result:

Delegated User Interface Dialogs

OSLC Asset Management service providers SHOULD support the selection of resources by delegated web-based user interface dialogs [[!OSLCCore2]] Delegated UIs as defined by OSLC Core.

OSLC Asset Management service providers MAY support the creation of resources by delegated web-based user interface dialogs [[!OSLCCore2]] Delegated UIs as defined by OSLC Core.

OSLC Asset Management service providers MAY support the pre-filling of creation dialogs based on the definition at [[OSLCCore2]] Delegated UIs.

The service providers supports the delegated UIs as follows:

Asset Management Resource Selection Creation
Asset SHOULD MAY

Version Compatibility

Version Compatibility with 1.0 Specifications

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

Media Types

For an Asset Resource format identification of RDF/XML and XML, the media type used for this representation SHOULD be application/rdf+xml or application/xml.

For an Asset Resource format identification of JSON, the media type used for this representation SHOULD be application/json.

Samples

(this section is informative)

See OSLC Asset Management 2.1 Samples.

Resource Shapes

(this section is informative)

See OSLC Asset Management 2.1 Appendix B: Resource Shapes

Notices and References

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 Asset Management 2.1 Specification, as described in the open-services.net Terms of Use. Details of the Covenant may be found here.

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 Asset Management Mailing List

Also the issues found with this specification and their resolution can be found at OSLC Asset Management 2.1 specification issues.

Acknowledgments

The following individuals have participated in the creation of this specification and are gratefully acknowledged:

Participants:

Fabio Ribeiro, Koneksys (Editor)
Jim Amsden, IBM (Chair)
Gray Bachelor, IBM (Chair)
Brad Sandler, IBM
Dave Johnson, IBM
Edwin Freekenhorst, Shell
Eric Bordeau, IBM
Gili Mendel, IBM; OSLC Asset Management Lead
Grant Larsen, IBM
Hari Padmanabhan, IBM
Jaimin Patel, WebLayers
John Favazza, WebLayers
Kevin Bauer, IBM
Randy Lexvold, the Emphasys Group
Ren Renganathan, Citigroup
Scott Bosworth, IBM
Sheehan Anderson, IBM
Srimanth Gunturi, IBM

Change History

Revision Date Editor Changes Made
01 07/06/2018 Fabio Ribeiro Draft OASIS format version created
02 09/08/2018 Gray Bachelor Change to V2.1 and add conformance