Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
SML Overview
Contents
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:
- Adding additional operations
- Using RDBMS instead of files
- Adding application specific APIs on top of SML APIs
- 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
- Define a CVS repository with the following parameters unless you are a committer.
- Connection type:
pserver - User:
anonymous - Password:
- Leave the password blank
- Host:
dev.eclipse.org - Repository path:
/cvsroot/technology
- Connection type:
- 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- 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
-
TODO: list other examples, doc plugins, etc.