SML Overview

Service Modeling Language Overview

This document gives an overview of the emerging standards, Service Modeling Language (SML) and Service Modeling Language Interchange Format (SML-IF) and their support in COSMOS. For a complete description, see the linked standards and COSMOS Eclipse-based documentation.

What is SML?

Service Modeling Language (SML) is "used to model complex services and systems, including their structure, constraints, policies, and best practices." It uses an extension of XML schema and is based on a profile of Schematron.

The language is domain neutral and can be applied to "deployment, monitoring, policy, health, capacity planning, service level agreements", and many other areas.

The constraints are captured in two ways:

• XML Schema Extensions
• Schematron Rules

Before delving into each method, SML references need to be explored.

SML References

One significant advantage of using SML is the ability to reference elements within or outside an SML document. The purpose of an SML reference is to declare a relationship between one entity and another. For example, such a relationship could be the applications making up a service, the service registered on a repository, or a service conformance to a service level agreement (SLA). See the figure below:

The standard defines the SML URI Scheme to declare references. The syntax of the scheme is:

 SMLURI ::= URI ('#' SMLXPath1_Fragment_ID)?

URI is dereferenced to retrieve the document, and SMLXPath1_Fragment_ID is dereferenced to retrieve a specific element contained in the document. The fragment is defined using XPath. Here is an example of an SML reference:

<RequiredPreRequisite sml:ref="true" xmlns:u="urn:university">
   <sml:uri>Course1#smlxpath1(u:Name)</sml:uri>
</RequiredPreRequisite>

XML Schema Extensions

In addition to using standard XML schema to define constraints, the SML standard defines seven constraints on SML references. Each constraint is described in more detail below:

• sml:acyclic - Prohibits cycles for a referenced element type
• sml:targetRequired - Indicates the requirement for a reference to be resolved
• sml:targetElement - Indicates the element name a reference should resolve to
• sml:targetType - Indicates the element type a reference should resolve to
• sml:key - Similar to xs:key but allows cross document references
• sml:keyref - Similar to xs:keyref but allows cross document references
• sml:unique - Similar to xs:unique but allows cross document references

Schematron Rules

Schematron is an ISO standard used to define constraints, not on the grammar but on the content of the document. Schematron is applied by first locating a context node and applying all assertion tests that apply. Examples of constraints include:

• IPv4 address must have four bytes
• The text content of a dereferenced element must start with a token

There are different ways of applying rules to an SML document. See the specification for full details. The following example defines an Schematron rule on an element declaration. The constraint ensures an SLA is associated with all external services:

<xs:element name="Services" type="tns:ServicesType">
   <xs:annotation>
      <xs:appinfo>
         <sch:schema xmlns:sch="http://purl.oclc.org/dsdl/schematron">
            <sch:ns prefix="u" uri="http://service.example.org" />
            <sch:ns prefix="smlfn" uri="http://www.w3.org/2008/09/sml-function"/>
            <sch:pattern id="ExternalServicePattern">
               <sch:rule context="tns:Service[@type='external']">
                  <sch:assert test="count(smlfn:deref(tns:SLA)) > 0">
                     For quality assurance, a service level agreement must be associated with
                     all external services
                  </sch:assert>                 
               </sch:rule>
            </sch:pattern>
         </sch:schema>
      </xs:appinfo>
   </xs:annotation>
</xs:element>

What is SML-IF?

Any system model is likely comprised of many SML documents representing the units of the system. For example, it's likely for a software instance to be represented using one SML document and an operating system using another. The purpose of the SML-IF standard is to define an XML structure to be able to package and interchange a collection of SML documents.

An SML-IF document is divided into two document types: definitions and instances. There are two variations of definition documents: Schema documents and Rule documents. The figure below depicts the general structure of an SML-IF document:

An SML-IF file is primarily used "to distinguish between model definition documents and model instance documents, and to bind rule documents with other documents in the interchange set."

The pseudo-schema of SML-IF's XML structure appears below:

<?xml version="1.0" encoding="UTF-8"?>
<model xmlns="http://www.w3.org/2008/09/sml-if"
       xmlns:xs="http://www.w3.org/2001/XMLSchema"
       SMLIFVersion="xs:token Version number of the SML-IF spec used to generate the current document">
    <identity>
        <name>
            xs:anyURI Namespace identifying the model
        </name>
        <version> ?
            xs:token <!-- The version of this model. E.g., 1.2 or 0.3 -->
        </version>
        <displayName sml:locid="xs:anyURI URI identifying the translation
                                resource for the display name" ?> ?
            xs:string Descriptive name of model intended for display
        <displayName/>
        <baseURI>
            xs:anyURI <!-- Base URI for relative references defined in the interchange set; 
                           must be an absolute reference. Deprecated: use xml:base instead. -->
        </baseURI> ?
        <description sml:locid="xs:anyURI URI identifying the translation
                                resource for the description" ?> ?
            xs:string Textual description of model for human consumption
        <description/>
    </identity>
    <ruleBindings> ?
        <ruleBinding> *
            <documentAlias="xs:anyURI"/> ?
            <ruleAlias="xs:anyURI"/>
        </ruleBinding>
    </ruleBindings>
    <schemaBindings> ?
        <defaultSchema> ?
            <namespaceBinding/> *  
        </defaultSchema>
        <schemaBinding> *
            <namespaceBinding/> *  
            <documentAlias/> +     
        </schemaBinding>
    </schemaBindings>
    <definitions schemaComplete="xs:boolean"> ?
        <document> *
            <docInfo> ?
	            <baseURI> ?
	                xs:anyURI <!-- If a document has a baseURI, then this will be used to form the 
	                               base URI for all relative URIs subject to SML URI processing 
	                               contained by that document. -->            
	            </baseURI>        
	            <aliases> ?
	                <alias> *
	                    xs:anyURI <!-- A URI by which SML references from other documents may refer to this document. -->
	                </alias>
	            </aliases>
            </docInfo>
                [
                <data>
                    xs:any <!-- At most one definition document goes here -->
                </data>
                |
                <base64Data>
                    xs:any <!-- At most one base64 encoded definition document goes here -->
                </base64Data>
                |
                <locator>
                    <documentURI/> ?
                        xs:any <!-- A URI or IRI that points to a definition document goes here -->
                </locator>
                ]
        </document>
    </definitions>
    <instances> ?
        <document> *
            <docInfo> ?
                <baseURI> ?
                     xs:anyURI <!-- If a document has a baseURI, then this will be used to form the 
                            base URI for all relative URIs subject to SML URI processing 
                            contained by that document. -->            
                </baseURI>        
                <aliases> ?
                   <alias> *
                       xs:anyURI <!-- A URI by which SML references from other documents may refer to this document. -->                        
                   </alias>
                </aliases>
            </docInfo>
            [
            <data>
                xs:any<!-- At most one instance document goes here -->
            </data>
            |
            <base64Data>
                xs:any <!-- At most one base64 encoded instance document goes here -->
            </base64Data>
            |
            <locator>
                <documentURI/> ?
                    xs:any <!-- A URI or IRI that points to an instance document goes here -->
            </locator>
            ]
        </document>
    </instances>
</model>

COSMOS Support

The COSMOS project provides tools to support the advancement of the SML* standard. These tools are provided as part of the Resource Modeling subproject. Features include:

• File-based SML repository for storing and managing SML documents
• Importing of SML-IF documents into the repository
• Exporting of stored SML documents into an SML-IF document
• Validating SML/SML-IF documents
• Editing SML-IF documents
• Querying the repository using CMDBf
• Example SML resources modeling a data center

COSMOS' SML repository provides APIs for storing, retrieving, and managing SML documents. Using the repository, clients can retrieve an SML document and any of its containing references.

Importing, exporting, validation, and CMDBf querying are all defined as repository operations. Even though the repository can be used as-is, there are a number of ways to extend its capabilities for a commercial offering:

1. Adding additional operations
2. Using RDBMS instead of files
3. Adding application specific APIs on top of SML APIs
4. and etc...

More documentation on COSMOS SML support can be found in the COSMOS User Guide.

Setting up for development

You will need to follow the steps on i13 COSMOS development setup instructions in order to prepare for development. SML does not require the MDR toolkit.

Eclipse Setup

• Follow these instructions to setup the CVS repository in your Eclipse installation.
• Check out each project you need individually (the names are listed below). Eclipse only knows how to compile projects/plugins that are at the root of the workspace.
• Compile each project as a sanity check that it was built properly.

Code organization

The CVS projects/plugins are organized under org.eclipse.cosmos.resource-modeling as follows:

• org.eclipse.cosmos.rm.validation - includes the validation support
• org.eclipse.cosmos.rm.repository - includes the API for managing SML documents, plus the operations for validation, import, and export
• org.eclipse.cosmos.rm.smlif - includes the SML-IF editor, plus the UI components of the validator, import, and export

Similarly, there are TPTP and JUnit-based test plugins provided under org.eclipse.cosmos.tests as follows:

• common
  • org.eclipse.cosmos.common.tests - utilities referenced by the others below
• resource-modeling
  • org.eclipse.cosmos.rm.validation.tests - tests the validation plugin. Also includes the code to generate the COSMOS SML Test Plan document.
  • org.eclipse.cosmos.rm.repository.tests - tests the repository plugin
  • org.eclipse.cosmos.rm.smlif.tests - tests the smlif plugin

The documentation for COSMOS' SML support is contained in the following places:

• doc/v12/usersguide/html - there is a both an overview of Resource Modeling and a specific chapter on the SML tools
• doc/v12/usersguide/help_files - this is the same content as the SML tools chapter and needs to stay in sync. It will eventually constitute a help plugin that will allow for contextual help in the SML tools

The following example projects are available as well:

• org.eclipse.cosmos.rm.sml.mdr - an implementation of a CMDBf Management Data Repository (MDR) using SML documents. Requires that you install the COSMOS SDK prerequisites including Axis2.
• org.eclipse.cosmos.rm.example.datacenter - an example of a data center expressed using SML
• org.eclipse.cosmos.rm.example.rtx - an example information model to be used in data federation or other common IT model, expressed in SML. See enhancement 242818 for more information.

Test organization

• SML Validation Tests in org.eclipse.cosmos.rm.validation.tests
  • Setup
    • You likely will need to update the values in /src/org.eclipse.cosmos.rm.internal.validation.common/testMessages.properties. Each must point to an already-existing directory on your local machine.
    • It is a good idea to run AllTests (see below) on a fresh build to establish a baseline before you start making changes, so you know if your changes caused any regression later. You will want to note the number of failures, and which tests fail. After verifying your fixes using specific JUnits, it is advisable to run all the tests again to verify your changes caused no regression of other JUnits via unintended side effects.
    • There is currently a one to one correspondence between JUnit .java classes and TPTP testsuites. If you want to create new tests, always do it through the TPTP testsuites, so we can maintain that ratio.
  • Running a JUnit: select it and then select Run As > JUnit Test from the context menu. JUnit will show you the results in a window, but you lose that history once you close the JUnit window.
  • Quick testing: run a plain JUnit to check your fix(es). This this will not update the test reports that are published with each iteration, those are based off TPTP .execution files.
  • Periodic testing with trackable execution history: run the tests in the "junits", "plugin-junits", and "manual-junits" folders, and direct the output of the .execution files to the corresponding "*-results" folders
  • Frequent regression testing: run the /src/*.java JUnits(AllTests.java should run them all, barring accidental omissions when adding new tests)

• SML Repository Tests in org.eclipse.cosmos.rm.repository.tests (this section incomplete)
  • Setup
    • You likely will need to update the values in /src/META-INF/configurationn.properties files. Each must point to an already-existing directory on your local machine.

Programmatic APIs

Note: This should be moved to the official documentation at some point.

The COSMOS User Guide describes access to the validator, import, and export utilities using the Eclipse tooling. These functions can also be invoked programmatically.

Validator API

org.eclipse.cosmos.rm.internal.repository.operations.FileValidateOperation illustrates the class and arguments to be invoked for validating an SML-IF file or collection of SML model unit files.

more to come...

Import API

org.eclipse.cosmos.rm.internal.repository.operations.FileImportOperation illustrates the class and arguments to be invoked for importing an SML-IF file into an SML repository

more to come...

Export API

org.eclipse.cosmos.rm.internal.repository.operations.FileExportOperation illustrates the class and arguments to be invoked for exporting SML model units from an SML repository to an SML-IF file

more to come...

References

1. Service Modeling Language (SML) Standard
2. Service Modeling Language Interchange Format (SML-IF) Standard
3. Schematron
4. XPath
5. XML Schema
6. COSMOS SML Test Plan