This specification defines the Service Modeling Language, Version 1.1 (SML) used to model complex services and systems, including their structure, constraints, policies, and best practices. SML uses XML Schema and Schematron.
W3C publishes a
No features have been identified as "features at risk" by the SML Working Group.
The major substantive change since the previous publication of this specification as a Last Call Working Draft has been the introduction of what are expected to be the final namespace names for the SML and SML-IF namespaces; previously each new Working Draft used a new pair of namespace names. Other editorial and cosmetic changes have also been made.
This document has been developed by the
Publication as a Candidate Recommendation does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
Please submit comments on this document using the
This document was produced by a group operating under the
Last Modified: $Date: 2008/11/25 19:09:09 $
The Service Modeling Language (SML) provides a rich set of constructs for creating models of complex services and systems. Depending on the application domain, these models may include information such as configuration, deployment, monitoring, policy, health, capacity planning, target operating range, service level agreements, and so on. Models provide value in several important ways.
Models focus on capturing all invariant aspects of a service/system that must be maintained for the service/system to function properly.
Models represent a powerful mechanism for validating changes before applying the changes to a service/system. Also, when changes happen in a running service/system, they can be validated against the intended state described in the model. The actual service/system and its model together enable a self-healing service/system ― the ultimate objective. Models of a service/system must necessarily stay decoupled from the live service/system to create the control loop.
Models are units of communication and collaboration between designers, implementers, operators, and users; and can easily be shared, tracked, and revision controlled. This is important because complex services are often built and maintained by a variety of people playing different roles.
Models drive modularity, re-use, and standardization. Most real-world complex services and systems are composed of sufficiently complex parts. Re-use and standardization of services/systems and their parts is a key factor in reducing overall production and operation cost and in increasing reliability.
Models enable increased automation of management tasks. Automation facilities exposed by the majority of services/systems today could be driven by software ― not people ― both for reliable initial realization of a service/system as well as for ongoing lifecycle management.
A model in SML is realized as a set of interrelated XML documents. The XML documents contain information about the parts of a service, as well as the constraints that each part must satisfy for the service to function properly. Constraints are captured in two ways:
Schemas ― these are
constraints on the structure and content of the documents in a model. SML
uses XML Schema [
Rules ― are Boolean expressions that constrain
the structure and content of documents in a model. SML uses
Schematron [
One of the important operations on the model is to establish its validity. This involves checking whether all data in a model satisfies the schemas and rules declared.
This specification focuses primarily on defining the extensions to XML Schema for references that cross document boundaries, Schematron usage in SML, as well as the process of model validation. It is assumed that the reader is familiar with XML Schema and Schematron.
SML scenarios require several features that either do not exist or are not fully supported in XML Schema. These features can be classified as follows:
SML references – XML documents introduce boundaries
across content that needs to be treated as a unit. XML Schema does not have any support
for references that cross documents, although it does support references to elements in the same document through
xs:ID, xs:IDREF, xs:key and xs:keyref.
References between elements defined in separate SML
Rules – XML Schema does not support a language for defining arbitrary constraints on the structure and content of XML documents. SML uses Schematron to express assertions on the structure and content of XML documents.
XML Schema supports two forms of extension: "attributes in different namespace" and "application information elements"; both forms are used by SML extensions.
The keywords "
This specification uses the Augmented Backus-Naur Form (ABNF)
notation [
This specification follows the same conventions for schema components as those used in the
XML schema specification [
This specification refers to terms such as XML document, element, attribute,
etc. for the sake of brevity. The alternative would be to use terms like "XML
document or a
The content of this specification is normative except for sections or texts that are explicitly marked as non-normative. If a section is marked as non-normative, then all contained sub-sections are non-normative, even if they are not explicitly marked as such. All notes are non-normative unless otherwise specified.
The following terms are used in this specification. They are listed here in alphabetical order.
A well-formed XML
An
An
A set of inter-related
The subset of documents in a
The subset of documents in a
A
A
A
A
A
A
The information contained within a single sch:schema element.
An
Conceptually, an SML reference is used to signal a link from one element in an SML model to another element in the same model.
An
An element in a model to which an
A
| Prefix | XML Namespace | Specification(s) |
|---|---|---|
sml
|
http://www.w3.org/ns/sml
|
This specification |
smlfn
|
http://www.w3.org/ns/sml-function
|
This specification |
xs
|
http://www.w3.org/2001/XMLSchema
|
[ |
sch
|
http://purl.oclc.org/dsdl/schematron
|
[ |
Other specifications on which this one depends are listed in [
Support for
The ability to use multiple SML reference schemes for an SML reference.
An extensibility mechanism allowing new SML reference schemes to be defined.
Constraints on the type of a referenced element.
The ability to define key, unique, and key reference constraints across SML references.
Appendix
An element information item in an SML model instance document
is as an
Its ref
Its http://www.w3.org/ns/sml
Its collapse following "true" or "1".
This mechanism enables schema-less identification of SML references; i.e.,
SML references can be identified without relying on the Post Schema Validation
Infoset (PSVI). [
It is implementation-defined whether
SML model validators must use PSVI to identify SML references. See
An SML reference is considered to be an instance of a
specific SML
Although its normative definition allows several syntaxes to be used to
identify an SML reference, for the sake of brevity and consistency,
the rest of this specification uses
sml:ref="true" to denote an SML reference in examples and text.
The following example shows an SML reference that is an instance of the SML URI Reference scheme.
An SML reference is null if and only if it has an attribute information item for which all of the following is true
Its nilref
Its http://www.w3.org/ns/sml
Its collapse following "true" or "1".
It is a consequence of the preceding that this specification assigns no meaning
to the sml:nilref attribute when it is used on an element that is not an SML
reference. Model validators
The following example shows a null SML reference.
sml:nilref may be useful in the case where the schema author defines a complex
type specifying sml:ref="true" with a fixed value of "true", but the instance author
wants to signal the absence of a target.
It is implementation-defined whether
SML model validators must use PSVI to identify null SML references. See
An SML reference is unresolved if and only if all of the following is true:
It is a non-null SML reference.
None of the
The notion of unresolved reference is context dependent.
That is, different
The following example shows an unresolved SML reference (assuming that the document
dummy.xml does not exist in the model).
The element node that a non-null SML reference resolves to is its target. The target of
an SML reference
The method of determining which documents are part of an SML model is implementation-defined.
For example, an SML model may consist of documents listed in a configuration file or an SML model could be construed as the transitive closure of documents referred to by any SML references starting from a set of documents known to be in the model.
The following example shows an SML reference that targets the second Course
child element of the root element of the document target.xml.
Every non-null SML reference
The following example shows an SML reference that violates the at-most-one-target rule.
If a non-null SML reference is an instance of multiple
reference schemes,
all recognized reference schemes
To determine if two targets are the same or different,
If both of the following are true, then a model validator
The definition of the reference scheme(s) specifies how URIs are
transformed to
The two target-complete identifiers are identical using a case-sensitive, codepoint-by-codepoint comparison.
Otherwise, a model validator
For all other cases, it is implementation-defined whether to treat the targets as the same or not.
An element in a document
A null SML reference is an explicit declaration of intent by the document author that
the
Each non-null SML reference
The reference must have at most one target. [
The reference
The deref() function takes a node set of
elements and returns a node set consisting of element nodes
corresponding to the elements referenced by the input node set. In
particular, for each SML reference R in the input node set the output
node set contains at most one element node.
Let I = input node set; that is, the set of nodes passed to the deref() function.
Let O = output node set; that is, the set of nodes returned by the deref() function.
The behavior of deref() function
For each SML reference R in the input node set I:
If the implementation recognizes no SML reference scheme used in the SML reference R, then no element is added to O.
If the implementation recognizes R as an instance of N supported reference schemes,
then deref() is not required to attempt to resolve all N schemes.
Its behavior in this case is implementation-defined and the set of reference schemes
that are actually attempted may be any subset of the recognized schemes. This is
subject to the following constraints:
If deref() doesn't attempt to resolve any reference scheme or if none of the attempted reference schemes resolves, then no element is added to O.
If at least one of the attempted reference schemes resolves to more than one target element, then 0 or 1 of the targets is added to O.
If one attempted reference scheme resolves to a target different from the target resolved by another attempted reference scheme, then 0 or 1 of the targets is added to O.
If one attempted reference scheme resolves and another doesn't, then 0 or 1 of the targets is added to O.
If none of the above is true (that is, all attempted reference schemes resolve to the same one and only one target element, call it T), then one target element (namely, T) is added to O, if it does not already exist in O.
The above describes the behavior required for a general XPath 1.0 deref() library function, and as such exhibits several significant differences from the behavior required to validate SML references during model validation. First, it can be used to successfully process instance documents whose SML model validity is unknown or invalid, although the results in this case may not be interoperable. Second, since XPath 1.0 defines no way for a function to signal erroneous input to its caller, the behavior here is specified to return results for SML references that do not obey all of the validity rules, e.g. a reference whose XPath expression evaluates to more than one node. As described in this section, such a function would be insufficient to check the validity of SML references.
Model validators MUST provide an implementation of the deref() XPath extension function. In addition to the above requirements for general deref() function implementations, for each SML reference using recognized schemes, deref() in model validators MUST attempt to resolve at least one of the recognized schemes.
An SML reference
Although SML does not require the use of any specific
scheme, it does specify how a reference
An SML reference scheme definition
The set of rules that, when satisfied, identify an SML reference as an
instance of the scheme. An SML reference scheme definition
The set of rules that, when evaluated, resolve the SML reference to its target element node.
An assertion that states whether instances of the reference scheme are
transformed to
An SML reference scheme definition
The SML URI Reference Scheme is defined as follows:
An SML reference is identified as an instance of the SML URI Reference Scheme
if and only if exactly one element information item whose uri and whose http://www.w3.org/ns/sml is present as a child of that reference element.
An instance of the SML reference scheme is valid if it meets all of the following requirements.
The content of the uri element xs:anyURI as defined in the XML schema specification
[
The fragment identifier (if present)
An SML reference that is an instance of the SML URI Reference Scheme is resolved using the following steps:
An XML document
If the URI reference is a same-document reference
as defined in the applicable URI RFC,
then
Otherwise,
If the URI reference is a relative reference, then let <sml:uri> element as the base URI. Otherwise,
Dereference
As a result of the above definition, if the retrieved object is not of XML media type or if it is not well-formed XML then, by definition, that object is not a document as defined by this specification. In this case, the SML reference scheme instance is unresolved.
If no fragment component is present in the URI reference,
the SML URI Reference Scheme instance resolves to the root element of
If a fragment component is present in the URI reference, then the appropriate case among the following applies:
If the fragment component complies with the smlxpath1()
XPointer scheme syntax, then the reference target is obtained
by applying the fragment component to
If the fragment component complies with the
If a target
If a target in
Instances of the SML URI Reference Scheme are transformed to
The following example shows an SML reference that is an instance of the
SML URI Reference scheme. The reference targets the element with ID targetId
in document target.xml.
smlxpath1() scheme
The smlxpath1() scheme is intended to be used with the
XPointer Framework [
This section describes the syntax and semantics of the smlxpath1() scheme
and the behavior of XPointer processors with respect to this scheme.
Scheme name: smlxpath1
Scheme syntax using ABNF [
SMLXPath1_Fragment_ID ::= 'smlxpath1' '(' SMLXPath1_SchemeData ')'
SMLXPath1_SchemeData ::= XPath1.0_LocationPath
where,
XPath1.0_LocationPath is the
The deref() XPath extension function SMLXPath1_SchemeData.
Namespace Binding Context: The smlxpath1() scheme inherits
the set of namespace bindings available to the parent sml:uri element.
For a given document SMLXPath1_SchemeData to the root element of
In the case of instances of the SML URI Reference scheme,
The following example shows an SML reference that is an instance of the
SML URI Reference scheme. The reference targets the root element
of the document target.xml.
SML supports the following attributes for expressing constraints on SML references.
| Name | Description |
|---|---|
sml:acyclic
|
Used to specify whether cycles are prohibited for an SML reference. |
sml:targetRequired
|
Used to specify that an SML reference's target element is required to be present in the model. |
sml:targetElement
|
Used to constrain the name of the SML reference's target. |
sml:targetType
|
Used to constrain the type of the SML reference's target. |
SML defines a new property for every Complex Type Definition schema component:
An xs:boolean value. Required.
The value of xs:anyType is false.
SML defines three new properties for every Element Declaration component:
An An Element Declaration component. Optional. A Type Definition component. Optional. xs:boolean value. Required.
sml:acyclic is used to specify whether or not a cycle is allowed on
instances of a complex type. sml:acyclic attribute on any <xs:complexType> element in a schema document.
This attribute is of type xs:boolean and its true or false.
The
If sml:acyclic is present, then
Otherwise, if its {base type definition} is a complex type definition,
then
Otherwise ({base type definition} is a simple type definition),
If a complex type definition
If
The nodes in the graph are all the elements resolved to by SML references of
type
If a node
SML defines three attributes: sml:targetRequired,
sml:targetElement, and sml:targetType, for
constraining the target of an SML reference. These three attributes are
collectively called sml:target* attributes.
xs:element elements with a name attribute. The sml:target* constraints are attached to the element declaration schema component.
If sml:targetRequired is present, then
Otherwise if the element declaration has a {substitution group affiliation},
then
Otherwise
If sml:targetElement is present, then its actual value
Otherwise if {substitution group affiliation} is present, then
Otherwise
If sml:targetType is present, then its actual
value
Otherwise if {substitution group affiliation} is present,
then
Otherwise
If a global element declaration
If two element declarations
The above condition #2 on the use of sml:target*
attributes has been defined to reduce the implementation burden on
If an element declaration true, then each element instance of
If an element declaration
If an element declaration
The effect of the above instance validation rules is summarized in the following table.
| Reference Category |
Acyclic
|
targetRequired
|
targetElement
|
targetType
|
|---|---|---|---|---|
| Non-reference | Satisfied | Satisfied | Satisfied | Satisfied |
| Null | Satisfied | Violated | Satisfied | Satisfied |
| Unresolved | Satisfied | Violated | Satisfied | Satisfied |
| Resolved | Check | Satisfied | Check | Check |
"Check" in the table above means that the appropriate constraint must be evaluated.
The constraints described above can be useful even on element declarations whose instances are not necessarily SML references, because the decision about whether to include a constraint and the decision about whether to make the element an SML reference can be made independently - some choices made by the schema author, other choices made by the instance document author.
XML Schema supports the definition of uniqueness and reference
constraints through xs:key, xs:unique, and
xs:keyref elements. However, the scope of these constraints is
restricted to a single document. SML defines analogs for these constraints,
whose scope extends to multiple documents by allowing them to traverse
xs:element/xs:annotation/xs:appinfo where
the xs:element has a name attribute.
| Name | Description |
|---|---|
sml:key
|
Similar to xs:key except that the selector and
field XPath expression can use the smlfn:deref function |
sml:unique
|
Similar to xs:unique except that the selector and
field XPath expression can use the smlfn:deref function |
sml:keyref
|
Similar to xs:keyref except that the selector and
field XPath expression can use the smlfn:deref function |
Appendix
SML identity constraints are attached to the element declaration
schema component. SML defines a new property for every element declaration
schema component:
A set of SML identity constraint
definitions components, which have the same set of properties as
XML Schema identity constraint definitions.
Names of all SML identity constraint definitions exist in a single symbol space, which is disjoint from any symbol space of XML Schema components.
For each sml:key, sml:unique, or sml:keyref
element without the ref attribute specified,
sml:selector and sml:field elements
are used in place of xs:selector and xs:field.
For each sml:key, sml:unique, or sml:keyref
element with the ref attribute specified,
ref attribute, with the following conditions:
The name attribute
The sml:selector and sml:field child
elements
If the element is sml:key, then the value of ref
attribute
If the element is sml:unique, then the value of the ref
attribute
If element is sml:keyref, then the value of the ref
attribute refer attribute
In addition to SML identity constraints obtained from the above explicit
definitions or references, if an element declaration
sml:selector XPath expression has the same syntax as that defined in the
XML Schema identity constraint selector XPath syntax with one exception.
The sml:selector XPath smlfn:deref() functions,
with function calls nested to any depth, at the beginning of the expression. The XML Schema identity constraint
selector Path production is amended to support this requirement as defined below.
sml:field XPath expression has the same syntax as that defined in the
XML Schema identity constraint field XPath syntax with one exception.
The sml:field XPath smlfn:deref() functions,
with function calls nested to any depth, at the beginning of the expression. The XML Schema identity constraint
field Path production is amended to support this requirement as defined below.
The
This could happen if the ref attribute resolves to
an identity constraint already contained in the same element declaration’s
If a global element declaration
If two element declarations
This rule is defined to reduce the implementation burden
for model validators. Please refer to section
Validation rules for SML identity constraints are the same as specified in
section smlfn:deref() function.
Let BV = value of SML constraint property P (one of
Let RV = value that restricts BV.
For RV to be a valid restriction of BV, the appropriate case among the following
For
If BV is true, RV is true.
If BV is false, RV is either true or false.
For
RV is same as BV.
RV is in the substitution group of BV.
For
RV is same as BV.
RV is a type derived from BV.
For
RV is same as BV. That is, all of the following is true.
The number of entries in RV is same as the number of entries in BV.
For each entry in BV, there exists an entry in RV with the same qualified name ({name} + {target namespace}).
RV is a superset of BV. That is, RV has all of the entries from BV as defined in the previous item and it has one or more additional entries.
This section is non-normative.
For a complex type D derived from its {base type definition} B, if an element declaration ED is included in D and an element declaration EB is included in B, and ED and EB satisfy the "NameAndTypeOK" constraint, then the SML constraints (target* and SML identity constraints) applicable to ED must be
the same as those on EB in case of derivation by extension, and
the same or more restrictive compared to those on EB in case of derivation by restriction.
SML defines this behavior to ensure that one cannot get rid of SML constraints on elements in a complex type by simply deriving another type from that type.
Enforcing this condition across derivation by restriction would require an implementation to match a restricting particle to the corresponding restricted particle in order to evaluate condition 2 above. This level of support is not provided by most XML Schema frameworks; thus most SML validators would otherwise need to duplicate large parts of XML Schema's compilation logic to verify consistent usage of SML constraints across derivation by restriction. In order to reduce this implementation burden on model validators, SML requires that all element declarations with a given name that are included in a complex type definition must have the same SML constraint value. This allows model validators to find the restricted particle for a restricting particle using a simple name match.
This also means that the value of a given SML constraint applicable to all element declarations of a given name in complex type definition can be logically viewed as available at a single place, for example in a property attached to that complex type, rather than being scattered across element declarations in that type. The next section uses this logical view because it makes it easier to understand and formally define SML constraint behavior across complex type derivation.
SML defines four properties for every complex type definition schema component CT.
A list of (qname, value) pairs, where, qname is a qualified name ({namespace name} + {name}). value is the value of a A list of (qname, value) pairs, where, qname is a qualified name ({namespace name} + {name}). value is the value of a A list of (qname, value) pairs, where, qname is a qualified name ({namespace name} + {name}). value is the value of a A list of (qname, value) pairs, where, qname is a qualified name ({namespace name} + {name}). value is the value of a
The value of the above 4 properties for xs:anyType is empty.
Let
CT = A complex type definition.
C = SML constraint (one of targetRequired, targetElement, targetType, SML identity constraint).
P = A property of CT corresponding to constraint C (one of
V = The value of P, a list of (qname, value) pairs.
ED = An element declaration contained in CT.
PED = A property of ED corresponding to constraint C (one of
Property P is assigned value V as defined below:
For each element declaration ED, with qualified name qn, contained in CT:
If ED does not have constraint C, that is, the value of PED is absent (or false in case of targetRequired), then skip ED.
Otherwise, if there is already an entry in V for qn, then skip ED.
If the value of the existing entry is different from
the value of PED then it is treated as a schema validation
error as defined in
section
Otherwise, the entry (qn, value of PED) is added to the list V.
The appropriate case among the following applies:
If CT is derived by extension from a simple type definition then value V is empty.
If CT is derived by extension from a complex type definition BT:
The initial value of V is computed as defined in list item 1 above and then,
For each entry (qn, vb) in the value of P in BT:
If V has an entry (qn, vc) present, then ensure that vc is same as vb. If it is not same, then it is treated as a schema validation error.
If V does not have any entry (qn, vc) present, then copy (qn, vb) into V.
If CT is derived by restriction from a complex type definition BT:
The initial value of V is computed as defined in list item 1 above and then,
For each entry (qn, vb) in the value of P in BT:
If V has an entry (qn, vc) present, then ensure that vc is a valid restriction of vb as defined in section
If V does not have any entry (qn, vc) present, then copy (qn, vb) into V.
Let,
CT = the complex type of element declaration ED.
E = an instance of ED.
C = a child element of E.
If C matches an element declaration contained in CT and if one or
more of CT's constraint properties, defined in
One way for constraints to be embedded in element
declarations or type definitions in a schema is for constraint element to be
included in a schema document, embedded at the appropriate locations within the
xs:element or xs:complexType elements which describe
the element declaration or type definition.
Element declarations and type definitions created by other means can, however,
also have constraints embedded within the {application information} of
their {annotation} properties. How such embedding is accomplished is outside
the scope of this specification and is likely to vary among
XML Schema supports a number of built-in grammar-based constraints but it does
not support a language for defining arbitrary rules for constraining the
structure and content of documents. Schematron [
This section assumes that the reader is familiar with
Schematron concepts; the Schematron standard is documented in [
Constraints can be specified using the
sch:assert and sch:report elements from Schematron.
The following example uses sch:assert elements to specify two
constraints:
An IPv4 address must have four bytes
An IPv6 address must have sixteen bytes
A xs:annotation/xs:appinfo element for a complex
type definition or an element declaration is applicable to all instances of
the complex type or element. In the above example, the pattern
Length (which is a part of the containing Schematron constraint)
is applicable for all elements whose
type is IPAddress or a derived type
of IPAddress. A pattern element contains one or
more sch:rule elements and a single sch:rule element contains
one or more assert and/or report elements. Each sch:rule element specifies its context using the
context attribute. This context expression
is evaluated in the context of each applicable element and results in an
element node set for which the assert and report test expressions contained in
the sch:rule element are evaluated. The context expression is defined as an XSLT Pattern.
This means that the smlfn:deref function may not be used in the
location path of a context expression.
In the above example,
context=".". Therefore the two assert
expressions are evaluated in the context of each applicable element; i.e.,
each element of type IPAddress. The
test expression for an assert is a
boolean expression, and the assert is
violated (or fires) if its test expression evaluates
to false. A report is violated (or
fires) if its test expression evaluates to true. Thus, an
assert can be converted to a
report by simply negating its test expression.
The following example uses report elements to represent the IP address constraints of the previous
example:
If a sch:assert or sch:report is violated,
the violation is reported together with the specified message.
The message can include substitution strings based on
XPath expressions. These can be specified using the
sch:value-of element. The following example
uses the sch:value-of element to
include the number of specified address bytes in the message:
In addition to being embedded in complex type definitions, constraints can also be embedded in global element declarations. Such constraints are evaluated for each instance element corresponding to the global element declaration. Consider the following example:
The sch:rule elements contained in
StudentPattern are applicable to all element
instances of the StrictUniversity global element declaration. For each
StrictUniversity element, the XPath expression
specified as the value of the context attribute is evaluated to return a node set, and the test
expressions for the two asserts are evaluated for each node in this node set.
Thus, these two asserts verify the following conditions for
each instance of StrictUniversity.
The ID of each student must begin with '99'.
Each student must be enrolled in at least one course.
Schematron patterns can be authored in separate rule documents that are then bound to a set of documents in the model.
The following example shows the constraints for
StrictUniversity expressed in a separate document:
The binding of the rule document containing the StudentPattern
pattern to documents that may contain instances of StrictUniversity
element is implementation-defined.
smlfn:deref()
function in the body of Schematron constraints.
If the queryBinding attribute is not specified, then its value
is assumed to be set to "xslt". "xslt" query binding.
"xslt".
SML defines a new property for every complex type definition schema component and every element declaration schema component.
A set of
The sch:schema elements embedded within the component, and sometimes in part from the
sch:schema elements sch:schema
elements if they appear as items in any other location.
Let the
The value of the
The value of xs:anyType is the empty set.
If the schema component is a global element declaration, then the
value of its
If the element declaration has a {substitution group affiliation},
then the value of
Otherwise (the element declaration has no {substitution group affiliation}), the empty set.
If the schema component is a complex type definition, then the
value of its
If the component's {base type definition} is a complex type definition,
then the
Otherwise (i.e., when {base type definition} is a simple type definition), the empty set.
Otherwise, the value of the
If a complex type
If a complex type
It is an error if all of the following are true.
An element declaration
Each
Each
All of the assertion tests in fired rules
SML defines the sml:locid attribute in support of localization
of natural-language texts or messages. sml:locid attribute on the following elements:
sch:assert and sch:report
in a
sch:assert and sch:report
in a Schematron pattern embedded in the
{application information} of the {annotation} property of a
complex type definition or an element declaration.
Elements in instance documents with textual content.
Model validators
that support the sml:locid
attribute sml:locid
attribute value to access the location of the translated text.
The mechanism for using the
QName value of the sml:locid attribute to locate the
translated text is implementation dependent. For example,
the {namespace name} can be used to identify the resource
containing the text and the {local name} can be used
to identify the text within such resource. Refer to
sml:locid attribute can be used to support text localization.
There is often the case that a sch:assert
or sch:report message can be reused in different
situations. To be able to re-use a message, the schema author
must be able to substitute variable content based on the
context in which the message is being used.
Although this specification does not mandate
the use of variable substitution in Schematron messages, it suggests the
use of xsl:variable when variable
substitution is desired.
Refer to xsl:variable
can be used in support of reusing localized messages.
A program is a
A conforming SML model processor is a
The validator
The validator
The validator MUST support Schematron [
The validator
The validator deref()
XPath extension function.
The validator
The validator
The conformance of a model and the validity of a model can be assessed if and
only if all documents in the model are available to the model validator. A
model validator
A model is a
Each
For each XML Schema document in the model's definition documents, the
[validity] property of the root element
All schemas assembled from the XML Schema documents in the model's
definition documents
All schemas assembled from the XML Schema documents in the model's
definition documents
Each Schematron document in the model's
definition documents
This specification does not define how schemas are assembled and which schema documents contribute to assembling the schemas.
A
In each instance document in the model, which is bound to a schema,
the [validity] property of the root element
The schema-validity of instance documents not bound to any schema does not contribute to the validity or invalidity of the model.
How schemas are bound to instance documents is not defined by this specification. Multiple schemas may be bound to the same instance document.
SML validity entails NOT being Schema-Invalid on the root or any descendant. SML validity can be non-vacuously checked only after assessment of Schema validity, and only on the portions of the subtree for which PSVI is available.
Because the depth of PSVI is implementation-dependent, there is variability in the visibility of SML constraints available to the SML validator, and consequently in SML validity results.
Each document in the model
Each document in the model
This means, for example, that each document must satisfy all applicable sml:acyclic, sml:target*, and SML identity constraints.
This section is a reference guide to the SML extensions of XML Schema and XPath.
Used to specify that instances of an SML reference of a given type and its derived types do not create any cycles in a model
If this attribute is set to true for a complex type CT, then instances of CT (including any derived types of CT) that are SML references cannot create any cycles in a model. In the following example, HostedOnRefType is a complex type declaration whose instances cannot create a cycle:
If
the sml:acyclic attribute is not
specified or set to false for a complex type declaration, then instances of this type
that are SML references may create cycles in a model.
This global attribute is used to identify SML references.
Any element that has sml:ref="true" will be treated as an SML reference.
This global attribute is used to identify null SML references.
Any SML reference that has sml:nilref="true" or sml:nilref="1" will be treated as a
null SML reference.
A QName representing the name of a referenced element
sml:targetElement is supported as an attribute for any element
declaration. The value of this
attribute must be the name of some global element declaration. Let
sml:targetElement="ns:GTE" for some element declaration
E. Then each element instance of E must
target an element that is an instance of ns:GTE or an
instance of some global element declaration in the substitution group
hierarchy whose head is ns:GTE.
In the following example, the element referenced by
instances of HostOS must be an instance
of win:Windows
A model is invalid if its documents violate one or more sml:targetElement constraints.
Used to specify that instances of an SML reference must target elements
in the model; i.e., an instance of the SML reference can not be null
or contain an unresolved reference. Therefore it is an error if targetRequired="true" is specified
on an element declaration where the corresponding
SML reference element R has sml:nilref="true".
In the following example, the targetRequired attribute is used
to specify that application instances must have a host operating system.
A model is invalid if its documents violate one or more
sml:targetRequired constraints.
A QName representing the type of a referenced element
sml:targetType is supported as an attribute for any element
declarations. If the value of this
attribute is specified as T, then the
type of the referenced element must either be T or a derived type of T. In
the following example, the type of the element referenced by the
OperatingSystem element must be
"ibm:LinuxType" or its derived
type
A model is invalid if its documents violate one or more sml:targetType constraints.
This attribute can be defined on the sch:assert,
sch:report and on any element with textual content.
The sml:locid attribute
is used to define the translation location for the text
content of the containing element.
The mechanism for using the QName value of
the sml:locid attribute to locate a translated text
is implementation specific and hence outside the scope of this specification.
This element is used to specify a key constraint in some scope. The
semantics are the same as that for xs:key except that
sml:key can also be used to specify key constraints on other
documents; i.e., the sml:selector child element of
sml:key can contain deref functions to resolve
elements in another document.
sml:key is supported in the appinfo
of an xs:element.
Applies a constraint in the context of the containing xs:element that scopes the
range of a nested document reference.
sml:keyref is supported in the
appinfo of an xs:element.
This element is used to specify a uniqueness constraint in some scope. The
semantics are the same as that for xs:unique except that
sml:unique can also be used to specify uniqueness constraints on
other documents; i.e., the sml:selector child element of
sml:unique can contain deref functions to resolve
elements in another document.
sml:unique is supported in the
appinfo of an xs:element.
Specifies an SML reference that is an instance of the SML URI reference scheme.
This element must be used to specify SML references that use the SML URI Reference Scheme.
This function takes a node set and attempts to resolve the SML references. The resulting node set is the set of elements that are obtained by successfully resolving (or de-referencing) the SML references. For example,
will resolve the SML reference, Student. The target of an SML reference must
always be an element.
This
key and keyref constraints
Schematron constraints
The following example illustrates the use of SML references. Consider the following schema fragment:
The schema definition in the above example is
SML agnostic and does not make use of any SML attributes, elements, or types.
The EnrolledCourse element,
however, has an open content model and this can be used to mark instances
of EnrolledCourse as
SML references as shown below:
The first EnrolledCourse element in the above example
is an SML reference since it specifies
sml:ref="true". It uses the SML URI Reference Scheme to target
the element for course PHY101. The second and third
EnrolledCourse elements are not SML references; the
second element specifies sml:ref="false" and
the third element does not specify the sml:ref
attribute. Note that the second EnrolledCourse element
contains an sml:uri element which satisfies the syntax of the
SML URI Reference Scheme (referring to course MAT100)
but this will be ignored since sml:ref="false"
for this EnrolledCourse element.
Note that, there are no SML constraints defined on the EnrolledCourse element or
on the type of that element in the schema. Therefore, even if the first EnrolledCourse element instance is marked as an SML reference, no SML constraints are evaluated for that element
during model validation. However, checks such as the ones defined in section
An EnrolledCourse
SML reference can be a marked as a null reference if it specifies the sml:nilref="true"
attribute as shown in the following example (the first EnrolledCourse
element is a null SML reference):
In the above example, the first SML reference, EnrolledCourse, defines
the sml:nilref="true" attribute which marks this as a null SML reference.
By specifying a null reference, the document author makes an explicit declaration
that this Student element does not refer to any target element.
Specifying a null reference does not have any SML-defined effect on the interpretation of element
in non-SML contexts. In particular, in this case, SML says nothing about the
interpretation of the Grade and Name elements.
Any such interpretation is left to the application, its usage context, other specifications, etc.
The following example illustrates the use of the SML URI Reference Scheme [Courses.xml –
whose URI is http://www.university.example.org/Universities/MIT/Courses.xml. In this case, the element inside
Courses.xml that corresponds to the course
PHY101 can be referenced as follows (assuming that Coursesis the root element in
Courses.xml)
An SML reference can also reference an element in its own document. To see this consider the following instance document
Here, the EnrolledCourse element for the student
Jane Doe references the Course element for MAT200 in
the same document.
The following example will be used to illustrate the sml:key,
sml:unique, and sml:keyref constraints across SML
references. This example consists of three schema documents. university.xsd
contains the type definitions for a University element, a
Student SML reference and a Course SML reference.
students.xsd contains the
type definitions for an EnrolledCourse SML reference and a Student element.
courses.xsd contains the type definition for a Course element.
XML Schema supports key and uniqueness constraints through
xs:key and xs:unique, but these constraints can
only be specified within a single XML document. The sml:key and
sml:unique elements support the specification of key and
uniqueness constraints across documents. We'll use the UniversityType
definition to illustrate this concept. It is reasonable to expect that each
student in a university must have a unique identity, and this identity must
be specified. This can be expressed as follows:
The sml:key and sml:unique constraints are
similar but not the same. sml:key requires that the specified
fields must be present in instance documents and have unique values, whereas
sml:unique simply requires the specified fields to have unique
values but does not require them to be present in instance documents. Thus
keys imply uniqueness, but uniqueness does not imply keys. For example,
students in a university must have a unique social security numbers, but the
university may have foreign students who do not possess this number. This
constraint can be specified as follows:
The sml:key and sml:unique constraint
are always specified in the context of a scoping element. In the above
example, the University element declaration is the
context for the key and unique constraints.
The following example illustrates the use of the ref
attribute in an SML identity constraint:
In the above example, the PrivateUniversity element
declaration specifies the StudentSSNisUnique unique
constraint by referencing its name in the
University element declaration.
XML Schema supports key references through xs:keyref to
ensure that one set of values is a subset of another set of values within an
XML document. Such constraints are similar to foreign keys in relational
databases. Key references in XML Schema are only supported within a single
XML document. The sml:keyref element allows key references to be
specified across SML references and across XML documents. The following example uses
sml:keyref to capture the requirement that students enrolled in a course
must be currently enrolled in the university:
The above constraint specifies that for a university, the set of IDs of
students enrolled in a course is a subset of the set of IDs of students currently enrolled
in the university. In particular, the selector and field
elements in StudentIDisKey key constraint identify the set of
IDs of students currently enrolled in the university, and the selector and
field elements in CourseStudents key reference
constraint identify the set of IDs of students enrolled in courses.
In the following example, the sml:locid attribute is used
to define the translation information for the Schematron
sch:assert error message:
In this example, the {namespace name} URI information of the
sml:locid attribute is used to define the location
for the resource containing the translated text:
The {namespace name} URI can point to a file containing the translated message, a folder containing a set of translated files or any other type of resource that can help locate the translated message. It is implementation dependent how the model validator makes use of this information for finding the actual resource containing the translated message.
In this example, http://www.university.example.org/translation/
points to a folder containing a set of translation resources. For this specific example,
there will be a set of translation files located under
http://www.university.example.org/translation/. Each of these translation
files will correspond to a language in which the messages have been translated.
For this example, the translation is only available in French and German so there
are only two files under http://www.university.example.org/translation/:
http://www.university.example.org/translation/fr_lang.txt file contains
the French translation of the sch:assert message.
http://www.university.example.org/translation/de_lang.txt contains
the German translation of the sch:assert message.
The {local part} information of the sml:locid
attribute is used to define the identity of the message being translated.
This information will be used to locate the translated text within
the translation resource.
The file http://www.university.example.org/translation/fr_lang.txt contains
the French translation of the sch:assert message, identified by
StudentIDErrorMsg, which is the {local part} information of the sml:locid attribute:
The file http://www.university.example.org/translation/de_lang.txt contains
the German translation for the sch:assert message. The message is identified by
StudentIDErrorMsg, which is the {local part} information of the sml:locid attribute:
This example demonstrates how localization can be applied to a Schematron rule with the
purpose of making the Schematron rule available to
sml:locid localization support:
The Schematron rule is language agnostic in the sense that the author does
not have to be aware of the locale of a potential sml:locid {namespace name} URI.
There is a clear separation between the translation process and the Schematron rule.
There are no changes required to be applied to the Schematron rule when translations
for other languages are made available. To support a new language,
all that needs to be done is to add a new translation file under the location identified by the
sml:locid {namespace name} URI.
There is often the case that a message can be reused in different
sch:assert or sch:report situations.
In the example above, the author of the Schematron rule may
want to use this error message in other contexts:
This is not possible since the translated message contains the context where the rule has been applied:
To be able to re-use this message, the schema author must
be able to substitute u:ID in <sch:value-of select="u:ID "/> with
some content that is appropriate for the context in which the message is used. In order
to do that, the translation messages should substitute this context with a generic value.
In other words, instead of the messages shown above, the translation files should contain messages where the context of the Schematron rule is being replaced with a generic variable.
The error message in sch:assert identified by the
lang:StudentIDErrorMsg value can now be reused in contexts
other than the one described by the above sample.
The sample below shows how substitution variable support can be achieved on Schematron
sch:assert messages by using xsl:variable support:
The error message in sch:assert and the localization identifier
lang:StudentIDErrorMsg can now be reused in contexts
other than u:Students/u:Student.
The editors acknowledge the members of the Service Modeling Language Working Group, the members of other W3C Working Groups, and industry experts in other forums who have contributed directly or indirectly to the process or content of creating this document.
At the time this specification was published, the members of the Service Modeling Language Working Group were:
John Arwe (IBM Corporation), Len Charest (Microsoft Corporation), Sandy Gao (IBM Corporation), Paul Lipton (CA), James Lynn (HP), Kumar Pandit (Microsoft Corporation), Valentina Popescu (IBM Corporation), Virginia Smith (HP), Michael Sperberg-McQueen (W3C/MIT), David Whiteman (IBM Corporation), Kirk Wilson (CA).
The Service Modeling Language Working Group has benefited in its work from the participation and contributions of a number of people not currently members of the Working Group, including in particular those named below.
Dave Ehnebuske (IBM), Jon Hass (Dell), Steve Jerman (Cisco), Heather Kreger (IBM), Vincent Kowalski (BMC), Milan Milenkovic (Intel), Bryan Murray (HP), Phil Prasek (HP), Junaid Saiyed (EMC), Harm Sluiman (IBM), Bassam Tabbara (Microsoft), Vijay Tewari (Intel), William Vambenepe (HP), Marv Waschke (CA), Andrea Westerinen (Microsoft), Pratul Dublish (Microsoft), Julia McCarthy (IBM).
Affiliations given above are those current at the time of their work with the working group.