SMODL Description

Copyright © 2005-2010 RUnit Software AS

Table of Contents

Introduction
SMODL types
Built-in types
User-defined struct types
Array types
SMODL XML
<arg>
<doc>
<field>
<maxExclusive>
<maxInclusive>
<maxLength>
<method>
<minExclusive>
<minInclusive>
<minLength>
<pattern>
<result>
<service>
<struct>
<typedef>
Typed elements
Elements for type constraints
name attribute
type attribute
nullable attribute
Examples
Constraints for int type
Constraints for float type
Constraints for double type
Constraints for long type
Constraints for string type

Introduction

SMODL or Simple MethOd Definition Language is an XML-dialect to define a service as a collection of methods. A method is defined by a set of method arguments and a method return value. The possible type values for method arguments and the method result can be either a built-in type, a user-defined structured type or an array type.

Example 1. Calculator service

<?xml version="1.0" encoding="UTF-8"?>
<service name="SimpleCalculator" targetNamespace="http://localhost/calculator"
         xmlns="http://smodl.org/v1">
<doc>Simple calculator service to perform basic arithmetic operations.</doc>

<method name="Add">
  <doc>Calculate the sum of 2 items.</doc>
  <arg name="item1" type="float"/>
  <arg name="item2" type="float"/>
  <result type="float"/>
</method>

<method name="Negate">
  <doc>Negate the value.</doc>
  <arg name="value" type="float"/>
  <result type="float"/>
</method>

<method name="Multiply">
  <doc>Calculate sum of 2  factors.</doc>
  <arg name="factor1" type="float"/>
  <arg name="factor2" type="float"/>
  <result type="float"/>
</method>

<method name="Inverse">
  <doc>Calculate the inversion of the value.</doc>
  <arg name="value" type="float"/>
  <result type="float"/>
</method>

</service>

SMODL types

The set of possible data types used in SMODL is divided into 3 categories: built-in types, user-defined structs and arrays.

Built-in types

Built-in types are listed in the following table in a comparison with corresponding types from the XML Schema.

Table 1. SMODL built-in type

Type nameDescriptionXML Schema type
binaryarbitrary binary dataxsd:base64Binary
boolboolean type that has two values, true and falsexsd:base64Binary
dateTimea particular moment in timexsd:dateTime
doubleIEEE double-precision 64-bit floating point typexsd:double
floatIEEE single-precision 32-bit floating point typexsd:float
int32-bit integer typexsd:int
long64-bit integer typexsd:long
stringarbitrary character stringxsd:string

User-defined struct types

A user-defined structured type or struct represents in SMODL a collection of named fields where each field represents a value of a particular type.

Array types

Arrays in SMODL are uniformly typed. That is, each element of a SMODL array must represent a value of the same element type.

SMODL XML

All SMODL XML elements belong to http://smodl.org/v1 namespace. The root element of the SMODL service specification is the service element.

In the following description of SMODL XML elements all attributes are required unless explicitly specified as optional.

<arg>

Specifies the name and the type of an argument of a SMODL method.

Attributes

name

Name of the argument. For a particular method, all arguments names must be unique and must satisfy restrictions on name attribute.

type

Type of the argument. See type attribute.

Child elements

See common structure of typed elements.

Notes

All arguments of a SMODL method are required. If you need to declare a method that accepts optional data, then use a struct with nullable fields for that.

<doc>

Specifies the semantic or provides other documentation of a particular SMODL element.

Attributes

None

Child elements

doc can only contain a plain text as a child.

Notes

All elements in SMODL besides doc itself can include this element. If present, doc must be the first child of its parent.

<field>

Specifies the name and the type of a field in a struct instance.

Attributes

name

Name of the field. For a particular struct, all fields names must be unique and and must satisfy restrictions on name attribute.

type

Type of the field. See type attribute.

nullable

See nullable attribute.

Child elements

See common structure of typed elements.

<maxExclusive>

See constraints and maxExclusive constraint.

<maxInclusive>

See constraints and maxInclusive constraint.

<maxLength>

See constraints and maxLength constraint.

<method>

Specifies a method of a SMODL service as a sequence of method arguments and a method result. Each service must define at least one method.

Attributes

name

Name of the method. For a particular service, all methods names must be unique and must satisfy restrictions on name attribute.

Child elements

method ::=

  • Sequence of

    • Zero or one of doc element

    • Zero or more of arg elements

    • One result element

<minExclusive>

See constraints and minExclusive constraint.

<minInclusive>

See constraints and minInclusive constraint.

<minLength>

See constraints and minLength constraint.

<pattern>

See constraints and pattern constraint.

<result>

Specifies the result of a method call in a SMODL service.

Attributes

type

Type of a method return value. See type attribute.

nullable

See nullable attribute.

Child elements

See common structure of typed elements.

Notes

All methods in SMODL return a result. If you need to declare a method that does not generate any result, use bool type for the method return value and set it to always return true.

<service>

The root element of SMODL that specifies a service as a collection of methods, struct types and type.

Attributes

name

Name of the service. This attribute value must satisfy restrictions on name attribute.

targetNamespace

Target namespace of the service. Must be a URI.

Child elements

service ::=

  • Sequence of

    • Zero or one of doc element

    • Interleave of

<struct>

Specifies a struct of a SMODL service, a complex type representing collection of typed fields.

Attributes

name

Name of the struct. For a particular service, all structs names must be unique and must satisfy restrictions on name attribute.

base

Optional name of a base struct that this struct extends. The base struct can be defined either before or after this struct.

Child elements

struct ::=

  • Sequence of

    • Zero or one of doc element

    • One or more of field elements

<typedef>

Specifies an alias name for a particular type together with its constraints.

Attributes

name

Name of the new type alias. It must satisfy restrictions on name attribute.

type

Type that this typedef aliases. See type attribute.

nullable

See nullable attribute.

Child elements

See common structure of typed elements.

Typed elements

arg, result, field and typedef in SMODL represent elements that define typed values. That is, all elements values should have a specific type. For all these elements some additional constraints can be introduced in order to limit corresponding elements values. This to be specified using child elements according to the following table.

Table 2. Supported type constraints

TypeAllowed constraints

double

float

int

long

maxExclusive constraint

maxInclusive constraint

minExclusive constraint

minInclusive constraint

string

maxLength constraint

minLength constraint

pattern constraint


Elements for type constraints

The following elements define constraints on a particular type value and have common structure:

These elements have the same semantics as the corresponding XML Schema constraint facets as defined in the XML Schema Part 2: Section 4.3.

Attributes

value

The value of the constraint. See corresponding section of XML Schema Specification for details.

Child elements

Value constraint element ::=

  • Sequence of

    • Zero or one of doc element

Constraint semantics

The semantics of the constraint element

Table 3. Supported type constraints

Constraint elementMeaning of the value attribute
maxExclusive The exclusive upper bound of the value space for a numeric type.
maxInclusive The inclusive upper bound of the value space for a numeric type.
maxLength The maximum number of characters in a string value.
minExclusive The exclusive lower bound of the value space for a numeric type.
minInclusive The inclusive lower bound of the value space for a numeric type.
minLength The minimum number of characters in a string value.
pattern The XML Schema regular expression as defined by Appendix F of The XML Schema specification, part 2 to constrain the string values only to strings that matches the expression.

name attribute

SMODL elements arg, method, struct and typedef have required name attribute that assigns a name to a corresponding definition. In all cases, the value of the attribute is restricted to the following pattern:

  • [A-Za-z][A-Za-z0-9_]

That is, each name must begin with an ASCII letter and can follow by zero or more ASCII letters, digits or _ symbols. This ASCII-only restriction ensures compatibility with the widest possible selection of protocols and programming languages.

type attribute

SMODL elements arg, field, result and typedef have required type attribute that specifies a type of a corresponding definition. In all such cases, the value of the attribute must be either one of built-in types or a name of a struct defined by a service followed by zero or more of [] pairs. Presence of [] indicates that the type is an array type and number of [] gives dimensions of the array type.

nullable attribute

SMODL elements arg, field, result and typedef have the optional nullable attribute with two possible values: true and false (the default). When set to true, it specifies that the value of the corresponding element can be null.

Examples

Below listed excerpts from a smodl file that demonstrate use of constrained types: int, float, double, long and string.

Constraints for int type

Example 2. Int type constraints

<method name="getInint">
	<arg name="i" type="int"/>
	<result type="inint"/>
</method>

<method name="getExint">
	<arg name="i" type="int"/>
	<result type="exint"/>
</method>

<method name="getInintArray">
	<arg name="i" type="int[]"/>
	<result type="inint[]"/>
</method>

<method name="getExintArray">
	<arg name="i" type="int[]"/>
	<result type="exint[]"/>
</method>

<typedef name="inint" type="int">
	<maxInclusive value="2"/>        
	<minInclusive value="-1"/>        
</typedef>

<typedef name="exint" type="int">
	<maxExclusive value="2"/>        
	<minExclusive value="-1"/>        
</typedef>

Constraints for float type

Example 3. Float type constraints

<method name="getInfloat">
	<arg name="i" type="float"/>
	<result type="infloat"/>
</method>

<method name="getInfloatArray">
	<arg name="i" type="float[]"/>
	<result type="infloat[]"/>
</method>

<method name="getExfloat">
	<arg name="i" type="float"/>
	<result type="exfloat"/>
</method>

<method name="getExfloatArray">
	<arg name="i" type="float[]"/>
	<result type="exfloat[]"/>
</method>

<typedef name="infloat" type="float">
	<minInclusive value="-1.e-10"/>        
	<maxInclusive value="0.001"/>
</typedef>

<typedef name="exfloat" type="float">
	<minExclusive value="-1.e-10"/>        
	<maxExclusive value="0.001"/>
</typedef>

Constraints for double type

Example 4. Double type constraints

<method name="getIndouble">
	<arg name="i" type="double"/>
	<result type="indouble"/>
</method>

<method name="getIndoubleArray">
	<arg name="i" type="double[]"/>
	<result type="indouble[]"/>
</method>

<method name="getExdouble">
	<arg name="i" type="double"/>
	<result type="exdouble"/>
</method>

<method name="getExdoubleArray">
	<arg name="i" type="double[]"/>
	<result type="exdouble[]"/>
</method>

<typedef name="indouble" type="double">
	<minInclusive value="-1.e-10"/>        
	<maxInclusive value="0.001"/>
</typedef>

<typedef name="exdouble" type="double">
	<minExclusive value="-1.e-10"/>        
	<maxExclusive value="0.001"/>
</typedef>

Constraints for long type

Example 5. Long type constraints

<method name="getInlong">
	<arg name="i" type="long"/>
	<result type="inlong"/>
</method>

<method name="getInlongArray">
	<arg name="i" type="long[]"/>
	<result type="inlong[]"/>
</method>

<method name="getExlong">
	<arg name="i" type="long"/>
	<result type="exlong"/>
</method>

<method name="getExlongArray">
	<arg name="i" type="long[]"/>
	<result type="exlong[]"/>
</method>

<typedef name="inlong" type="long">
	<maxInclusive value="20000000000"/>        
	<minInclusive value="-3000000000000"/>        
</typedef>

<typedef name="exlong" type="long">
	<maxExclusive value="20000000000"/>        
	<minExclusive value="-3000000000000"/>        
</typedef>

Constraints for string type

Example 6. String type constraints

<method name="getString">
	<arg name="p" type="string"/>
	<result type="mystring"/>
</method>

<method name="getStringArray">
	<arg name="p" type="string[]"/>
	<result type="mystring[]"/>
</method>

<method name="getStringStruct">
	<arg name="p" type="strstruct"/>
	<result type="strstruct"/>
</method>

<struct name="strstruct">
    <field name="str" type="mystring"/>
</struct>

<typedef name="mystring" type="string">
    <maxLength value="16"/>        
    <minLength value="4"/>
    <pattern value="[a-z]*"/>
</typedef>"