In my last blog I talked about the messaging format which will be used for the RAP protocol messages. I told you that we plan to use JSON as the message format. So, the thing is that the blog ended in a little discussion about what are the benefits of using JSON instead of XML. So, I decided to pick the biggest argument which speaks for XML and try to mitigate it

I want to talk about XML-Schema. XML-Schema is a really great benefit of XML. You can use XML-Schema to describe a XML-Message for validation. Another benefit of XML-Schema is that you can write your schema completely with XML.

When it comes to the discussion why somebody wants to use JSON instead of XML, the schema is always an argument against JSON. But this has now an end. There is a young project out there called JSON Schema. With JSON Schema you can define your message completely with JSON. For sure the JSON Schema is not so well-engineered as XML-Schema at the moment. But I think we need to give it a chance to grow. The guys behind JSON Schema are doing a great job with this technology and are working very hard to make this technology ready for productive use. There are already some implementations of JSON Schema. But enough about the theory, lets take a look at the schema for the protocol message described here:

{
  "description" : "RAP protocol message schema",
  "type" : "object",
  "properties" : {
    "meta" : {
      "description" : "Contains request sepcific information",
      "type" : "object",
      "properties" : {
        "requestCounter" : { "type" : "integer", "minimum" : 1 },
        "settingStore" : { "type" : "integer" },
        "tabId" : { "type" : "integer", "optional" : true }
      }
    },
    "device" : {
      "type" : "object",
      "description" : "Contains display specific information.",
      "optional" : true,
      "properties" : {
        "id" : { "type" : "string" },
        "cursorLocation" : {
          "type" : "array",
          "maxItems" : 2,
          "items" : { "type" : "integer" }
        },
        "focusControl" : { "type" : "string" }
      }
    },
    "widgets" : {
      "type" : "array",
      "description" : "Contains widget specific information.",
      "uniqueItems" : true,
      "minItems" : 1,
      "items" : {
        "type" : "object",
        "properties" : {
          "widgetId" : { "type" : "string", "optional" : true },
          "type" : { "type" : "string", "enum" : [
            "synchronize",
            "multiSynchronize",
            "listen",
            "construct",
            "fireEvent",
            "destroy",
            "execute",
            "executeScript" ]
          },
          "payload" : { "type" : "object" }
        }
      }
    }
  }
}

As with the message itself the most interesting part in the schema is the “widgets” property of the “message” object. It’s very important that it’s an array instead of an object because of the event order which will be send to the RAP server. So, with the JSON Schema we have the possibility to define this property as an array and we can be sure that it’s an array at runtime. Another cool thing is that we can define that all array elements has to be an object with some required properties. For example every widget array element needs a property called “type” for identifying it’s payload. The schema gives us the possibility to define allowed values for the “type” property. So, we can be sure that a message only contains allowed payloads.

I think describing the whole schema will blow up this blog. So, take a closer look at the schema by your self if you are interested and write a comment if something is not clear.

At the moment it’s not clear if we use the JSON schema for the protocol at runtime. But it’s always good to know that we have something for validation. So, let me know what do you think about the schema.

Tags: protocol, rap