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>

---