We use proprietary and third party's cookies to improve your experience and our services, identifying your Internet Browsing preferences on our website; develop analytic activities and display advertising based on your preferences. If you keep browsing, you accept its use. You can get more information on our Cookie Policy
Cookies Policy
FIWARE.ArchitectureDescription.Apps.Repository R3 - FIWARE Forge Wiki

FIWARE.ArchitectureDescription.Apps.Repository R3

From FIWARE Forge Wiki

Jump to: navigation, search


FIWARE WIKI editorial remark:
This page corresponds to Release 3 of FIWARE. The latest version associated to the latest Release is linked from FIWARE Architecture


  • Copyright © 2014 by SAP

Legal Notice

Please check the following FI-WARE Open Specification Legal Notice (essential patents license) to understand the rights to use this open specification. As all other FI-WARE members, SAP has chosen one of the two FI-WARE license schemes for open specifications.

To illustrate this open specification license from our SAP perspective:

  • SAP provides the specifications of this Generic Enabler available under IPR rules that allow for a exploitation and sustainable usage both in Open Source as well as proprietary, closed source products to maximize adoption.
  • This Open Specification is exploitable for proprietary 3rd party products and is exploitable for open source 3rd party products, including open source licenses that require patent pledges.
  • If the owner (SAP) of this GE spec holds a patent that is essential to create a conforming implementation of the GE spec (i.e. it is impossible to write a conforming implementation without violating the patent) then a license to that patent is deemed granted to the implementation.

Software associated to the Repository - RI is provided as open source under the BSD License. Please check the specific terms and conditions linked to this open source license at https://github.com/service-business-framework/Repository-RI/blob/master/license.txt. You can also obtain the Repository GE software using the FI-WARE Catalogue at http://catalogue.fi-ware.org/enablers/repository-sap-ri


Together with the Registry and the Marketplace, the Repository is a core enabler of the FI-WARE Business Framework. The Repository provides a consistent uniform API to access USDL service descriptions and associated media files for applications of the business framework. A service provider can use the Repository to publish the description of various aspects of the service according to a unified description language. Whereas the Repository is used to publish service descriptions (service models), the Registry is used for storing runtime information about concrete instances and their configuration settings.

USDL is used in its Linked Data version "Linked USDL". Documentation can be found at <http://linked-usdl.org/> . Information about the FI-WARE Platform is available at http://wiki.fi-ware.eu . USDL describes services on a metadata level and can refer to supplemental resources of any media type. Therefore the Repository must be able to store resources in arbitrary formats. The RDF datamodel of USDL allows to refer to entities of the service description via the resource URL. Therefore Linked-USDL is already well prepared to allow the distribution of service descriptions all over the Internet.

Target usage

The Repository is a place to store service models, especially USDL descriptions but also other models required by components of the overall delivery framework (e.g. technical models for service composition and mashup). The repository provides a common location for storage (centrally or distributed and replicated), reference and/or safety.

The use of a repository is required in order to appear at the marketplace or other tools. These tools may refer to a number of central repositories containing information relevant for interoperation of the enablers and roles within the FI-WARE platform. The repository contains published descriptions which can be utilized by any component in respect to privacy and authorization constraints imposed by the business models. Usually a repository is under control of an authority and usually is keeping track of versions, authenticity and publication dates.

User roles

  • The Provider creates services describing basic service information as well as technical information. He needs to upload and publish service descriptions on the repository in order to make them available to other components of the platform, such as the Shops/Stores, Aggregators, etc.
  • The Aggregator will use for example technical and service-level information of existing services in the Repository in order to perform a composition of a value added service or application. So for example, in order to give a valid statement about the availability of the new composed service. The availability of each contained service needs to be considered. The Aggregator also needs information about the technical interfaces of a service in order to develop code to call them correctly . Service descriptions for the newly created composite service can be uploaded and published to the repository again.
  • The Marketplace Provider enables consumers to make comparisons between services therefore needs all kind of business relevant descriptions of services, such as general descriptions, business partners, service-levels, and pricing, to be presented in the store or within the marketplace. Also technical information can be required, on a level to be able to do comparisons between services for the consumer.
  • The Channel Maker. The internet consists of various channels and heterogeneous devices for consuming information such as Web (browser), Android, iOS but also global as well as local social networking and community platforms such as Facebook, LinkedIn, MySpace, Xing, KWICK! The Channel Maker needs detailed information about the channel to ensure the proper channel creation or selection. Further a channel may require embedding or wrapping the service so it can be accessed by the user through the specific channel.
  • The Hoster requires information on service-level descriptions, deployment and hosting platform requirements to provide the necessary infrastructure needed to host applications/services in a reliable and scalable way.
  • The Gateway will use information about technical interfaces to provide data, protocol and process mediation services. The gateway also provides services for mediation towards premise systems outside of the FI-Ware platform.

Basic Concepts

Web Citizen

The Repository is relying on Web principles:

  • URI to identify resources
  • consistent URI structure based on REST style protocol
  • HTTP content negotiation to allow the client to choose the appropriate data format supporting HTML, RDF, XML, RSS, JSON, Turtle, ...
  • Human readable output format using HTML rendering ('text/html' accept header) including hyperlinked representation
  • Use of HTTP response codes including ETags (proper caching)
  • Linked Data enablement supporting RDF input and output types

Open Distributed Architecture

The Repository Open Specification has to be seen as a specification of the repository abstract functionality. There can be many technologies used to implement the functionality. Often the repository protocol is implemented on top of a Web content management system.

Also we envision a large number of repositories containing service descriptions, which also might to refer to descriptions in other repositories. Repositories can be hosted by the provider or a provider may use repository services of other platform providers. The latter might be an alternative for small sized providers, which don't want to provide an own infrastructure.

The service descriptions in a repository are typically used by different other components of the platform, such as service stores or marketplaces, by extracting information needed for the specific functionality.

Data Model

The Repository is structured into core objects, which are resources and collections. These objects constitute also the granularity of access control. Collections are containers for storing resources, which are typically used to maintain all resources belonging to a certain service description in one place.


The resources are mainly the USDL service descriptions themselves as well as complementary media files that are used within the service descriptions.


A collection is a container for collecting resources. Multiple collections can be used on the repository for various purposes. Collections can be nested and may provide versioning of the resources. Collections are used to keep all content that is locally referred from the service descriptions together in one place. For example a service description often has additional documentation, depictions and other collateral information, which can be bundled together in one collection.


Recipes are virtual containers selecting resources from different collections.

Content Negotiation

For optimal interoperability and flexible use, the repository should be able to deliver the results of an operation in multiple formats. HTTP content negotiations should be used to let the client choose an appropriate content type. Basic content types (mime-type) are

  • HTML - to deliver the results in hyper-linked HTML that can be rendered directly in a Web Browser
  • RDF - various RDF serializations for processing in applications
  • JSON - Javascript Object Notation for easy processing in a mashup environment.

Repository Architecture

The Repository GE is used by various other GEs within the FI-WARE platform. Namely Marketplace, Store, Composition Environment as well as SLA monitoring and Revenue Sharing can access repositories to retrieve detailed information about a service or application. The composition environment for example can retrieve available service offerings for composition from the Marketplace. In order to get detailed information about the respective services, the repository API is used. Finished composite services or applications in turn can be described in Linked USDL and published in a Repository. New offerings for the service can be posted to the Marketplace. Similarly the mediation GE can get details about a service to be mediated from the Repository and push back mediator proxy services for a complex mediation type, to be reused by many applications. The Repository is also used to store business models according to composite services and applications, which will be used by the business model execution environment and revenue sharing system.

Repository in the context of the Business Framework

Besides the FI-WARE platform, Future Internet applications or composite services on top of the FI-Ware platform can also use the repository as a service for their own purpose. An example of the inner architecture of the Repository is shown in the following diagram.

Example of high-level architecture of a repository implementation

The architecture shown here is only a blueprint for possible implementations of the repository and depicts the functional components, necessary to realize this functionality. There are many technology options for a concrete implementation, depending on the context and application domain and its nonfunctional requirements. Since the requirements according to repository size, workload and other parameters can be quite different, there is no obvious all-encompassing implementation solution. The implementations can span very simple ones, which provide only few extensions to a standards Web service to very sophisticated ones that utilizes enterprise content management systems (e.g. based on the "CMIS - Content Management Interoperability Services" standard).

The repository only stores and provides access to service descriptions. Since there is no common standard for versioning, and the requirement according to versioning may vary depending on the use case scenario, we do not require version control from a repository implementation, although a real implementation can provide versioning models and mechanism (e.g. using the capabilities of the underlying CMS system).

Also there is no requirement regarding consistency checking of the service descriptions in the repository. The applications themselves have to ensure that the descriptions are consistent. All clients of a repository have to cope with incomplete and inconsistent information by default. This reflects the architecture of the Web, where also no consistency commitment of the pages on different Web servers can be made. To ensure integrity additional measures have to be taken.

Technical Interfaces

Main Interactions

The Repository operation protocol is kept very simple. It basically provides operations to get and put resources, such as service descriptions and media content. Additional operations are used to structure the repository into collections of resources.

Managing Resources (mandatory)

The core functionality of a repository is to store resources and retrieve them when necessary. Further resources sometimes need to be updated and eventually deleted. The following diagram shows an example sequence of resource management operations of a repository.

Example sequence of resource management operations

The Get Resource operation can be used to retrieve a resource from the repository. This operation delivers the actual content of the resource and/or metadata about the resource, such as the media type, creator, or modification date, depending on the used technical interface. The following parameters need to be exchanged:

  • resource identifier - Resource identifier of the resource to be returned.

If only information about collections is requested, the collection identifier is used instead of the resource identifier.

  • collection identifier - Identifier for the collection, which contains the resource.
  • resource - Resource which will be returned
  • media type - Media type of the resource which will be returned.

The Put Resource operation is used to store a new resource into the repository or update an existing resource with the same resource identifier. The repository should take precautions to provide inconsistent changes due to concurrent access. The following parameters need to be exchanged:

  • resource identifier - Identifier which contains the resource.
  • collection identifier - Identifier which denotes the collection into which the resource will be put. The collection can be a part of the resource identifier, if for example URL paths are used to identify a resource.
  • resource - the content of the resource to be stored into the repository

In order to delete a resource irrevocably from the repository the Delete Resource operation is used. The following parameters are exchanged:

  • resource identifier - Resource identifier of the resource to be deleted.

Managing Collections

Collections are used to put a structure into the repository. In order to easily access parts of the repository, it allows clients to get information about the contents of individual collections.

The Create Collection operation creates a new collection in the repository, containing the necessary details such as owner, policies, and other metadata attributes. It requires the parameter:

  • description - Description of the collection to be created, which contains the location path within the repository and administrative data such as creator and access policies.

To get the details and contents of a collection the Get Collection operation is used. The collection information contains information such as owner, policies, textual descriptions, dates, versions, number of resources, and more. The level of detail of the description may depend on the authorization level of the requester. The following parameters can be involved in the operation:

  • collection identifier - Collection identifier for which a description is to be returned.
  • filter - Optional filter expression to select the properties to be filtered.
  • description - Returned collection description containing information according to the filter expression.

A collection in the repository can be deleted with the Delete Collection operation. This operation can only be successful for a requester that has the appropriate authorization. The delete operation requires the identifier of the collection as input. After this operation the collection is no longer accessible for clients. Only one parameter is necessary:

  • collection - Collection identifier for the collection to be deleted

Listing Content

The List operation lists collections and/or resources contained in the repository, which are accessible by the user. This operation usually is needed for a repository browser and maintenance tool as well as an editor tool in order to select the resource to be maintained.

The operations using the following parameters: No input parameters are required. However, for practical reasons it might be useful to restrict the list of collections and resources by specifying the number of results and the starting offset.

  • collection - Collection for which the list is restricted to.
  • index - Index of the first element of the result set to be returned.
  • limit - Maximal number of results to be returned.
  • filter - A repository implementation might also offer the possibility to filter the list of collections according to specific criteria. An optional filter expression can be used to reduce the number of delivered results. A repository may support different criteria to filter the output
  • result list - The operation results in a list of collections/resources that is returned to the client and contains resource descriptions according to the collection, filter, index, and limit expressions.

List the additional services

Besides the operations described above, a repository might provide additional services, such as search, backup, etc. A repository should list and describe the additional services to the clients when the List Services operation is invoked. If additional services are offered only for specific collections of the Repository, the collection identifier can be used to list the actual available functionalities for this collection. The required parameters for this operation are:

  • collection - Collection identifier for which the additional services will be listed.
  • result list - List of additional services are returned to the client.

Searching the Repository

A Repository might provide searching service, to search service descriptions according to the occurrence search terms in properties of the description and media content. It is desirable that in compliance to OpenSearch the repository provides an OpenSearch description to the search API.

Querying the Repository

A repository might also provide a more complex querying service in a specific query language. As an example a query service based on SPARQL [ REP2 ]would allow to execute complex queries on the Linked Data RDF model [ REP1 ].

Basic Design Principles


There are many proprietary solutions implementing repository functionality and also many standards for various types of repositories. Within FI-WARE we try to abstract this functionality into a Generic Enabler.

Implementation agnostic

The API abstracts from the concrete implementation technology. Implementations using various kinds of databases should be possible. Although the main goal is to store services descriptions in a distributed environment, any implementation of a repository can be used as long as the technical interfaces comply with the GE operation protocol and can be mapped (mediated) to the FI-Ware preferred REST-based reference implementation.


REP1 RDF Primer W3C Recommendation 10 February 2004 (http://www.w3.org/TR/2004/REC-rdf-primer-20040210/)
REP2 SPARQL 1.1 Overview, W3C Working Draft 01 May 2012 (http://www.w3.org/TR/2012/WD-sparql11-overview-20120501/9
Personal tools
Create a book