Architecture, APIs, and content


Content series:

This content is part # of 3 in the series: Introducing IBM WebSphere Service Registry and Repository, Part 2

Stay tuned for additional content in this series.

This content is part of the series:Introducing IBM WebSphere Service Registry and Repository, Part 2

Stay tuned for additional content in this series.

IBM® WebSphere® Service Registry and Repository (hereafter called Registry and Repository) is the master metadata repository for service interaction endpoint descriptions. As the integration point for service metadata, Registry and Repository establishes a central point for finding and managing service metadata. Once service metadata is placed in Registry and Repository, visibility is controlled, versions are managed, proposed changes are analyzed and communicated, and usage is monitored.

In the first article, you explored Registry and Repository concepts and capabilities and the role of Registry and Repository throughout the service-oriented architecture (SOA) life cycle. This article provides an overview of Registry and Repository architecture and technical details that help you take advantage of Registry and Repository capabilities for advertising, finding services, managing and governing services.

How WebSphere Service Registry and Repository architecture components work together

Let's begin with a brief overview of how all the key building blocks fit together within the WebSphere Service Registry and Repository architecture (see Figure 2). WebSphere Service Registry and Repository is a Java™ 2 Platform Enterprise Edition (J2EE) application that runs on a WebSphere Application Server and uses a relational database as a backing store for service metadata persistence. You can use J2EE Stateless Session Beans or a Web service to interact with Registry and Repository programmatically, and you can use a Registry and Repository Web application or a WebSphere Service Registry and Repository Eclipse plug-in to interact with service metadata in Registry and Repository through a user interface.

Registry and Repository contains service metadata artifacts that are in the form of XML documents, concepts that represent service metadata entities that are not backed by a document in Registry and Repository, semantic metadata assigned to these service metadata artifacts and entities, and relationships among and between the artifacts and entities. You can use the programming and user interfaces to perform basic Create, Retrieve, Update, and Delete (CRUD) operations on the content, and flexible queries based on XPATH expressions against the content.

Registry and Repository also offers a number of governance capabilities that you can use to manage and govern your service metadata. Part 3 of this series focuses on WebSphere Service Registry and Repository governance model and capabilities.

The following sections describe the key elements of WebSphere Service Registry and Repository architecture that will be covered in this article:

  • Registry and Repository components describe the architectural elements that support registry and repository functions.
  • WebSphere Service Registry and Repository content model explains the information that you can place into and retrieve from WebSphere Service Registry and Repository.
  • WebSphere Service Registry and Repository interfaces discuss the programmatic and user interfaces that you can use to interact with WebSphere Service Registry and Repository. Part 3 of this article series explains this topic in detail.
Figure 1. WebSphere Service Registry and Repository architecture
WebSphere Service Registry and Repository architecture
WebSphere Service Registry and Repository architecture

Registry and Repository components

This section walks you through the major components of WebSphere Service Registry and Repository architecture to help you understand how you can interact with Registry and Repository, and extend its capabilities using the customized extension points.

Registry and Repository architecture consists of several core components that together allow Registry and Repository to respond to the scenarios that are outlined in Part 1 of this series, A day in the life of WebSphere Service Registry and Repository in the SOA life cycle.

Registry and Repository is a WebSphere J2EE application. As such, it takes advantage of the role-based access control provided by WebSphere Application Server. When Registry and Repository is deployed as an enterprise-wide application in your environment, it is recommended that security be turned on. This enables role-based views and access control, and this is tied to many of Registry and Repository governance capabilities.

Registry and Repository uses a relational database as its backing store. You can put any XML document into Registry and Repository, but there are some types that are special, such as WSDL and XSD. These special types are modeled, and when one of these special types of document is loaded into Registry and Repository, it is shredded into a finer-grained content model.

WebSphere Service Registry and Repository core. The WebSphere Service Registry and Repository core offers both Registry and Repository capabilities for service metadata. The repository allows users to store, manage and query service metadata artifacts holding service descriptions (WSDL, XSD, WS-Policy, SCDL or XML documents). It not only takes good care of the documents containing service metadata, but it also provides a fine-grained representation of the content of those documents (for example, ports and portTypes in WSDL documents). And it provides registry functions for decorating registered service declarations and elements of the derived content models with user-defined properties, relationships, and classifiers. The Registry and Repository core provides a rich query interface that makes use of those decorations when you want to find a service endpoint or service interface.

Whenever a change to registry or repository content is detected by Registry and Repository, it invokes all validation and notification plug-ins that are registered. Both kinds of plug-ins are considered extension mechanisms that you can use to customize how you want Registry and Repository to react to changes. You can write and register validation functions that Registry and Repository will execute when changes are made to the content. For example, you can write and register a validation function that checks for completeness of a service definition. You can also write and register notification functions to communicate changes to the content of the repository. Registry and Repository comes with an out-of-the-box JMS notification plug-in. Registry and Repository has a subscription capability that allows your users to register their interest in consuming notifications.

Governance functions. Registry and Repository supports a rich set of extensible governance functions, including the ability to model your own service life cycle model for governed entities, define valid transitions between service states, write and plug-in validators to guard the transitions between states, and designate (notification) actions to be taken as result of the transition. It also provides interfaces to analyze the impact of changes to Registry and Repository content, and provides auditing of such changes. The governance model of the WebSphere Service Registry and Repository are explained in depth in Part 3 of this series.

Classifications. Classifications play a major role in many interactions with Registry and Repository. They allow you to annotate service descriptions and parts of service definitions with your corporate vocabulary. They are used by Registry and Repository to capture the governance state. You can use them to segregate service endpoints that are deployed in different environments. Registry and Repository classification systems are captured in OWL documents that you load into Registry and Repository using the administrative interface. You can then classify Registry and Repository entities with values from these classification systems, which allows you to perform classification-based queries, and restrict access based on classification.

Access control model. In addition to the role-based access control provided by the WebSphere Application Server, Registry and Repository supports a fine-grained access control model that allows you to define which user roles can perform specific types of actions on corresponding artifacts. You can capture Access Control Rules in XACML and reference life cycle states and semantic annotations such as classifications, and properties. This allows you to restrict visibility of services by business area or to restrict which user roles can transition services to certain life cycle states. Part 3 of this series explains the fine-grained access control model in more detail.

Registry and Repository administration interfaces. These interfaces support the import and export of Registry and Repository content for exchange with other Registry and Repository repositories and provide a JMX-based API for Registry and Repository configuration and basic administration. These support interactions with the Access Control model and with the Classification Systems.

Programming Interfaces. You can use Java and SOAP APIs to interact programmatically with Registry and Repository. These APIs provide basic CRUD operations, governance operations, and a flexible query capability based on XPath. You can use a SOAP API to communicate content using XML data structures or a Java API to communicate content using SDO data graphs.

User Interfaces. Two user interfaces are provided that enable you to interact with Registry and Repository. A servlet-based Web User Interface (UI) supports is the main way for your users representing different roles to interact with Registry and Repository. This UI supports look-up and publish scenarios, metadata management and analysis scenarios, and functions that support SOA governance. Your developer roles can work with Registry and Repository using an Eclipse plug-in that supports look-up, retrieval, and publishing of service metadata from your Eclipse-based development tools or management consoles (see Figure 2 above).

WebSphere Service Registry and Repository content model

This section provides a rather informal description of the WebSphere Service Registry and Repository content model. For a complete description, see the WebSphere Service Registry and Repository Programming Model in the WebSphere Service Registry and Repository product documentation of the IBM Knowledge Center.

The content model has entities representing service description artifacts and service description metadata. All WebSphere Service Registry and Repository content elements have a WebSphere Service Registry and Repository-assigned URI, a name and a description.

Figure 2. Service Registry and Repository content
Service Registry and Repository content
Service Registry and Repository content

Service description entities

There are three kinds of Service Description Entities that are stored and managed in Registry and Repository. Physical Documents are XML documents that are known as service metadata artifacts. Logical derivations are the finer-grained pieces of content that result when some types of physical document are shredded as they are loaded into Registry and Repository. Concepts are generic entities that are usually typed, and represent anything that is not represented by a document in Registry and Repository. You can interact with all three types of service description entities, using them in queries, applying service annotations, and establishing relationships from and to them.

Physical documents

Let's start with the most elemental building blocks for the WebSphere Service Registry and Repository content model: service metadata artifact documents (Physical Documents), such as XSD or WSDL files. These service metadata documents are stored and managed in Registry and Repository. We refer to the coarse-grained model made up from registry objects that represents those documents as the physical model. Documents are versionable objects in the Registry and Repository content model, which basically means that in addition to a URI, name, and description, they also have a version property.

You can store any XML service metadata artifact type in Service Registry and Repository and receive the benefits of broader visibility, reuse, management, and governance.

Logical derivations

Registry and Repository offers advanced functions for a number of well-known SOA metadata types. These key Registry and Repository metadata document types are: WSDL, XSD, WS-Policy, and SCDL. For these document types, Registry and Repository provides special services, including "shredding" of the documents upon receipt into Logical Derivations or a set of Logical Objects to enable users to explore Registry and Repository content beyond the boundaries of the files stored. Logical objects are not versionable.

For the key document types, Registry and Repository also defines a few predefined properties and makes an effort to detect relationships to other key documents, and where available, records those relationships in the content model. An XSDDocument, for example, has a targetNamespace property and the relationships importedXSDs, redefinedXSDs and includedXSDs. When an entry for a key-type document is created in Registry and Repository, it is introspected for relationships to other key-type artifacts. If not already represented in Registry and Repository, these related artifacts are also added, and in either case the relationship between the artifacts is recorded.

The set of logical derivations comprises the logical model of Service Registry and Repository. The logical model has entities such as portType, port, and message related to WSDL files, and complexType or simpleType related to XSD documents. Elements of the logical model have properties and relationships reflecting a subset of their characteristics as defined in the underlying document. For example, a WSDLService element has a namespace property and a relationship to the ports it contains. It is important to note that all individual results of document shredding are aggregated into one logical model that represents not only the content of individual documents, but also relationships between content in different documents.

Registry and Repository stores other types of service metadata using the XML Document, a generic document type. Documents of type XMLDocument are not decomposed into the logical model.


There is one other kind of entity in Registry and Repository, loosely referred to as a Concept in the figure above. Registry and Repository uses a concept to represent anything that does not have a physical document in Registry and Repository. You can use concepts to represent a reference to content in some other metadata repository, such as a portlet in a portlet catalogue or an asset in an asset repository. It can also be used to group physical artifacts together to govern them as a unit; for example, concepts can be versioned.

Service description metadata

In addition to content directly related to service metadata documents, Registry and Repository supports a number of metadata types that you can use used to decorate the service description entities to explain their semantics. We refer to those metadata as service semantic metadata.

Registry and Repository supports three types of service semantic metadata types: Properties, Relationships and Classifiers. You can use all three types to decorate entities in the physical or logical model, and concepts as well.

You can use service semantic metadata to:

  • Associate a property "businessValue" with a physical model entity representing a WSDL file.
  • Define a new relationship "makesUseOf" between an entity in the logical model representing a "portType" and an entity in the physical model representing an XML document.
  • Create a classifier "importantThings" and associate it with a "port" entity in the logical model and with an entity in the physical model representing a "Policy" document. This enables semantic queries to target individual elements of the service metadata, and meaningful dependency analyses to take place prior to making changes.


Properties are simple name/value pairs that are associated with any of the Service Description Entities. Some properties are assigned by the system, such as the unique id, the owner, and the last time the service entity was changed. These system-assigned properties cannot be changed. Others are derived through the "shredding" of a key-type service description document into its logical model. Properties of this type include name and namespace. Sometimes you are allowed to change these system-assigned values. You can also create your own properties. These are referred to as user-defined properties. You can use user-defined properties as a simple, unstructured and untyped extension mechanism. Properties can be used in queries, and can be used to establish fine-grained access control.


Relationships tie together one source service description entity to one or more target service description entities. Every relationship is given a name. A source is only allowed to have a single relationship with a given name. Some relationships are assigned by Registry and Repository during the "shredding" of key types of documents. The relationship established between XSD documents based on the importing of one into the other is one such system-assigned relationship. You can also define your own relationships. For example, you can:

  • Relate a Concept that represents an external object to a service using a user defined relationship.
  • Relate all of the service description documents that will be governed as a unit to a governable entity.
  • Relate a monitoring policy to a service endpoint.


You can load classification systems into Registry and Repository where they can then be used to apply semantic meaning to Service Description Entities. Classification systems are documents encoded using the Web Ontology Language (OWL). While any valid OWL document can be used as a Classification system, at this point in time Registry and Repository exploits only a small subset of the expressiveness of OWL. Registry and Repository represents OWL Classes as classifiers and interprets the subTypeOf relationship between those Classes as establishing a classifier hierarchy. Other OWL concepts such as data or relationship representing properties or other built-in OWL relationships are ignored.

A classification system is imported into Registry and Repository as a whole and can not be modified via Registry and Repository functions. Updates are done by importing a modified version of the ontology. Any Class in the underlying ontology can be used as a classifier; the same classifier can be used to classify multiple entities and an entity can be associated with multiple classifiers.

In summary, you can use user-defined properties and relationships to customize the set of predefined properties and relationships provided in the Registry and Repository meta-model. You can add properties to a WSDLDocument or configure a Concept with properties and relationships to represent its structure. To simplify the process of customizing Registry and Repository entities, a simple "template" mechanism is provided that allows you to create an XML schema that captures the definition of properties and relationships associated with a Concept entity of a particular type. You can then associate the template with the entity type. All interactions with entities of that type will then be "patterned" to match the template, designating the properties and relationships that are relevant when interacting with that kind of entity.

WebSphere Service Registry and Repository interfaces

You can use the programmatic and user interfaces that Registry and Repository provides to interact with and manage its content. In this section, you will learn about these interfaces so that you can find and retrieve service metadata from Registry and Repository, discern relationships between services, save service descriptions, and govern services as they go through their life cycle.

CRUD operations

Using WebSphere Service Registry and Repository interfaces, you can create, retrieve, update and delete documents and concepts managed by Registry and Repository. You cannot modify entities in the logical model. You can only change these by updating the document that contains the logical entity. Concepts can be created, retrieved and deleted. You can also change all semantic decorations on all entity types.

Query interface

You can interact with the Registry and Repository query interface in two ways. You can use one of the predefined queries that are configured via parameters (for example, all WSDL documents with classifier X); and you can write your own XPath-based query.

When you use the XPath-based query interface, you create an XPath expression that identifies the type of managed entity to be returned and a filter that captures the managed elements related to the desired object. Extensions are provided for you to include classification annotations in a query. For example, if you are looking for all WSDLServices that have a port that refers to a binding that refers to a portType named "StockQuotePortType", you use the following query expression:


Validation functions

Registry and Repository allows you to register validation functions that are run when basic CRUD operations are executed against its content, and also in the context of the governance model. Validation functions must not have side-effect and must return a Boolean result that can be used to veto the update.

Event notification

Registry and Repository provides basic event notification features to allow exploiters to register their interest in any changes to Registry and Repository content. Initially notification will be based on JMS publication of events. These events identify the type of the change and contain a pointer to the object that was changed.

Registry and Repository provides some predefined content for both validation and notification, . Examples can include an e-mail notification feature that allows users to request an e-mail to be sent when an interesting event happens or a WS-I compliance checker that can be used in validation scenarios.

Supported APIs

IBM supports two flavors of APIs that you can use to interact with Registry and Repository: a Java-based API and a SOAP-based API. Both support publishing (creating and updating) service metadata artifacts and metadata associated with those artifacts, retrieving service metadata artifacts, deleting the artifacts and their metadata, and querying the content of the Registry and Repository.

The programming APIs use Service Data Objects (SDO) to capture the data graphs inherent in the content model, allowing access to physical documents, logical parts of the physical documents, and concepts. The SOAP API uses XML documents to similarly represent Service Data Objects to communicate content structures in both the physical and logical model.

You can use XPath expressions in the Query API to perform searches for coarse- and fine-grained queries. Queries can be performed using semantic annotations, properties, and all or parts of physical service metadata artifacts. You can request that fragments of metadata be returned (such as endpoints), all metadata be returned, and both metadata and documents be returned. In addition to "free-form" XPath-based queries, a set of pre-canned queries are available for you to use to address common paths through the Registry and Repository content model.

The Governance API lets you analyze the impact of changes to specific artifacts. A set of predefined impact queries is available to help you navigate through the Registry and Repository content according to popular patterns, such as which WSDL files import or use this XSD. In addition you can use Governance operations to request life cycle transitions for a governed entity as well as the configuration of e-mail notifications for users interested in specific content changes.

Registry and Repository also provides a JMX-based Administration API that supports basic configuration and loading and managing of metadata in support of repository content, such as classification and life cycle management. The Administration API allows you to load definitions of state machines to be used to model the life cycle of governed entities, and to load classification systems described in OWL. In addition, the Administration API support registration of plug-ins for Validation functions or additional Notification providers. As explained earlier, Validation functions can be used to control basic CRUD operations as well as in the context of life-cycle state transitions for governed entities.

Registry and Repository ships a default notification handler that publishes change events on a JMS topic. The event specifies the type of event (create, update, delete or transform), the artifact impacted (identified via its URI) and a few more bits of information about the artifact. To avoid violating access control rules, the actual content of the artifact in question is not shipped with the event and must be retrieved separately.


A simple Audit capability is provided that logs information about Registry and Repository updates.

User Interfaces

Two user interfaces are provided to access Registry and Repository. The main interface is a Web application deployed with the Registry and Repository runtime. This supports all of your user roles, offering lookup, browse, retrieve, publish, and annotate capabilities, as well as governance activities, such as import/export and impact analysis. A subset of this user interface is offered as an Eclipse plug-in to meet the needs of your developer and analyst users that use Eclipse based-tooling. The Eclipse plug-in is used primarily for lookup, browse, retrieve and publish capabilities. The Web-based user interface is also used for performing service metadata management and governance.

The Web interface supports customizable views of the Registry and Repository content represented to a user. A set of user interface definition files describes the content and layout of the various components that make up the Web interface. The concept of user-role-specific perspectives is supported. Registry and Repository comes with a set of predefined perspectives for the most common user roles, but you can customize the predefined ones or introduce new, role-specific perspectives.


This article provided an architectural overview of Registry and Repository and its capabilities. You learned about the architectural components and how they relate in allowing service metadata to be advertised, found, retrieved, managed, and governed. You learned about the entity and metadata types that comprise Registry and Repository content model. An overview of the interfaces offered by Registry and Repository will allow you to interact with its content programmatically and use a user interface. Part 3 of this series focuses on the governance capabilities available in Registry and Repository.


Special thanks to the following for their contributions in shaping the WebSphere Service Registry and Repository architecture: Raymond Ellis, Andrew Hately, Ed Kahan, and Dan Wolfson.

Downloadable resources

Related topics


Sign in or register to add and subscribe to comments.

ArticleTitle=Introducing IBM WebSphere Service Registry and Repository, Part 2: Architecture, APIs, and content