SMEX-D

SMEX stands for Simple Message Exchange, and SMEX-D for SMEX Descriptor, an XML language designed to provide simple descriptions of a wide range of Web-Service message exchanges, both REST-based and SOAP-based.

A SMEX is a pair of messages sent between two systems referred to as the client and server. The first message, from client to server, is called the request; the second, from server to client, the response. A SMEX might represent a complete transaction in the RPC style, or one step in an extended conversation between client and server, or between multiple co-operating computers.

Amazon.com Example · Here is a SMEX-D instance describing an Amazon.com ItemSearch transaction.

A SMEX-D Instance · In this discussion, the acronym “NSX” stands for “Non-SOAP XML”, i.e. an XML document whose root element is not in the SOAP namespace.

A SMEX request may take one of three forms:

1. Name-value pairs.

2. An NSX message.

3. A SOAP message.

A SMEX response may take one of three forms:

1. No reply, in which case the “exchange” is a one-way message transmission consisting only of the request.

2. An NSX message.

3. A SOAP message.

The namespace for SMEX-D is http://smex-d.net/ns/. All elements in a SMEX instance are in the SMEX-D namespace, and all attributes are in no namespace, unless otherwise specified.

A SMEX-D instance’s root element is <smex-d>. The <smex-d> element must have two child elements, <request> and <response>.

The <smex-d> element may have an update attribute whose value must be one of true or false. The default value of update is false.

update="false" asserts that this message exchange operation is “safe and idempotent” as the terms are defined in HTTP 1.1; true means that there is no assertion of safety or idempotence.

<smex-d> must have an href attribute, whose value must be a URI to which the SMEX request is to be sent.

The request Element · <request> must have a form attribute whose value must be one of pairs, soap, or nsx.

The request message is transmitted from client to server via HTTP, using either the POST or GET verb. If the containing <smex-d> element has update="true", or the request form is nsx or soap, then the client must use the HTTP POST verb. otherwise, it should use GET.

The response Element · <response> must have a form attribute whose value must be one of soap, nsx, or none. The last value means that there is no response expected to the request.

The response message is transmitted from the server to the client as an HTTP response to the request message.

Name-Value Pairs · <request> elements with form="pairs" have zero or more child <pair> elements. Each <pair> element must have a name attribute whose value must be a Name, in XML terms. <pair> may have a child <enum> element, which, if provided, contains one or more <v> elements containing the allowed values.

If there is no <enum>, the values are constrained using the type attribute, whose value is a string identifying one of the 19 primitive datatypes from XML Schema section 3.2. The default value is string.

Here is an example of such a <request> element:

 <request form="pairs">
  <pair name="user" />
  <pair name="max-weight" type="decimal" />
  <pair name="rgb"><enum><v>R</v><v>G</v><v>B</v></enum></pair>
 </request>

A request in pairs form is to be transmitted from the client to the server using the usual URL-encoding techniques for GET and name-value pairs for POST.

The language Element · This element is used to describe the language used in an NSX message, or in a SOAP message’s header or body, by specifying either its namespace or one or more schemas, or both. <language> may have a namespace attribute, whose value must be an XML Namespace Name identifying the language used in the NSX message.

It may also contain contain one or more <schema> elements, each identifying a schema that constrains the message.

A <schema> element must have a flavor attribute, whose value must be one or more of relaxng, xsd, or schematron. If omitted, the default value is relaxng.

<schema> may also have a root attribute, whose value must be a Name, in XML terms, giving the required root element.

<schema> must have an href attribute whose value is a URI for the schema.

<language> must have either a namespace attribute or at least one child <schema> element.

An example of <language>:

 <language namespace="http://example.com/ns/invoices">
  <schema root="simple-invoice" href="http://example.com/schemas/invoice" />
 </language>

Defining NSX Messages · <request> and <response> elements with form="nsx" specify that the request or response takes the form of an XML document whose root is not in the SOAP namespace. Such elements must contain a single <language> element which describes the language in the message.

An example of an NSX <request> element:

 <request form="nsx">
  <language namespace="http://example.com/ns/invoices" />
 </request>

Defining SOAP Messages · <request> and <response> elements with form="soap" specify that the request or response is an XML document whose infoset is a SOAP 1.2 Message. Such an element must contain two children, <header> and <body>. Each of these children must contain one or more <language> elements which describe the elements that may appear as top-level children of the SOAP header and body.

An example of a SOAP <response> element:

 <response form="soap">
  <header>
   <language namespace="http://schemas.xmlsoap.org/ws/2004/08/addressing" />
   <language>
    <schema href="http://example.com/schemas/query" />
   </language>
  </header>
  <body>
   <language>
    <schema href="http://example.com/schemas/invoice" />
   </language>
  </body>
 </response>

---