Canonical schema pattern

The interaction between services often requires exchanging business documents. In order for a service consumer to send data (related to a particular business entity e.g. a purchase order), it needs to know the structure of the data i.e. the data model. For this, the service provider publishes the structure of the data that it expects within the incoming message from the service consumer. In case of services being implemented as web services,[4] this would be the XML schema document. Once the service consumer knows the required data model, it can structure the data accordingly. However, under some conditions it may be possible that the service consumer already possesses the required data, which relates to a particular business document, but the data does not conform to the data model as specified by the service provider. This disparity among the data models results in the requirement of data model transformation so that the message is transformed into the required structure as dictated by the service provider. Building upon the aforementioned example, it is entirely possible that, after processing the received business document, the service provider sends back the processed document to the service consumer that once again performs the data model transformation to convert the processed business document back to the data model that it uses within its logic to represent the business document.
This runtime data model transformation adds processing overhead and complicates the design of service compositions.[5] In order to avoid the need for data model transformation, the Canonical Schema pattern dictates the use of standardized data models for those business documents that are commonly processed by the services in a service inventory.[6][7]

Diagram A
Service A is using a different data model as compared to Service B for the same business document. When messages are exchanged, runtime data model transformation needs to be performed.

Diagram B
Both services are using the same data model for representing a particular business document. As a result, no data model transformation is required when messages are exchanged.

This design pattern is fully supported by the application of the Standardized Service Contract design principle. The Standardized Service Contract design principle advocates that the service contracts be based on standardized data models. This is achieved by performing an analysis of the service inventory blueprint[8] in order to find out the commonly occurring business documents that are exchanged between services. These business documents are then modeled in a standardized manner. For example, in case of web services, the business documents are modeled as XML schemas. Once a standardized data representation layer exists in a service inventory, different service contracts can make use of the same data models if they need to exchange the same business documents. This eliminates the need for any data model transformation and reduces the processing overhead associated with the data model transformation. It also increases the reusability potential of a service as now the service can be consumed without requiring any custom data model transformation logic. In a way, the application of the Canonical Schema pattern reduces the need for the application of the Data Model Transformation[9] design pattern.

The application of this design pattern requires design standards[10] in place that make the use of standardized data models mandatory, as the mere creation of data models does not guarantee their use.[11] Although simple in principle but difficult to enforce as it needs commitment from different project teams which may entail extra efforts, on part of each team, in terms of designing solutions that accommodate standardized data models.
On some occasions, either because of the sheer size of the organization or because of the resistance from different segments of the enterprise, the Canonical Schema design pattern may need to be applied within a particular domain inventory, created by the application of the Domain Inventory design pattern.[7]
The schemas need to be designed separately than the service contract design so that there is no dependency between them.[11]

• Canonical model

• Erl et al., (2009).SOA Design Patterns. Prentice Hall. ISBN 0-13-613516-1.
• Thomas Erl (2008).SOA Principles of Service Design. Prentice Hall. ISBN 0-13-234482-3.

• SOA Concepts
• SOA Terms Glossary
• SOA Design Patterns