Pluggable Web Services with SMD

By on March 19, 2008 7:11 am

We have been leading the efforts in the development of Service Mapping Description (SMD). SMD is a flexible format and can be used to describe JSON-RPC, REST, JSONP, and other web services. SMD will provide a foundation to facilitate a future of pluggable interoperable SOA-based web services, where client and server components can be decoupled. Existing client/server frameworks tend to have tightly coupled communication, and applications built with standalone JavaScript libraries like the Dojo Toolkit generally must build their own client and server communication with the only assistance in the form of Ajax wrappers. With SMD, web services can be described with an open format, and client libraries can utilize these SMD descriptions to build high-level friendly communication wrappers. Of course, the Dojo Toolkit has taken the lead with the new SMD implementations in the Dojo Toolkit 1.1, but with SMD-based web service interaction, there is no lock-in. This provides an open definition of web services: any client and server can participate in providing or consuming these web services.

We have also been working on a specification for JSON Schema which provides the definition of contractual type constraints. JSON Schema is a definition for describing a valid set of values. Defining type constraints provides a standardized form of data documentation that can be used for data persistence, form generation, and creating contracts on data used in web services. SMD uses JSON Schema to describe the acceptable values for the all the parameters and return values of the available web services. With a shared vocabulary of data type definitions, SMDs can not only define what types of services are available, but can provide meaningful expectations on the type of data that should be passed to a service and what will be returned from it. With open comprehensive service description, servers can provide web services like JSON-RPC and bi-directional REST services like that of CouchDb and Persevere. These RPC and database storage services can be effortlessly integrated with JavaScript libraries which can become first-class citizens in high-level client/server application development instead of just animation providers. And with new (in the Dojo Toolkit 1.1) and upcoming (in the Dojo Toolkit 1.2) dojo.rpc and capabilities, the Dojo Toolkit can be more than just a library—it can be a fully capable front-end for client/server application development. Web services and data storage endpoints can be exposed by servers, and with minimal effort Dojo Toolkit users can connect and utilize these services without building custom communication handlers. Let’s take a look at how we can define services with an example SMD:

{target:"/jsonrpc", // this defines the URL to connect for the services
 transport:"POST", // We will use POST as the transport
 envelope:"JSON-RPC-1.2", // We will use JSON-RPC
 services: {
   add : { // define a service to add two numbers
   parameters: [
     {name:"a",type:"number"}, // define the two parameters
 foo : {   // nothing is required to be defined, all definitions are optional.
   //This service has nothing defined so it can take any parameters 
  //and return any value
 getNews : {
   // we can redefine the target, transport, and envelope for specific services
   target: "/newsSearch",
   transport: "GET",
   envelope: "URL",
   parameters:[ { name: "query", type: "string", optional: false, default: "" } ],

This SMD provides a definition for a variety of available services, and documents what parameters are expected, how to call the services, and what to expect in return. This SMD could be published by the server, and the client could retrieve the SMD by URL:

var services = new dojox.rpc.Service("");

Or alternately the SMD can be defined inline:

var mySMD = {target:"/jsonrpc"...};
var services = new dojox.rpc.Service(mySMD);

The dojox.rpc.Service will generate a services object that maps JavaScript methods to web services. To use the services object we can simply call the methods on the object. Note that that when these methods are called they return a dojo.Deferred object so that the service can be executed asynchronously. Here is an example of calling a service mapped method and retrieving the result when it is finished:

var newsDeferred = services.getNews({query:"dojo"});
newsDeferred.addCallback(function(returnValue) {
    alert("A news item: " + returnValue[0]);

This would trigger a request to “/newService?query=dojo” to retrieve the latest news. When the response is received back from the server, the callback function would be called and a news item would be retrieved. Thus we have successfully leveraged the SMD mechanism for decoupling the action of getting the news from the transport details.

The SMD-based architecture is another great example of the Dojo Toolkit philosophy of “build with, not on”. Every layer in the Dojo Toolkit is intended to be open, comprehensible, and extensible. This means your Ajax applications can use remote communication built on manageable reusable services with SMD, rather than relying on custom or black box communication techniques. With SMD there is no lock-in to the Dojo Toolkit: the SMD services can easily be created and consumed by any agents or libraries.


  • What is/will be the support for cross-domain SMDs? I assume they would use something like JSONP?

  • Yes, we will use JSONP, although we use a special form, where the callback function will be derived directly from the name of the SMD, in order to allow for static creation of SMDs that can be accessed cross-domain.

  • Ahh, sounds great

  • I’m a new be for smd.
    I use my own ajax scripts. can i use smd in that, or is it compulsory to use dojo library for using smd

  • Pingback: SitePen Blog » RESTful JSON + Dojo Data()

  • Pingback: SitePen Blog » Dojo + jabsorb()

  • Pingback: SitePen Blog » Amazon S3 + Dojo()

  • Pingback: SitePen Blog » Client/Server Model on the Web()

  • Pingback: SitePen Blog » Protected Cross-Domain Authentication with JavaScript()

  • Abe

    I spent a lot of time trying to get an example similar to yours by supplying an SMD that used the JSON-RPC-2.0 envelope, however, I kept getting a “No match found” error. To fix this you need to dojo.require(“dojox.rpc.JsonRPC”) to register the JSON-RPC envelopes in the envelope registry. Hope this helps.

  • Pingback: SpringOne 2008 Day 4 « Incremental Operations()

  • zhaohui wang

    I,m a new be for smd, i am trying to use smd for mashup, but i have a problem, how to description this as a “service return” in a service’s smd. kann you give me some tipps?

    “title”:”Rockit Room April 20th!”,
    } , {
    “title”:”TRINDADE (RJ)”,
    “isfamily”:0} ,…

    thanks a lot.

  • 1. Silly question, what is SAO? I’ve heard of SOA, are these two different acronyms?

    So as I understand a RESTful service, any number of content types can be made available to the client, (ie. xml,json,flash,string…), and its up to the RESTful client to interpret that data. How does SMD help?

    From the example code above, it almost looks as if most of the interpretation is done on the client, and for the most part, I believe is all goodness. The first example simply looks as if you are creating a service on the client. Which seems odd to me, wouldn’t you rather create a pluggable Class architecture?

  • gabriel: It was supposed to be SOA, thanks for the correction.
    The goal of SMD is to provide a means for configuring clients to use common web service formats/transports. While dojox.rpc.Service does support pluggable transports, if a web service requires specialized client side code to work, it has failed to achieved the client server separation abstraction.

  • @Kris – thanks for the clarification, and you’re right, it makes sense as an abstract.

    I wonder if you can consider SMD an RMI for the client, as it looks as if some/most of the logic takes place there.

  • joe

    As much as I appreachiate (and use!) the great concepts in Dojo, the frustration begins, when you have to search for the “easter eggs” in the given examples.
    Having used dojo.rpc for quite a long time with the “old style” SMD-files, from the above example SMD it should have been quite easy to convert them to the new dojox.rpc standard. Needless to say, that the changed service didn’t work, and the completely cryptic Java Script error message only made clear, that something had gone wrong in creating the RPC methods.
    Only after hours of debugging and finally getting into the dojo sources, I discovered that the envelope definition
    >>>> envelope:”JSON-RPC-1.2″<<<<<
    is inconsistent with my current Dojo distribution (1.3Beta3), but has to be “JSON-RPC-1.0” or “JSON-RPC-2.0”.
    My appeal, especially to you, Kris, is to
    make your examples “complete”, i.e. testable ( whenever possible), including the dojo-version for which it is made.
    That would give dojo an immense boost among the fans and would make it easier to convince the others.

  • @joe: My apologies, we will try to do a better job of identifying version compatibility and ensuring backwards compatibility.

  • How do I add this to my RSS reader? Sorry I’m a newbie :(

  • Pingback: SitePen Blog » Unobtrusive JavaScript Typing via JSON Schema Interfaces()

  • Pingback: Dojo Confessions (Or: How I gave up my jQuery Security Blanket and Lived to Tell the Tale) |

  • Pingback: Zend_Json_Server and Dojox.rpc.Service « Flight School()

  • Json

    I can’t see why SMD would become a REST standard, because it is relying heavily on the query parameters instead of fully-flexed REST architecture. I’ve seen that the JsonRestStore also uses SMD, but I wonder about situations where the target would contain variables.

  • Pingback: SMD (Service Mapping Description) « Distigme()

  • jumpnett

    What “type”s are supported by SMD?