<span class="diff-add"><span>Service Modeling Language, Version 1.1</span></span> -- Review Version

W3C

Service Modeling Language, Version 1.1

W3C Working Draft 10 September 2008

This version:
http://www.w3.org/TR/2008/WD-sml-20080910/
Latest version:
http://www.w3.org/TR/sml/
Previous version:
http://www.w3.org/TR/2007/WD-sml-20070806/
Editors:
Bhalchandra Pandit, Microsoft Corporation
Valentina Popescu, IBM Corporation
Virginia Smith, HP

This document is also available in these non-normative formats: XML.


Abstract

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 is based on a profile of Schematron.

Status of this Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This is the third Public Working Draft of the Service Modeling Language, Version 1.1 specification for review by W3C members and other interested parties. It has been developed by the Service Modeling Language (SML) Working Group, which is a part of the Extensible Markup Language (XML) Activity.

The features and algorithms described in the normative portion of the document are specified in enough detail adequate for early implementation experiments.

Publication as a Working Draft 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.

Comments on this document are invited and are to be sent to the public-sml@w3.org mailing list (public archive).

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

Table of Contents

1. Introduction (Non-Normative)
2. Notations and Terminology
    2.1 Notational Conventions
    2.2 Terminology
    2.3 XML Namespaces
3. Dependencies on Other Specifications
4. SML References
    4.1 Reference Definitions
        4.1.1 SML Reference
        4.1.2 SML Null Reference
        4.1.3 Unresolved SML Reference
        4.1.4 SML Reference Target
    4.2 Reference Semantics
        4.2.1 At Most One Target
        4.2.2 Consistent References
        4.2.3 Identical Targets
        4.2.4 Multiple References  
        4.2.5 Null References
        4.2.6 deref() XPath Extension Function
    4.3 Reference Schemes
        4.3.1 SML URI Scheme
            4.3.1.1 The smlxpath1() scheme
    4.4 Constraints on References
        4.4.1 sml:acyclic
            4.4.1.1 Mapping from Schema
            4.4.1.2 Schema Validity Rules
            4.4.1.3 Instance Validity Rules
        4.4.2 Constraints on SML Reference Targets
            4.4.2.1 Mapping from schema
            4.4.2.2 Schema Validity Rules
            4.4.2.3 Instance Validity Rules
        4.4.3 Reference Constraints Summary (Non-Normative)
    4.5 Identity Constraints
        4.5.1 Syntax and Semantics
            4.5.1.1 Mapping from Schema
            4.5.1.2 Schema Validity Rules
            4.5.1.3 Instance Validity Rules
5. Rules
    5.1 Informal Description (Non-Normative)
    5.2 Rule Support
    5.3 Rules Embedded in Schema Documents
        5.3.1 Mapping from schema
        5.3.2 Schema Validity Rules
        5.3.3 Instance Validity Rules
    5.4 Rules Authored in Rule Documents
        5.4.1 Rule Binding
6. Localization of natural-language messages
    6.1 Variable substitution
7. Conformance Criteria
8. SML Extension Reference (Non-Normative)
    8.1 Attributes
        8.1.1 sml:acyclic
        8.1.2 sml:ref
        8.1.3 sml:nilref
        8.1.4 sml:targetElement
        8.1.5 sml:targetRequired
        8.1.6 sml:targetType
        8.1.7 sml:locid
    8.2 Elements
        8.2.1 sml:key
        8.2.2 sml:keyref
        8.2.3 sml:unique
        8.2.4 sml:uri
    8.3 XPath functions
        8.3.1 smlfn:deref
9. References
    9.1 Normative
    9.2 Non-Normative

Appendices

A. Normative SML Schema
B. Model Definition Document Sample (Non-Normative)
C. SML References Sample (Non-Normative)
D. SML URI Scheme Sample (Non-Normative)
E. SML Identity Constraints Sample (Non-Normative)
F. Localization and Variable Substitution Sample (Non-Normative)
G. Acknowledgements (Non-Normative)


1. Introduction (Non-Normative)

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.

  1. Models focus on capturing all invariant aspects of a service/system that must be maintained for the service/system to function properly.

  2. 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.

  3. 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.

  4. 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.

  5. 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:

  1. Schemas ― these are constraints on the structure and content of the documents in a model. SML uses XML Schema [XML Schema Structures, XML Schema Datatypes] as the schema language. In addition SML defines a set of extensions to XML Schema to support references that may cross document boundaries.

  2. Rules ― are Boolean expressions that constrain the structure and content of documents in a model. SML uses a profile of Schematron [ISO/IEC 19757-3, Introduction to Schematron, Improving Validation with Schematron] and XPath [XPath] for rules.

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, the profile of Schematron used by SML, as well as the process of model validation. It is assumed that the reader is familiar with XML Schema and Schematron.

SML uses XML Schema [XML Schema Structures, XML Schema Datatypes] to define constraints on the structure of data in a model.

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:

  1. 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 within elements in the same document through xs:ID, xs:IDREF, xs:key and xs:keyref. References between elements defined in separate SML model documents are fundamental to the SML specification. SML extends XML Schema to support references that may cross document boundaries, and a set of constraints on those references that apply regardless of whether they cross document boundaries or not.

  2. Rules – XML Schema does not support a language for defining arbitrary rules 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.

2. Notations and Terminology

2.1 Notational Conventions

The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [IETF RFC 2119].

The content of this specification is normative except for sections, notes, 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.

2.2 Terminology

Document

A well-formed XML document, as defined in [XML].

Model

A set of inter-related documents that describe a service or system.  Each model consists of two disjoint subsets of documents – model definition documents and model instance documents.

Reference

A link from one element in an SML model to another element from the same model.

Schematron Constraint

The information contained within a single sch:schema element.

Rule

A rule is a boolean expression that constrains the structure and content of a set of documents in a model.

Rule bindings

A rule binding is an association of a set of one or more rule documents with a set of zero or more model documents. The documents associated with a given rule document are said to be "bound" to it. For a model to be valid, every definition and/or instance document in the model must conform to the constraints defined by every rule document it is bound to. It is permissible for a rule document to have no bindings associated with it, and for a model document to be bound to zero rule documents.

Rule document

A rule document is a model definition document consisting of Schematron rules that conforms to the SML's profile of Schematron.

Schema document

A schema document is a model definition document that conforms to the XML Schema specification [XML Schema Structures] definition of a schema document.

Model Definition Documents

The subset of documents in a model that describes the schemas and rules that govern the structure and content of the model's documents. This specification defines two types of model definition document, schema documents and rule documents, but permits implementations to define other types of model definition documents. Such other types of model definition documents do not play any role in SML model validation.

Model Instance Documents

The subset of documents in a model that describes the structure and content of the modeled entities.

Model Validation

Model validation is the process of verifying that all documents in a model are valid with respect to the model's definition documents.

Model Validator

A model validator is an embodiment capable of performing model validation.

Target-complete URI

A target-complete URI is a URI or IRI that contains all the information required to locate a target of an SML reference.

2.3 XML Namespaces

Table 2-1 lists XML namespaces that are used in this specification. The choice of any namespace prefix is arbitrary and not semantically significant.

Table 2-1. XML Namespaces used in this specification.
PrefixXML NamespaceSpecification(s)
sml http://www.w3.org/2008/01/sml This specification
smlerr http://www.w3.org/2008/01/sml-err This specification
smlfn http://www.w3.org/2008/01/sml-function This specification
xs http://www.w3.org/2001/XMLSchema [XML Schema Structures, XML Schema Datatypes]
sch http://purl.oclc.org/dsdl/schematron [ISO/IEC 19757-3]
xsi http://www.w3.org/2001/XMLSchema-instance XML Schema instance, as defined in [XML Schema Structures]

3. Dependencies on Other Specifications

Other specifications on which this one depends are listed in [Normative-References].

Conforming implementations of this specification MUST support XML 1.0 [XML], XML Schema 1.0 [XML Schema Structures, XML Schema Datatypes], Schematron [ISO/IEC 19757-3] and XPath 1.0 [XPath]. Conforming implementations MAY additionally support later versions of the XML, XML Schema, Schematron or XPath specifications.

4. SML References

Support for SML references in an SML model includes:

  1. The ability to use multiple reference schemes for representing references.

  2. An extensibility mechanism allowing new reference schemes to be defined.

  3. Constraints on the type of a referenced element.

  4. The ability to define key, unique, and key reference constraints across SML references.

Conforming model validators MUST support SML references as defined by this specification.

4.1 Reference Definitions

4.1.1 SML Reference

An element information item in an SML model instance document MUST be treated as a reference element if and only if:

  1. It has an attribute information item whose [local name] is ref and whose [namespace name] is http://www.w3.org/2008/01/sml and whose [normalized value] , after whitespace normalization using collapse following schema rules, is either "true" or "1".

This mechanism enables schema-less identification of reference elements, i.e., reference elements can be identified without relying on PSVI.

Although its normative definition allows several syntaxes to be used to identify an SML reference element, 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.

4.1.2 SML Null Reference

An element information item in an SML model instance document is an SML null reference if and only if:

  1. It is an SML reference.

  2. It has an attribute information item whose [local name] is nilref and whose [namespace name] is http://www.w3.org/2008/01/sml and whose [normalized value] after whitespace normalization using collapse following schema rules, is either "true" or "1".

4.1.3 Unresolved SML Reference

An element information item in an SML model instance document is an unresolved SML reference if and only if:

  1. It is a non-null SML reference.

  2. None of the recognized reference schemes resolves.

4.1.4 SML Reference Target

The node set a non-null SML reference resolves to is its target. SML null references have no target.

4.2 Reference Semantics

A model validator MUST attempt to resolve an SML reference using all reference schemes of which the reference is recognized as an instance.

4.2.1 At Most One Target

Every non-null reference MUST target at most one element in a model. When a recognized scheme in a reference resolves to more than one target then the model MUST be declared invalid.

4.2.2 Consistent References

An SML model MUST be declared invalid when a recognized scheme resolves to a target that's different from the target resolved to by another recognized scheme or when one recognized scheme resolves and another does not.

4.2.3 Identical Targets

To determine if two targets are the same or different, a model validator MUST obey the following rules.

  1. A model validator MUST consider both targets to be the same when both of the following are true.

    1. The definition of the scheme(s) used to locate the targets specifies that the scheme uses target-complete URIs. [4.3 Reference Schemes]

    2. The two URIs or IRIs used to locate the targets are identical using a case-sensitive, codepoint-by-codepoint comparison.

  2. A model validator MUST consider both targets to be different when there is something available in the element information items for the targets that tells them apart. For example, if there is an infoset property for which the 2 targets have different values, they are different. This applies recursively for complex-valued properties.

  3. For all other cases, it is implementation-defined whether to treat the targets as the same or not.

4.2.4 Multiple References  

An element in a document MAY be targeted by multiple reference elements. These reference elements may use different schemes and/or be expressed in different ways.  

4.2.5 Null References

A null reference is an explicit declaration of intent by the document author that the reference itself does not exist, and a processing directive (not a hint) to processors not to attempt to recognize any reference schemes in it. If a reference element is recognized as null, then processors MUST NOT attempt to resolve it. The question of whether a null reference is resolved or not is undefined; it is an ill-formed question.

4.2.6 deref() XPath Extension Function

Each SML processor MUST provide an implementation of the deref() XPath extension function. This 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 node R in the input node set the output node set contains at most one element node. The behavior of deref() function MUST satisfy the following constraints:

  1. If the implementation recognizes no scheme used in the reference, then deref() returns no target for R.

  2. If the implementation recognizes R as using N supported 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 schemes that are actually attempted may be any subset of the recognized schemes. This is subject to the following constraints:

    1. If deref() doesn't attempt to resolve any scheme or if none of the attempted schemes resolves, then no target is returned.

    2. If at least one of the attempted schemes resolves to more than one target element, then 0 or 1 of the targets is returned.

    3. If one attempted scheme resolves to a target that's different from the target resolved by another attempted scheme, then 0 or 1 of the targets is returned.

    4. If one attempted scheme resolves and another doesn't, then 0 or 1 of the targets is returned.

    5. If none of the above is true (that is, all attempted schemes resolve to the same one and only one target element, call it T), then one target is returned (namely, T).

4.3 Reference Schemes

An SML reference MAY be represented by using a variety of schemes, including those defined in this specification. SML does not mandate the use of any specific schemes. A reference scheme MAY use child elements, attributes, both, or neither to capture the information necessary to identify the reference target. It is not required that all elements in an SML model be reachable via an SML reference. This will depend on the support defined by the chosen reference scheme.

Although SML does not require the use of any specific scheme, it does specify how a reference MUST be represented when using SML-defined reference schemes. This specification defines the 4.3.1 SML URI Scheme for identifying reference targets.

All of the following MUST be defined for each SML reference scheme,

  1. The set of rules that, when satisfied, identify a reference element as containing one and the only instance of the scheme within that reference element.

  2. The set of rules that, when evaluated, resolve the containing reference to a set of target element nodes.

  3. An assertion that states whether or not the scheme uses target-complete URIs.

A schema definition MAY impose additional requirements on references recognized as instances of that scheme. Such requirements, if any, MUST NOT be applied by scheme implementations to references that are not instances of the corresponding scheme.

4.3.1 SML URI Scheme

The SML URI Scheme is defined as follows:

  1. An SML reference element is identified as using the SML URI scheme if and only if exactly one element information item whose [local name] is uri and whose [namespace name] is http://www.w3.org/2008/01/sml is present as a child of that reference element.

  2. The SML URI scheme is resolved using the following steps:

    1. A document is obtained by dereferencing the URI reference, sans fragment identifier, using the appropriate operation defined for the scheme used in that URI reference. If there is no document retrieved, the scheme instance is unresolved.

    2. If a fragment identifier is not present in the URI reference, the scheme instance resolves to the root element of the retrieved document.

    3. If a fragment identifier is present in the URI reference, the scheme instance resolves to the set of elements obtained by applying the fragment identifier to the root element of the retrieved document.

  3. The SML URI Scheme can be used in an SML-IF [SML-IF 1.1] document to reference documents from the interchange set.

  4. Scheme syntax:

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

    where ,

    1. URI is a URI reference without a fragment identifier.

    2. SMLXPath1_Fragment_ID is a production that defines the syntax of the fragment portion of the SML URI scheme. This is defined in section 4.3.1.1 The smlxpath1() scheme.

4.3.1.1 The smlxpath1() scheme

The smlxpath1() scheme is intended to be used with the XPointer Framework [XPointer] to allow addressing of elements. The 4.3.1 SML URI Scheme uses it to encode fragment identifiers.

EmptyThis section describes the syntax and semantics of the smlxpath1() scheme and the behavior of XPointer processors with respect to this scheme.

  1. Scheme name: smlxpath1.

  2. Scheme syntax:

    SMLXPath1_Fragment_ID ::= 'smlxpath1' '(' SMLXPath1_SchemeData ')'

    SMLXPath1_SchemeData ::= XPath1.0_LocationPath

    where,

    XPath1.0_LocationPath is the LocationPath production defined in the XPath 1.0 specification [XPath].

  3. The deref() XPath extension function MUST NOT be present in the expression evaluation context function library when processing the location path in SMLXPath1_SchemeData.

  4. Namespace Binding Context: The smlxpath1() scheme inherits the set of namespace bindings available to the containing element.

  5. Document Context: The document context is set by the URI reference containing the smlxpath1() scheme instance.

  6. The element(s) targeted by a scheme instance are obtained by applying the location path in SMLXPath1_SchemeData to the root element of the document in the document context. The result MUST be a set of elements. The set MAY be empty. If the result of applying the location path is something other than a set of elements, then the XPointer result is an error.

4.4 Constraints on References

SML supports the following attributes for expressing constraints on reference elements.

Table 4-1. Attributes
NameDescription
sml:acyclic Used to specify whether cycles are prohibited for a reference.
sml:targetRequired Used to specify that a reference's target element is required to be present in the model.
sml:targetElement Used to constrain the name of the reference's target.
sml:targetType Used to constrain the type of the reference's target.

SML defines a new property for every Complex Type Definition schema component:

{acyclic}

An xs:boolean value. Required.

The value of {acyclic} for xs:anyType is false.

And 3 new properties for every Element Declaration component:

{target required}

An xs:boolean value. Required.

{target element}

An Element Declaration component. Optional.

{target type}

A Type Definition component. Optional.

4.4.1 sml:acyclic

sml:acyclic is used to specify that a cycle is not allowed for an SML reference type. Model validators that conform to this specification MUST support the sml:acyclic attribute on any <xs:complexType> element in a schema document. This attribute is of type xs:boolean and its actual value can be either true or false.

4.4.1.1 Mapping from Schema

{acyclic} of a complex type definition is as specified by the appropriate case among the following:

  1. If sml:acyclic is present, then {acyclic} has the actual value of this attribute.

  2. Otherwise, if its {base type definition} is a complex type definition, then {acyclic} has the same value of {acyclic} as its {base type definition}.

  3. Otherwise ({base type definition} is a simple type definition), {acyclic} is false.

4.4.1.2 Schema Validity Rules

If a complex type definition CT's {base type definition} is also a complex type definition and has {acyclic} true, then CT MUST have {acyclic} true.

4.4.1.3 Instance Validity Rules

If CT is a complex type definition with {acyclic} true, then instances of CT MUST NOT create cycles in the model. More precisely, the directed graph constructed in the following way MUST be acyclic:

  1. The nodes in the graph are all the elements resolved to by SML references of type CT or types derived from CT.

  2. If a node N is or contains an SML reference R of type CT or a type derived from CT, and R resolves to T (which must also be a node in the graph), then an arc is drawn from N to T.

4.4.2 Constraints on SML Reference Targets

SML defines three attributes: sml:targetRequired, sml:targetElement, and sml:targetType, for constraining the target of a reference. These three attributes are collectively called sml:target* attributes. Model validators that conform to this specification MUST support these attributes on all xs:element elements with a name attribute.

4.4.2.1 Mapping from schema
  1. {target required} is as specified by the appropriate case among the following:

    1. If sml:targetRequired is present, then {target required} is the actual value of this attribute.

    2. Otherwise if the element declaration has a {substitution group affiliation}, then {target required} is the same as that of the {substitution group affiliation}.

    3. Otherwise if the element declaration ED is contained (directly, indirectly, or implicitly) in a content model of a complex type D, who is a restriction of another complex type B and B contains an element declaration EB with the same name as ED, then {target required} of ED is the same as that of EB.

    4. Otherwise {target required} is false.

  2. {target element} is as specified by the appropriate case among the following:

    1. If sml:targetElement is present, then its actual value MUST resolve to a global element declaration G, and {target element} is G.

    2. Otherwise if {substitution group affiliation} is present, then {target element} is the same as that of the {substitution group affiliation}.

    3. Otherwise if the element declaration ED is contained (directly, indirectly, or implicitly) in a content model of a complex type D, who is a restriction of another complex type B and B contains an element declaration EB with the same name as ED, then{target element} of ED is the same as that of EB.

    4. Otherwise {target element} is absent.

  3. {target type} is as specified by the appropriate case among the following:

    1. If sml:targetType is present, then its actual value MUST resolve to a global type definition T, and {target type} is T.

    2. Otherwise if {substitution group affiliation} is present, then {target type} is the same as that of the {substitution group affiliation}.

    3. Otherwise if the element declaration ED is contained (directly, indirectly, or implicitly) in a content model of a complex type D, who is a restriction of another complex type B and B contains an element declaration EB with the same name as ED, then {target type} of ED is the same as that of EB.

    4. Otherwise {target type} is absent.

4.4.2.2 Schema Validity Rules

Model validators that conform to this specification MUST enforce the following:

  1. If a global element declaration S has a {substitution group affiliation} G, then all the following are true:

    1. If G has {target required} true then S also has {target required} true.

    2. If G has {target element} TEG, then S has {target element} TES and TES is the same as TEG or is in the substitution group of TEG.

    3. If G has {target type} TTG, then S has {target type} TTS and TTS is validly derived from TTG.

  2. If 2 element declarations E1 and E2 have the same {namespace name} and {name} and they are both contained (directly, indirectly, or implicitly) in a content model of a complex type, then E1 and E2 have the same {target required}, {target element}, and {target type}.

  3. For a complex type D derived by restriction 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 (for XML Schema’s definition of valid restrictions, see Schema Component Constraint: Particle Valid (Restriction), Constraints on Particle Schema Components in [XML Schema Structures]), then all the following are true:

    1. If EB has {target required} true then ED also has {target required} true.

    2. If EB has {target element} TEB, then ED has {target element} TED and TED is the same as TEB or is in the substitution group of TEB.

    3. If EB has {target type} TTB, then ED has {target type} TTD and TTD is validly derived from TTB.

Note:

This note is non-normative. The above condition #2 on the use of sml:target* attributes has been defined to reduce the implementation burden on model validators for verifying condition #3, that the use of sml:target* attributes is consistent across derivation by restriction. These conditions enable model validators to find the restricted particle for a restricting particle using a simple name match when sml:target* attributes are specified for these particles.  In the absence of the above conditions, it is extremely difficult for SML validators to verify condition #3. In order to verify condition #3, it is necessary to connect the particles in the derived type with  those from the restricted base type. However, 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:target* attributes across derivation by restriction.

4.4.2.3 Instance Validity Rules

If an element declaration E has {target required} true, then each element instance of E that is also an SML reference MUST target some element in the model, (no instance of E can be a null or unresolved SML reference).

If an element declaration E has {target element} TE, then each element instance of E that is also a resolved SML reference MUST target an element that is an instance of TE or an instance of some global element declaration in the substitution group of TE.

If an element declaration E has {target type} TT, then each element instance of E that is also a resolved SML reference MUST target an element whose [type definition] is TT or a type derived from TT.

4.4.3 Reference Constraints Summary (Non-Normative)

The effect of the above instance validation rules is summarized in the following table.

Table 4-2. Target Constraints and SML Reference Categories.
Acyclic targetRequired targetElement targetType
Non-referenceSatisfiedSatisfiedSatisfiedSatisfied
NullSatisfiedViolatedSatisfiedSatisfied
UnresolvedSatisfiedViolatedSatisfiedSatisfied
ResolvedCheckSatisfiedCheckCheck

4.5 Identity Constraints

XML Schema supports the definition of key, unique, and key 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 SML references.

Model validators that conform to this specification MUST support the following elements for defining identity constraints across references, as child elements of xs:element/xs:annotation/xs:appinfo where the xs:element has a name attribute:

NameDescription
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

SML defines a new property for every Element Declaration component:

{SML identity-constraints definitions}

A set of SML identity constraint definitions components, which have the same set of properties as XML Schema identity constraint definitions.

4.5.1 Syntax and Semantics

Names of all SML identity constraint definitions exist in a single symbol space, which is disjoint from any symbol space of XML Schema components.

4.5.1.1 Mapping from Schema

For each sml:key, sml:unique, or sml:keyref element without the ref attribute specified, {SML identity-constraints definitions} contains a component corresponding to this element, as specified in section 3.11 Identity-constraint Definitions of the XML Schema specification [XML Schema Structures]), where 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, {SML identity-constraints definitions} contains the component resolved to by the actual value of the ref attribute, with the following conditions:

  1. The name attribute MUST NOT be specified.

  2. The sml:selector and sml:field child elements MUST NOT be specified.

  3. If the element is sml:key, then the value of ref attribute MUST resolve to an SML key constraint.

  4. If the element is sml:unique, then the value of the ref attribute MUST resolve to an SML unique constraint.

  5. If element is sml:keyref, then the value of the ref attribute MUST resolve to an SML keyref constraint, and the refer attribute MUST NOT be specified.

In addition to SML identity constraints obtained from the above explicit definitions or references, if an element declaration S has a {substitution group affiliation} G, then its {SML identity-constraints definitions} also contains members of {SML identity-constraints definitions} of G.

If an element declaration ED is contained (directly, indirectly, or implicitly) in a content model of a complex type D, who is a restriction of another complex type B and B contains an element declaration EB with the same name as ED, then {SML identity-constraints definitions} of ED also contains members of {SML identity-constraints definitions} of EB.

4.5.1.2 Schema Validity Rules
  1. {selector} in SML identity constraints has the same syntax as that defined in the XML identity constraint selector XPath syntax with one exception. The SML identity constraint {selector} XPath allows smlfn:deref() functions, nested to any depth, at the beginning of the expression. The XML identity constraint selector Path production is amended to support this requirement as defined below.

    Path ::= ('.//')? Step ( '/' Step)* | DerefExpr
    DerefExpr ::= (NCName ':')? 'deref(' Step (/Step)* ')'  ('/'Step)* 
    
  2. The sml:field XPath expression MUST conform to the amended BNF defined above for the selector XPath expression with the following modification,to allow smlfn:deref() functions, nested to any depth, at the beginning of the expression.

    Path::= ('.//')?  ( Step '/')* ( Step | @NameTest ) |
            DerefExpr ('/' @NameTest)?
    
  3. The {SML identity-constraints definitions} of an element declaration MUST NOT contain two identity constraints with the same name.

    Note:

    This note is non-normative. This could happen if the ref attribute resolves to an identity constraint already contained in the same element declaration’s {SML identity-constraints definitions}.

  4. If a global element declaration S has a {substitution group affiliation} G, then {SML identity-constraints definitions} of S MUST be a superset of that of G.

  5. If two element declarations E1 and E2 have the same {namespace name} and {name} and they are both contained (directly, indirectly, or implicitly) in a content model of a complex type, then E1 and E2 MUST have the same set of {SML identity-constraints definitions}.

    Note:

    This note is non-normative. This rule is defined to reduce the implementation burden for model validators. It facilitates the matching of restricting and restricted particles using their names, and avoids the replication of large parts of XML Schema's compilation logic for this purpose.

  6. For a complex type D derived by restriction from its {base type definition} B, if ED is included in D and EB is included in B and ED and EB satisfies the "NameAndTypeOK" constraint (for XML Schema’s definition of valid restrictions, see Schema Component Constraint: Particle Valid (Restriction), Constraints on Particle Schema Components in [XML Schema Structures]), then {SML identity-constraints definitions} of ED MUST be a superset of that of EB.

4.5.1.3 Instance Validity Rules

Validation rules for SML identity constraints are the same as specified in section 3.11 Identity-constraint Definitions of the XML Schema specification [XML Schema Structures]), with the addition of support for the smlfn:deref() function.

5. Rules

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 [ISO/IEC 19757-3] is an ISO/IEC standard for defining assertions concerning a set of XML documents. SML uses a profile of the Schematron schema to add support for user-defined constraints. SML uses XPath, augmented with the smlfn:deref()  extension function, as its constraint language.

5.1 Informal Description (Non-Normative)

This section assumes that the reader is familiar with Schematron concepts; the Schematron standard is documented in [ISO/IEC 19757-3] and [Introduction to Schematron, Improving Validation with Schematron] are good tutorials on an older version of Schematron.

User-defined 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:

  1. An IPv4 address must have four bytes

  2. An IPv6 address must have sixteen bytes

<xs:simpleType  name="IPAddressVersionType">
       <xs:restriction base="xs:string" >
           <xs:enumeration value="V4" />
           <xs:enumeration value="V6" />
        </xs:restriction>
</xs:simpleType>

<xs:complexType name="IPAddress">
        <xs:annotation>
            <xs:appinfo>
                <sch:schema xmlns:sch="http://purl.oclc.org/dsdl/schematron">
                   <sch:ns prefix="tns" uri="urn:IPAddress" />
                   <sch:pattern id="Length">
                      <sch:rule context=".">
                         <sch:assert test="tns:version != 'V4' or count(tns:address) = 4">
                              A v4 IP address must have 4 bytes.
                         </sch:assert>
                         <sch:assert test="tns:version != 'V6' or count(tns:address) = 16">
                              A v6 IP address must have 16 bytes.
                         </sch:assert>
                      </sch:rule>
                   </sch:pattern>
                </sch:schema>            
            </xs:appinfo>
        </xs:annotation>
        <xs:sequence>
            <xs:element name="version" type="tns:IPAddressVersionType" />
            <xs:element name="address" type="xs:byte" minOccurs="4" maxOccurs="16" />
        </xs:sequence>
</xs:complexType>

A Schematron constraint embedded in the 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 rules and a rule element contains one or more assert and/or report elements. Each rule 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 defined in the rule 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:

    <xs:simpleType  name="IPAddressVersionType">
        <xs:restriction base="xs:string">
           <xs:enumeration value="V4"/>
           <xs:enumeration value="V6"/>
        </xs:restriction>
    </xs:simpleType>

    <xs:complexType name="IPAddress">
        <xs:annotation>
            <xs:appinfo>
                <sch:schema xmlns:sch="http://purl.oclc.org/dsdl/schematron">
                    <sch:ns prefix="tns" uri="urn:IPAddress" />
                    <sch:pattern id="Length">
                        <sch:rule context=".">
                            <sch:report test="tns:version = 'V4' and count(tns:address)!= 4">
                                A v4 IP address must have 4 bytes.
                            </sch:report>
                            <sch:report test="tns:version = 'V6' and count(tns:address) != 16">
                                A v6 IP address must have 16 bytes.
                            </sch:report>
                        </sch:rule>
                    </sch:pattern>
                </sch:schema>            
            </xs:appinfo>
        </xs:annotation>
        <xs:sequence>
            <xs:element name="version" type="tns:IPAddressVersionType" />
            <xs:element name="address" type="xs:byte" minOccurs="4" maxOccurs="16" />
        </xs:sequence>
    </xs:complexType>

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:

     <sch:assert test="tns:version != 'v4' or count(tns:address) = 4">
          A v4 IP address must have 4 bytes instead of the specified
          <sch:value-of select="string(count(tns:address))"/> bytes.
     </sch:assert>

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:

<xs:element name="StrictUniversity" type="tns:UniversityType">
    <xs:annotation>
        <xs:appinfo>
            <sch:schema xmlns:sch="http://purl.oclc.org/dsdl/schematron">
                <sch:ns prefix="u" uri="http://www.university.example.org/ns" />
                <sch:ns prefix="smlfn"  
                        uri="http://www.w3.org/2008/01/sml-function"/>
                <sch:pattern id="StudentPattern">
                    <sch:rule context="u:Students/u:Student">
                        <sch:assert test="smlfn:deref(.)[starts-with(u:ID,'99')]">
                            The specified ID <sch:value-of select="string(u:ID)"/>
                             does not begin with 99.
                        </sch:assert>
                        <sch:assert test="count(u:Courses/u:Course)>0">
                            The student <sch:value-of select="string(u:ID)"/> must be enrolled
                            in at least one course.
                        </sch:assert>
                    </sch:rule>
                </sch:pattern>
             </sch:schema>
         </xs:appinfo>
    </xs:annotation>
</xs:element>

The rules defined 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.  The context expression for the rule returns a node set consisting of all Student elements referenced by an instance of StrictUniversity, and the test expressions for the two asserts are evaluated for each element node in this node set.  Thus, these two asserts verify the following conditions for each instance of StrictUniversity

  1. The ID of each student must begin with '99'.

  2. Each student must be enrolled in at least one course.

Schematron patterns can be authored in separate rule documents which are next bound to a set of documents in the model.

The following example shows the constraints for StrictUniversity expressed in a separate document:

<?xml version="1.0" encoding="utf-8" ?>
        <sch:schema xmlns:sch="http://purl.oclc.org/dsdl/schematron">
            <sch:ns prefix="u" uri="http://www.university.example.org/ns" />
            <sch:ns prefix="smlfn" uri="http://www.w3.org/2008/01/sml-function"/>
            <sch:pattern id="StudentPattern">
                <sch:rule context="u:Students/u:Student">
                    <sch:assert test="smlfn:deref(.)[starts-with(u:ID,'99')]">
                        The specified ID <sch:value-of select="string(u:ID)"/>
                        does not begin with 99.
                    </sch:assert>
                    <sch:assert test="count(u:Courses/u:Course)>0">
                        The student <sch:value-of select="string(u:ID)"/> must be enrolled
                        in at least one course.
                    </sch:assert>
                </sch:rule>
            </sch:pattern>
</sch:schema>

The binding of the StudentPattern pattern to instances of StrictUniversity element is implementation-dependent and hence outside the scope of this specification.

5.2 Rule Support

SML supports a conforming profile of Schematron. All elements and attributes are supported.  

Model validators that conform to this specification are REQUIRED to support and evaluate XPath expressions augmented with the 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". Conforming implementations MUST support the "xslt" query binding. Conforming implementations MAY additionally support query bindings other than "xslt".

5.3 Rules Embedded in Schema Documents

SML defines a new property for every complex type definition schema component and every element declaration schema component.

{rules}

5.3.1 Mapping from schema

sch:schema elements can be embedded in members of the {application information} of the {annotation} of a global element declaration or a global complex type definition. They MUST NOT be embedded in any other kind of schema component.

Let local-rules be the set of Schematron constraints attached to a global element declaration or a global complex type definition.

The value of {rules} property of a schema component is computed as follows:

  1. The value of {rules} for xs:anyType is the empty set.

  2. If the schema component is a global element declaration, then the value of {rules} is same as its local-rules.

  3. If the schema component is a complex type definition, then the value of its {rules} is the union of its local-rules and the appropriate case from the following:

    1. If {base type definition} is a complex type definition, then {rules} of the {base type definition}. This is true for derivation by extension as well as for derivation by restriction.

    2. Otherwise ({base type definition} is a simple type definition, the empty set.

5.3.2 Schema Validity Rules

Model validators that conform to this specification MUST enforce the following rules.

  1. The value of {rules} MAY be non-empty for global element declarations, global complex type definitions or anonymous complex type definition of global element declarations. It MUST NOT be non-empty for any other schema component.

  2. The value of {rules} for a local element declaration MUST be the empty set.

  3. If a complex type D is derived by restriction or extension from {base type definition} B and if B has Schematron constraints defined on it then they are automatically copied to D and unioned with the Schematron constraints defined on D.

  4. If a complex type D is derived by restriction from {base type definition} B then, a global element declaration with non-empty {rules} contained in B cannot be restricted to a local element declaration in D. Consequently, it as an error if all of the following is true.

    1. An element declaration ED is contained (directly, indirectly, or implicitly) in D and an element declaration EB is contained (directly, indirectly, or implicitly) in B,

    2. ED and EB satisfy the "NameAndTypeOK" constraint (for XML Schema's definition of valid restrictions, see Schema Component Constraint: Particle Valid (Restriction), Constraints on Particle Schema Components in [XML Schema Structures])

    3. EB is a reference to a global element declaration with a Schematron constraint on it.

    4. ED is a local element declaration with the same name as EB.

5.3.3 Instance Validity Rules

Model validators that conform to this specification MUST behave as follows:  

  1. Each Schematron constraint in {rules} of a complex-type definition CT MUST be evaluated for all element instances of type CT in a model during the model's validation.

  2. Each Schematron constraint in {rules} of a global element declaration G MUST be evaluated for all element instances of G in a model during the model's validation.

  3. As defined in the Schematron specification [ISO/IEC 19757-3], a pattern MUST be evaluated for an instance element by evaluating the rule elements of the pattern in the order of their definition. The context expression for a rule MUST be evaluated in the context of the instance element, and all asserts and reports contained in the first rule whose context expression evaluates to a non-empty node set MUST be evaluated for each node in this node set.

  4. If an assert or report is violated, then the violation MUST be reported during model validation together with the specified message. The model MUST be declared invalid when this happens.

5.4 Rules Authored in Rule Documents

5.4.1 Rule Binding

Model validators that conform to this specification MUST provide a mechanism to support binding of Schematron patterns, authored in separate rule documents, to a set of documents in a model. The mechanism for binding such Schematron patterns to a set of documents in a model is implementation-dependent and hence outside the scope of this specification.

6. Localization of natural-language messages

SML defines the sml:locid attribute in support of localization of the natural-language texts or messages. Model validators that conform to this specification MAY support sml:locid attribute on the following elements:

  1. sch:assert and sch:report in a rule document.

  2. sch:assert and sch:report in a Schematron pattern embedded in the xs:annotation/xs:appinfo element for a complex type definition or an element declaration.

  3. Elements in instance documents where containing element has textual content, whenever allowed by schema.

Conforming model validators that support the sml:locid attribute MUST use the sml:locid attribute value to access the location of the translated text.

Note:

This note is non-normative. 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 test and the {local name} can be used to identify the text within such resource. Refer to F. Localization and Variable Substitution Sample section for a concrete sample on how the sml:locid attribute can be used to support text localization.

6.1 Variable substitution

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 how substitution variable is used in Schematron messages, it suggests the use of xsl:variable to achieve this support. Refer to F. Localization and Variable Substitution Sample section for a concrete sample on how the xsl:variable can be used in support of reusing localized messages.

7. Conformance Criteria

A program is a conforming SML model validator if it satisfies the following conditions:

  1. The validator MUST perform model validation as defined in this specification. Model validation is the process of examining each document in a model and verifying that this document is valid with respect to the model definition documents, i.e., each model instance document satisfies the schemas and rules defined in the applicable model definition documents.

  2. The validator MUST support XML XML], XML Schema [XML Schema Structures], and XPath [XPath] but MAY also support any future versions of these specifications.

  3. The validator MUST support Schematron [ISO/IEC 19757-3].

  4. The validator MUST perform Schematron rule evaluation on the #ALL phase.

  5. The validator MUST support the deref() XPath extension function.

A set of XML documents is a conforming SML model if it satisfies the following conditions:

  1. Each document in the model MUST be a well-formed XML document [XML]

  2. Each XML Schema document in the model's definition documents MUST satisfy the conditions expressed in Errors in Schema Construction and Structure (§5.1). [XML Schema Structures]

  3. Each Schematron document in the model's definition documents MUST be a valid Schematron document [ISO/IEC 19757-3]

A conforming SML model is valid if it satisfies all of the following conditions:

  1. In each instance document in the model, the [validity] property of the root element and all of its attributes and descendants MUST NOT be "invalid" when schema validity is assessed by a conforming schema-aware processor with respect to the referenced XML Schema documents in the model's definition documents. [XML Schema Structures]

  2. Each document in the model MUST satisfy all applicable Schematron constraints constraints when validated in the #ALL phase.

  3. Each document in the model MUST satisfy all applicable sml:acyclic and sml:target* constraints.

  4. Each document in the model MUST satisfy all applicable SML identity constraints.

  5. All documents in the model are available to the model validator. If any model document is not reachable, then the model validator's behavior is implementation-defined.

8. SML Extension Reference (Non-Normative)

This section is a reference of the SML extensions to XML Schema and XPath.

8.1 Attributes

8.1.1 sml:acyclic

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

<xs:attribute name="acyclic" type="xs:boolean"/>

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:

<xs:complexType name="Hostref" sml:acyclic="true">
...
</xs:complexType>

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.

8.1.2 sml:ref

This global attribute is used to identify reference elements.

<xs:attribute name="ref" type="xs:boolean"/>

 Any element that has sml:ref="true" will be treated as a reference element.

8.1.3 sml:nilref

This global attribute is used to identify null reference elements. This attribute MUST NOT be used on an element unless it also has sml:ref="true" specified.

<xs:attribute name="nilref" type="xs:boolean"/>

 Any element that has sml:nilref="true" or sml:nilref="1" will be treated as a null reference element.

8.1.4 sml:targetElement

A QName representing the name of a referenced element

 <xs:attribute name="targetElement" type="xs:QName"/>

sml:targetElement is supported as an attribute for any element declarations. 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 instances of win:Windows

<xs:element name="HostOS" type="tns:HostOSRefType"
         sml:targetElement="win:Windows"
         minOccurs="0"/>
 
<xs:complexType name="HostOSRefType">
  <xs:sequence>
    <xs:any namespace="##any" processContents="lax" minOccurs="0"
     maxOccurs="unbounded"/>
  </xs:sequence>
  <xs:anyAttribute namespace="##any" processContents="lax"/>
</xs:complexType>

A model is invalid if its documents violate one/more sml:targetElement constraints.

8.1.5 sml:targetRequired

Used to specify that instances of a reference element must target elements in the model, i.e., an instance of the reference element can not be null or contain an unresolved reference which does not target any element in the model. Therefore it is an error if targetRequired="true" is specified on an element declaration where the corresponding reference element R has sml:nilref="true".

<xs:attribute name="targetRequired" type="xs:boolean"/>

In the following example, the targetRequired attribute is used to specify that application instances must have a host operating system.

<xs:complexType name="ApplicationType">
    <xs:sequence>
      <xs:element name="Name" type="xs:string"/>
      <xs:element name="Vendor" type="xs:string"/>
      <xs:element name="Version" type="xs:string"/>
      <xs:element name="HostOSRef" type="tns:HostOSRefType"
                  sml:targetRequired="true"/>
    </xs:sequence>
</xs:complexType>

<xs:complexType name="HostOSRefType">
  <xs:sequence>
    <xs:any namespace="##any" processContents="lax" minOccurs="0"
     maxOccurs="unbounded"/>
  </xs:sequence>
  <xs:anyAttribute namespace="##any" processContents="lax"/>
</xs:complexType>

A model is invalid if its documents violate one/more sml:targetRequired constraints.

8.1.6 sml:targetType

A QName representing the type of a referenced element

    <xs:attribute name="targetType" type="xs:QName">

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

<xs:element name="OperatingSystem" type="tns:OperatingSystemRefType"
                      sml:targetType="ibm:LinuxType"
                      minOccurs="0"/>

<xs:complexType name="OperatingSystemRefType">
  <xs:sequence>
    <xs:any namespace="##any" processContents="lax" minOccurs="0"
     maxOccurs="unbounded"/>
  </xs:sequence>
  <xs:anyAttribute namespace="##any" processContents="lax"/>
</xs:complexType>

A model is invalid if its documents violate one/more sml:targetType constraints.

8.1.7 sml:locid

This attribute can be defined on the sch:assert, sch:report and on any element with a textual content, whenever the schema allows that. The sml:locid attribute is used to define the translation location for the text content of the containing element.

<xs:attribute name="locid" type="xs:QName"/>

The mechanism for using the QName value of the sml:locid attribute to locate a translated text is implementation specific and hence outside the scopes of this specification.

8.2 Elements

8.2.1 sml:key

This element is used to specify a key constraint in some scope. The semantics are essentially the same as that for xs:key but 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.

<xs:element name="key" type="sml:keybase"/>

sml:key is supported in the appinfo of an xs:element.  

8.2.2 sml:keyref

Applies a constraint in the context of the containing xs:element that scopes the range of a nested document reference.

    <xs:element name="keyref">
      <xs:complexType>
        <xs:complexContent>
          <xs:extension base="sml:keybase">
            <xs:attribute name="refer" type="xs:QName" use="optional"/>
          </xs:extension>
        </xs:complexContent>
      </xs:complexType>
    </xs:element>>

sml:keyref is supported in the appinfo of an xs:element.  

8.2.3 sml:unique

This element is used to specify a uniqueness constraint in some scope. The semantics are essentially the same as that for xs:unique but 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.

<xs:element name="unique" type="sml:keybase"/>

sml:unique is supported in the appinfo of an xs:element.  

8.2.4 sml:uri

Specifies a reference in URI scheme.

<xs:element name="uri" type="xs:anyURI"/>

This element must be used to specify references that use the URI scheme.

8.3 XPath functions

8.3.1 smlfn:deref

node-set deref(node-set)

This function takes a node-set of elements and attempts to resolve the references contained in the elements that have sml:ref="true".    The resulting node-set is the set of elements that are obtained by successfully resolving (or de-referencing) the  reference contained in each element in the input node-set for which sml:ref="true".  For example,

deref(/u:Universities/u:Students/u:Student)

will resolve the reference in element Student. The target of the reference must always be an element.

9. References

9.1 Normative

[SML-IF 1.1]
Service Modeling Language Interchange Format Version 1.1, Bhalchandra Pandit, Valentina Popescu, Virginia Smith, Editors. World Wide Web Consortium, 10 September 2008. This version of the Service Modeling Language Interchange Format specification is available at http://www.w3.org/TR/2008/WD-sml-if-20080110/. The latest version of the Service Modeling Language Interchange Format Version 1.1 specification is available at http://www.w3.org/TR/sml-if
[IETF RFC 2119]
Key words for use in RFCs to Indicate Requirement Levels, S. Bradner, Author. Internet Engineering Task Force, June 1999. Available at http://www.ietf.org/rfc/rfc2119.txt.
[ISO/IEC 19757-3]
Information technology ― Document Schema Definition Languages (DSDL) ― Part 3: Rule-based validation ― Schematron. International Organization for Standardization and International Electrotechnical Commission, 1 January 2006. Available at http://standards.iso.org/ittf/PubliclyAvailableStandards/c040833_ISO_IEC_19757-3_2006(E).zip
[XML]
Extensible Markup Language (XML) 1.0 (Fourth Edition), T. Bray, J. Paoli, C. M. Sperberg-McQueen, and E. Maler, Editors. World Wide Web Consortium, 10 February 1998, revised 16 August 2006. This version of the XML 1.0 Recommendation is http://www.w3.org/TR/2006/REC-xml-20060816. The latest version of XML 1.0 is available at http://www.w3.org/TR/REC-xml.
[XML Schema Structures]
XML Schema Part 1: Structures Second Edition, H. Thompson, D. Beech, M. Maloney, and N. Mendelsohn, Editors. World Wide Web Consortium, 2 May 2001, revised 28 October 2004. This version of the XML Schema Part 1 Recommendation is http://www.w3.org/TR/2004/REC-xmlschema-1-20041028. The latest version of XML Schema 1.0 Part 1 is available at http://www.w3.org/TR/xmlschema-1.
[XML Schema Datatypes]
XML Schema Part 2: Datatypes Second Edition, P. Byron and A. Malhotra, Editors. World Wide Web Consortium, 2 May 2001, revised 28 October 2004. This version of the XML Schema Part 2 Recommendation is http://www.w3.org/TR/2004/REC-xmlschema-2-20041028. The latest version of XML Schema 1.0 Part 2 is available at http://www.w3.org/TR/xmlschema-2.
[XPath]
XML Path Language (XPath) Version 1.0, J. Clark and S. DeRose, Editors. World Wide Web Consortium, 16 November 1999. This version of XML Path Language (XPath) Version 1.0 is http://www.w3.org/TR/1999/REC-xpath-19991116. The latest version of XML Path Language (XPath) Version 1.0 is available at http://www.w3.org/TR/xpath.
[XPointer]
XPointer Framework, P. Grosso, E. Maler, J. Marsh, and N. Walsh, Editors. World Wide Web Consortium, 25 March 2003. This version of the XPointer Framework Recommendation is http://www.w3.org/TR/2003/REC-xptr-framework-20030325/ The latest version of XPointer Framework is available at http://www.w3.org/TR/xptr-framework/.
[xmlns() Scheme]
XPointer xmlns() Scheme, S. DeRose, R. Daniel Jr., E. Maler, and J. Marsh, Editors. World Wide Web Consortium, 25 March 2003. This version of the XPointer xmlns() Scheme Recommendation is http://www.w3.org/TR/2003/REC-xptr-framework-20030325/ The latest version of XPointer xmlns() Scheme is available at http://www.w3.org/TR/xptr-xmlns/.
[xpointer() Scheme]
XPointer xpointer() Scheme, S. DeRose, E. Maler, and R. Daniel Jr., Editors. World Wide Web Consortium, 19 December 2002. This version of the XPointer xpointer() Scheme specification is http://www.w3.org/TR/2002/WD-xptr-xpointer-20021219/. The latest version of XPointer xpointer() Scheme is available at http://www.w3.org/TR/xptr-xpointer/.

9.2 Non-Normative

[Introduction to Schematron]
An Introduction to Schematron, Eddie Robertsson, Author. O'Reilly Media, Inc., 12 November 2003. Available at http://www.xml.com/pub/a/2003/11/12/schematron.html
[Improving Validation with Schematron]
Improving XML Document Validation with Schematron, Dare Obasanjo, Author. Microsoft Corporation, September 2004. Available at http://msdn2.microsoft.com/en-us/library/Aa468554.aspx
[XML Schema Primer]
XML Schema Part 0: Primer Second Edition, D. Fallside and P. Walmsley, Editors. World Wide Web Consortium, 2 May 2001, revised 28 October 2004. This version of the XML Schema Part 0 Recommendation is http://www.w3.org/TR/2004/REC-xmlschema-0-20041028. The latest version of XML Schema Part 0 is available at http://www.w3.org/TR/xmlschema-0.

A. Normative SML Schema

<?xml version="1.0" encoding="utf-8"?>

<!--
/*
 * Copyright © 2008 World Wide Web Consortium,
 *
 * (Massachusetts Institute of Technology, European Research Consortium for
 * Informatics and Mathematics, Keio University). All Rights Reserved. This
 * work is distributed under the W3C® Document License [1] in the hope that
 * it will be useful, but WITHOUT ANY WARRANTY; without even the implied
 * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 *
 * [1] http://www.w3.org/Consortium/Legal/2002/copyright-documents-20021231
 */
-->
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:sml="http://www.w3.org/2008/01/sml" targetNamespace="http://www.w3.org/2008/01/sml" elementFormDefault="qualified" blockDefault="#all" version="1.0" xml:lang="en" finalDefault="" attributeFormDefault="unqualified">
  
   <!--
      References
      ==========
  -->
   
  
   <!-- CONTEXT: To be used in any <xs:element> -->
   
  <xs:attribute name="ref" type="xs:boolean">
    <xs:annotation>
      <xs:documentation>
    Specifies if the element contains a reference
      </xs:documentation>
    </xs:annotation>
  </xs:attribute>
  
   <!-- CONTEXT: To be used in any <xs:element> -->
   
  <xs:attribute name="nilref" type="xs:boolean">
    <xs:annotation>
      <xs:documentation>
    Specifies that the reference element denotes a “null” reference. 
    To be used only on elements for which sml:ref="true".
      </xs:documentation>
    </xs:annotation>
  </xs:attribute>  
  
   <!-- CONTEXT: To be used in any <xs:element> -->
   
  <xs:attribute name="targetElement" type="xs:QName">
    <xs:annotation>
      <xs:documentation>
    A qualified name of an element in the
    referenced document.
      </xs:documentation>
    </xs:annotation>
  </xs:attribute>
  
   <!-- CONTEXT: To be used in any <xs:element>-->
   
  <xs:attribute name="targetRequired" type="xs:boolean">
    <xs:annotation>
      <xs:documentation>
    If true, requires the target element of the reference to
    exist in the model.
      </xs:documentation>
    </xs:annotation>
  </xs:attribute>
  
   <!-- CONTEXT: To be used in any <xs:element>-->
   
  <xs:attribute name="targetType" type="xs:QName">
    <xs:annotation>
      <xs:documentation>
    A qualified name of the type of the element in the
    referenced document.
      </xs:documentation>
    </xs:annotation>
  </xs:attribute>
  
   <!-- CONTEXT: To be used in any <xs:complexType>-->
   
  <xs:attribute name="acyclic" type="xs:boolean">
    <xs:annotation>
      <xs:documentation>
    If this attribute is set to true for a type D 
    then instances of D should not create any
    cycles in a model. More precisely, the directed graph whose
    edges represent instances of D, and whose nodes represent
    documents that contain the source or target elements for
    instances of D, must be acyclic.
      </xs:documentation>
    </xs:annotation>
  </xs:attribute>
  
  
   <!-- CONTEXT: To be used in <sch:assert>, <sch:report>
  and elements with textual content.
  This attribute is used to support string localization.
  It is used to define the translation location for 
  the text content of the containing element.-->
     
  <xs:attribute name="locid" type="xs:QName"/>
  
  
   <!-- CONTEXT: Represents a reference using the URI scheme. To be
       used as a child  element of elements for which
       sml:ref="true". -->
   
  <xs:element name="uri" type="xs:anyURI">
    <xs:annotation>
      <xs:documentation>
    References in URI scheme must be representend by this
    element.  
      </xs:documentation>
    </xs:annotation>
  </xs:element>

  
   <!--
      Uniqueness and Key constraints
      ==============================
  -->
   

  <xs:complexType name="keybase" mixed="false">
    <xs:sequence minOccurs="0">
      <xs:element name="selector" type="sml:selectorXPathType"/>
      <xs:element name="field" type="sml:fieldXPathType" maxOccurs="unbounded"/>
      <xs:any namespace="##other" minOccurs="0" maxOccurs="unbounded" processContents="lax"/>
    </xs:sequence>
    <xs:attribute name="name" type="xs:NCName"/>
    <xs:attribute name="ref" type="xs:QName"/>
    <xs:anyAttribute namespace="##other" processContents="lax"/>
  </xs:complexType>
  <xs:element name="key" type="sml:keybase"/>
  <xs:element name="unique" type="sml:keybase"/>
  <xs:element name="keyref">
    <xs:complexType mixed="false">
      <xs:complexContent>
    <xs:extension base="sml:keybase">
      <xs:attribute name="refer" type="xs:QName" use="optional"/>
    </xs:extension>
      </xs:complexContent>
    </xs:complexType>
  </xs:element>

  
   <!--
      Other Complex Types
      ==================
  -->
   

  <xs:complexType name="selectorXPathType" mixed="false">
    <xs:sequence>
      <xs:any namespace="##other" minOccurs="0" maxOccurs="unbounded" processContents="lax"/>
    </xs:sequence>
    <xs:attribute name="xpath" use="required">
      <xs:simpleType>
    <xs:restriction base="xs:string">
      
   <!-- The value MUST conform to the selector BNF grammar defined in
           section '4.4 Identity Constraints' in the SML specification.
      -->
   
    </xs:restriction>
      </xs:simpleType>
    </xs:attribute>
    <xs:anyAttribute namespace="##other" processContents="lax"/>
  </xs:complexType>

  <xs:complexType name="fieldXPathType" mixed="false">
    <xs:sequence>
      <xs:any namespace="##other" minOccurs="0" maxOccurs="unbounded" processContents="lax"/>
    </xs:sequence>
    <xs:attribute name="xpath" use="required">
      <xs:simpleType>
    <xs:restriction base="xs:string">
      
   <!-- The value MUST conform to the field BNF grammar defined in
           section '4.4 Identity Constraints' in the SML specification.
      -->
   
    </xs:restriction>
      </xs:simpleType>
    </xs:attribute>
    <xs:anyAttribute namespace="##other" processContents="lax"/>
  </xs:complexType>
</xs:schema>

B. Model Definition Document Sample (Non-Normative)

This model definition document sample illustrates the use of the following SML extensions:

  1. SML references

  2. key and keyref constraints

  3. User-defined constraints

<?xml version="1.0" encoding="utf-8"?>

<!--
/*
 * Copyright ©  World Wide Web Consortium,
 *
 * (Massachusetts Institute of Technology, European Research Consortium for
 * Informatics and Mathematics, Keio University). All Rights Reserved. This
 * work is distributed under the W3C® Document License [1] in the hope that
 * it will be useful, but WITHOUT ANY WARRANTY; without even the implied
 * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 *
 * [1] http://www.w3.org/Consortium/Legal/2002/copyright-documents-20021231
 */
-->
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:tns="http://example.org/SampleModel" xmlns:sml="http://www.w3.org/2008/01/sml" xmlns:smlfn="http://www.w3.org/2008/01/sml-function" xmlns:sch="http://purl.oclc.org/dsdl/schematron" targetNamespace="http://example.org/SampleModel" elementFormDefault="qualified" finalDefault="" blockDefault="" attributeFormDefault="unqualified">

  <xs:import namespace="http://www.w3.org/2008/01/sml"/>

  <xs:simpleType name="SecurityLevel">
    <xs:restriction base="xs:string">
      <xs:enumeration value="Low"/>
      <xs:enumeration value="Medium"/>
      <xs:enumeration value="High"/>
    </xs:restriction>
  </xs:simpleType>

  <xs:complexType name="Hostref" sml:acyclic="true" mixed="false">
    <xs:sequence>
      <xs:any namespace="##any" processContents="lax" minOccurs="0" maxOccurs="unbounded"/>
    </xs:sequence>
    <xs:anyAttribute namespace="##any" processContents="lax"/>
  </xs:complexType>

  
   <!-- This element represents the host operating system for
       an application. Note that the type of the referenced
       element must be OperatingSystemType or a derived type
       of OperatingSystemType -->
   
  <xs:element name="HostOSRef" type="tns:Hostref" sml:targetType="tns:OperatingSystemType"/>

  <xs:complexType name="ApplicationType" mixed="false">
    <xs:sequence>
      <xs:element name="Name" type="xs:string"/>
      <xs:element name="Vendor" type="xs:string"/>
      <xs:element name="Version" type="xs:string"/>
      <xs:element ref="tns:HostOSRef" minOccurs="0"/>
    </xs:sequence>
  </xs:complexType> 

  <xs:simpleType name="ProtocolType">
    <xs:list>
      <xs:simpleType>
	<xs:restriction base="xs:string">
	  <xs:enumeration value="TCP"/>
	  <xs:enumeration value="UDP"/>
	  <xs:enumeration value="SMTP"/>
	  <xs:enumeration value="SNMP"/>
	</xs:restriction>
      </xs:simpleType>
    </xs:list>
  </xs:simpleType>

  <xs:complexType name="GuestAppRefType" sml:acyclic="false" mixed="false">
    <xs:sequence>
      <xs:any namespace="##any" processContents="lax" minOccurs="0" maxOccurs="unbounded"/>
    </xs:sequence>
    <xs:anyAttribute namespace="##any" processContents="lax"/>
  </xs:complexType>
  
  <xs:element name="GuestAppRef" type="tns:GuestAppRefType" sml:targetType="tns:ApplicationType"/>

  <xs:complexType name="OperatingSystemType" mixed="false">
    <xs:sequence>
      <xs:element name="Name" type="xs:string"/>
      <xs:element name="FirewallEnabled" type="xs:boolean"/>
      <xs:element name="Protocol" type="tns:ProtocolType"/>
      
   <!-- The following element represents the applications hosted by
	   operating system -->
   
      <xs:element name="Applications" minOccurs="0">
	<xs:complexType mixed="false">
	  <xs:sequence>
	    <xs:element ref="tns:GuestAppRef" maxOccurs="unbounded"/>
	  </xs:sequence>
	</xs:complexType>
      </xs:element>
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name="OSRefType" sml:acyclic="false" mixed="false">
    <xs:sequence>
      <xs:any namespace="##any" processContents="lax" minOccurs="0" maxOccurs="unbounded"/>
    </xs:sequence>
    <xs:anyAttribute namespace="##any" processContents="lax"/>
  </xs:complexType>

  <xs:element name="OSRef" type="tns:OSRefType" sml:targetType="tns:OperatingSystemType"/>

  <xs:complexType name="WorkstationType" mixed="false">
    <xs:sequence>
      <xs:element name="Name" type="xs:string"/>
      <xs:element ref="tns:OSRef"/>
      <xs:element name="Applications" minOccurs="0">
	<xs:complexType mixed="false">
	  <xs:sequence>
	    <xs:element ref="tns:GuestAppRef" maxOccurs="unbounded"/>
	  </xs:sequence>
	</xs:complexType>
      </xs:element>
    </xs:sequence>
  </xs:complexType> 

  <xs:element name="Workstation" type="tns:WorkstationType">
    <xs:annotation>
      <xs:appinfo>
	<sch:schema>
	  <sch:ns prefix="sm" uri="SampleModel"/>
	  <sch:ns prefix="smlfn" uri="http://www.w3.org/2008/01/sml-function"/>
	  <sch:pattern id="OneHostOS">
	    
   <!-- The constraints in the following rule are evaluated  
		 For all instances of the Workstation global element-->
   
	    <sch:rule context=".">
	      
   <!-- define a named variable - MyApplications -
		   for use in test expression-->
   
	      <sch:let name="MyApplications" value="smlfn:deref(sm:Applications/sm:GuestAppRef)"/>
	      <sch:assert test="count($MyApplications)=count($MyApplications/sm:HostOSRef)">
		Each application in workstation
		<sch:value-of select="string(sm:Name)"/>
		must be hosted on an operating system
	      </sch:assert>
	    </sch:rule>
	  </sch:pattern>
	</sch:schema>

	
   <!-- In a workstation, (Vendor,Name,Version) is the key for
	     guest applications -->
   
	<sml:key name="GuestApplicationKey">
	  <sml:selector xpath="smlfn:deref(tns:Applications/tns:GuestAppRef)"/>
	  <sml:field xpath="tns:Vendor"/>
	  <sml:field xpath="tns:Name"/>
	  <sml:field xpath="tns:Version"/>
	</sml:key>

	
   <!-- In a workstation, Name is the key for operating system -->
   
	<sml:key name="OSKey">
	  <sml:selector xpath="smlfn:deref(tns:OSRef)"/>
	  <sml:field xpath="tns:Name"/>
	</sml:key>
	
	
   <!-- In a workstation, the applications hosted by the
	     referenced operatinsystem must be a subset of the
	     applications in the workstation -->
   
	<sml:keyref name="OSGuestApplication" refer="tns:GuestApplicationKey">
	  <sml:selector xpath="smlfn:deref(tns:OSRef)/tns:Applications/tns:GuestAppRef"/>
	  <sml:field xpath="tns:Vendor"/>
	  <sml:field xpath="tns:Name"/>
	  <sml:field xpath="tns:Version"/>   
	</sml:keyref>

	
   <!-- In a workstation, the host operating system of guest
	     applications must be a subset of the operating system in
	     the workstation -->
   
	<sml:keyref name="ApplicationHostOS" refer="tns:OSKey">
	  <sml:selector xpath="smlfn:deref(tns:Applications/tns:GuestAppRef)/tns:HostOSRef"/>
	  <sml:field xpath="tns:Name"/>
	</sml:keyref>
      </xs:appinfo>
    </xs:annotation>
  </xs:element>

  <xs:element name="SecureWorkstation" type="tns:WorkstationType">
    <xs:annotation>
      <xs:appinfo>
	<sch:schema>
	  <sch:ns prefix="sm" uri="SampleModel"/>
	  <sch:ns prefix="smlfn" uri="http://www.w3.org/2008/01/sml-function"/>
	  <sch:pattern id="SecureApplication">
	    <sch:rule context="sm:Applications/sm:Application">
	      <sch:report test="smlfn:deref(.)[sm:SecurityLevel!='High']">
		Application <sch:value-of select="string(sm:Name)"/>
		from <sch:value-of select="string(sm:Vendor)"/>
		does not have high security level.
	      </sch:report>
	      <sch:assert test="smlfn:deref(.)[sm:Vendor='TrustedVendor']">
		A secure workstation can only contain
		applications from TrustedVendor.
	      </sch:assert>
	    </sch:rule>
	  </sch:pattern>
	</sch:schema>
      </xs:appinfo>
    </xs:annotation>
  </xs:element>

</xs:schema>

C. SML References Sample (Non-Normative)

The following example illustrates the use of SML references. Consider the following schema fragment:

<xs:element name="EnrolledCourse">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="Name" type="xs:string"/>
        <xs:element name="Grade" type="xs:string"/>
        <xs:any namespace="##any" minOccurs="0"
                maxOccurs="unbounded" processContents="lax"/>
      </xs:sequence>
      <xs:anyAttribute namespace="##any" processContents="lax"/>
    </xs:complexType>
</xs:element>

<xs:complexType name="StudentType">
    <xs:sequence>
      <xs:element name="ID" type="xs:string"/>
      <xs:element name="Name" type="xs:string"/>
      <xs:element name="EnrolledCourses" minOccurs="0">
        <xs:complexType>
          <xs:sequence>
            <xs:element ref="tns:EnrolledCourse"
                        maxOccurs="unbounded"/>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
    </xs:sequence>
</xs:complexType>

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 reference elements as shown below:

<Student xmlns="http://www.university.example.org/ns"
         xmlns:sml="http://www.w3.org/2008/01/sml">
  <ID>1000</ID>
  <Name>John Doe</Name>
  <EnrolledCourses>
    <EnrolledCourse sml:ref="true">
      <Name>PHY101</Name>
      <Grade>A</Grade>
      <sml:uri>
        http://www.university.example.org/Universities/MIT/Courses.xml
		#xmlns(u=http://www.university.example.org/ns)
		xpointer(/u:Courses/u:Course[u:Name='PHY101'])
      </sml:uri>
    </EnrolledCourse>
    <EnrolledCourse sml:ref="false">
      <Name>MAT100</Name>
      <Grade>B</Grade>
      <sml:uri>
        http://www.university.example.org/Universities/MIT/Courses.xml
		#xmlns(u=http://www.university.example.org/ns)
		xpointer(/u:Courses/u:Course[u:Name='MAT100'])
      </sml:uri>
    </EnrolledCourse>
    <EnrolledCourse>
      <Name>SocialSkills</Name>
      <Grade>F</Grade>
    </EnrolledCourse>
  </EnrolledCourses>
</Student>

The first EnrolledCourse element in the above example is a reference element since it specifies sml:ref="true". It uses the SML URI scheme to target the element for course  PHY101. The second and third EnrolledCourse elements are not reference elements; the second element specifies sml:ref="false" and the third element does not specify the sml:ref attribute. Note that the second element has a child element that contains a reference scheme referring to course MAT100, but this reference will be ignored since sml:ref="false" for the second element.

An EnrolledCourse reference element 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 reference):

<Student xmlns="http://www.university.example.org/ns"
         xmlns:sml="http://www.w3.org/2008/01/sml">
  <ID>1000</ID>
  <Name>John Doe</Name>
  <EnrolledCourses>
    <EnrolledCourse sml:ref="true" sml:nilref="true">
      <Name>PHY101</Name>
      <Grade>A</Grade>
    </EnrolledCourse>
    <EnrolledCourse sml:ref="false">
      <Name>MAT100</Name>
      <Grade>B</Grade>
      <sml:uri>
        http://www.university.example.org/Universities/MIT/Courses.xml
		#xmlns(u=http://www.university.example.org/ns)
		xpointer(/u:Courses/u:Course[u:Name='MAT100'])
      </sml:uri>
    </EnrolledCourse>
    <EnrolledCourse>
      <Name>SocialSkills</Name>
      <Grade>F</Grade>
    </EnrolledCourse>
  </EnrolledCourses>
</Student>

In the above example, first reference EnrolledCourse defines the sml:nilref="true" attribute which marks this as a null 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.

D. SML URI Scheme Sample (Non-Normative)

The following example illustrates the use of SML URI scheme. Consider the case where all courses offered by MIT are stored in a single XML document – 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)

<Student xmlns="http://www.university.example.org/ns">
  <ID>1000</ID>
  <Name>John Doe</Name>
  <EnrolledCourses>
    <EnrolledCourse sml:ref="true" xmlns:u="http://www.university.example.org/ns">
      <sml:uri>
        http://www.university.example.org/Universities/MIT/Courses.xml
		#smlxpath1(/u:Courses/u:Course[u:Name='PHY101'])
      </sml:uri>
    </EnrolledCourse>
  </EnrolledCourses>
</Student>

A reference element can also be used to reference an element in its own document. To see this consider the following instance document

<University xmlns="http://www.university.example.org/ns">
  <Name>MIT</Name>
  <Courses>
    <Course>
      <Name>PHY101</Name>
    </Course>
    <Course>
      <Name>MAT200</Name>
    </Course>
  </Courses>
  <Students>
    <Student>
      <ID>123</ID>
      <Name>Jane Doe</Name>
      <EnrolledCourses>
        <EnrolledCourse sml:ref="true" xmlns:u="http://www.university.example.org/ns">
          <sml:uri>
            #smlxpath1(/u:University/u:Courses/u:Course[u:Name='MAT200'])
          </sml:uri>
        </EnrolledCourse>
      </EnrolledCourses>
    </Student>
  </Students>
</University>

Here, the EnrolledCourse element for the student Jane Doe references the Course element for MAT200 in the same document.

E. SML Identity Constraints Sample (Non-Normative)

The following example will be used to illustrate the sml:key, sml:unique, and sml:keyref constraints across SML references. This example consists of 3 schema documents, university.xsd that contains the currently enrolled students, active courses, and other university information, students.xsd that contains information on all current and past students, and courses.xsd that contains information on the students currently enrolled in that course. The following snippets represent pieces of the definition documents.

  <!-- from university.xsd -->
  <xs:complexType name="StudentRefType">
    <!-- SML reference to a Student -->
    <xs:sequence>
      <xs:any namespace="##any" processContents="lax" minOccurs="0" maxOccurs="unbounded"/>
    </xs:sequence>
    <xs:anyAttribute namespace="##any" processContents="lax"/>
  </xs:complexType>
  
  <xs:element name="Student" type="StudentRefType"/>

  <xs:complexType name="CourseRefType">
    <!-- SML reference to a Course -->
    <xs:sequence>
      <xs:any namespace="##any" processContents="lax" minOccurs="0" maxOccurs="unbounded"/>
    </xs:sequence>
    <xs:anyAttribute namespace="##any" processContents="lax"/>
  </xs:complexType>

  <xs:element name="Course" type="CourseRefType"/>

  <xs:complexType name="UniversityType">
    <xs:sequence>
      <xs:element name="Name" type="xs:string"/>
      <xs:element name="Students" minOccurs="0">
        <xs:complexType>
          <xs:sequence>
            <xs:element ref="Student" maxOccurs="unbounded"/>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
      <xs:element name="Courses" minOccurs="0">
        <xs:complexType>
          <xs:sequence>
            <xs:element ref="Course" maxOccurs="unbounded"/>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
    </xs:sequence>
  </xs:complexType>


  <!-- from students.xsd -->
  <xs:complexType name="EnrolledCourseRefType">
    <!-- SML reference to a Course -->
    <xs:sequence>
      <xs:element name="Grade" type="xs:string"/>
      <xs:any namespace="##any" processContents="lax" minOccurs="0" maxOccurs="unbounded"/>
    </xs:sequence>
    <xs:anyAttribute namespace="##any" processContents="lax"/>
  </xs:complexType>

  <xs:element name="EnrolledCourse" type="EnrolledCourseRefType"/>

  <xs:complexType name="StudentType">
    <xs:sequence>
      <xs:element name="ID" type="xs:string"/>
      <xs:element name="SSN" type="xs:string" minOccurs="0"/>
      <xs:element name="Name" type="xs:string"/>
      <xs:element name="EnrolledCourses" minOccurs="0">
        <xs:complexType>
          <xs:sequence>
            <xs:element ref="EnrolledCourse" maxOccurs="unbounded"/>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
    </xs:sequence>
  </xs:complexType>

  <xs:element name="Students">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="Student" type="StudentType"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>


  <!-- from courses.xsd -->
  <xs:complexType name="CourseType">
    <xs:sequence>
      <xs:element name="Name" type="xs:string"/>
      <xs:element name="EnrolledStudents" minOccurs="0">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="EnrolledStudent" maxOccurs="unbounded">
              <xs:complexType>
                <xs:sequence>
                  <xs:element name="StudentID" type="xs:string"/>
                </xs:sequence>
              </xs:complexType>
            </xs:element>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
    </xs:sequence>
  </xs:complexType>

  <xs:element name="Courses">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="Course" type="CourseType"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>

sml:key and sml:unique

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:

  <xs:element name="University" type="tns:UniversityType">
    <xs:annotation>
      <xs:appinfo>
        <sml:key name="StudentIDisKey">
           <sml:selector xpath="smlfn:deref(tns:Students/tns:Student)/tns:ID"/>
           <sml:field xpath="."/>  
        </sml:key>  
      </xs:appinfo>
    </xs:annotation>
  </xs:element>

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:

  <xs:element name="University" type="tns:UniversityType">
    <xs:annotation>
      <xs:appinfo>
        <sml:unique name="StudentSSNisUnique">
           <sml:selector xpath="smlfn:deref(tns:Students/tns:Student)"/>
           <sml:field xpath="tns:SSN"/>  
        </sml:unique>  
    </xs:appinfo>
  </xs:annotation>
</xs:element>

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:

  <xs:element name="PrivateUniversity" type="tns:UniversityType">
    <xs:annotation>
      <xs:appinfo>
        <sml:unique ref="tns:StudentSSNisUnique"/>
      </xs:appinfo>
    </xs:annotation>
  </xs:element>

In the above example, the PrivateUniversity element declaration specifies the StudentSSNisUnique unique constraint by referencing its name in the University element declaration.

sml:keyref

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:

  <xs:element name="University" type="tns:UniversityType">
    <xs:annotation>
      <xs:appinfo>
        <sml:key name="StudentIDisKey">
           <sml:selector xpath="smlfn:deref(tns:Students/tns:Student)"/>
           <sml:field xpath="tns:ID"/>  
        </sml:key>  
        <sml:keyref name="CourseStudents" refer="tns:StudentIDisKey">
           <sml:selector xpath="smlfn:deref(tns:Courses/tns:Course)/
                                   tns:EnrolledStudents/tns:EnrolledStudent"/>
           <sml:field xpath="tns:ID"/>
        </sml:keyref>
      </xs:appinfo>
    </xs:annotation>
  </xs:element>

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.  

F. Localization and Variable Substitution Sample (Non-Normative)

In the following example, the sml:locid attribute is used to define the translation information for the Schematron sch:assert error message:

<sch:schema xmlns:sch="http://purl.oclc.org/dsdl/schematron"
  xmlns:lang="http://www.university.example.org/translation/">
  
   <sch:ns prefix="u" uri="http://www.university.example.org/ns" />
   <sch:ns prefix="smlfn" uri="http://www.w3.org/2008/01/sml-function"/>

          <sch:pattern id="StudentPattern”>
          
            <sch:rule context="u:Students/u:Student">
              <sch:assert test="smlfn:deref(.)[starts-with(u:ID,'99')]"
                          sml:locid="lang:StudentIDErrorMsg">
                      The specified ID <sch:value-of select="string(u:ID)"/> does not begin with 99.
              </sch:assert>
            </sch:rule>
</sch:schema>

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:

<xmlns:lang="http://www.university.example.org/translation/">

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 dependant how the processor 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/:

  1. http://www.university.example.org/translation/fr_lang.txt file contains the French translation of the sch:assert message.

  2. 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:

StudentIDErrorMsg = L'identifieur specifie <sch:value-of select="string(u:ID)"/> ne commence pas par 99.

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:

StudentIDErrorMsg = Das angegebene Attributkennzeichen ID <sch:value-of select="string(u:ID)"/> beginnt nicht mit 99.

This example demonstrates how localization can be applied to a Schematron rule with the purpose of making the Schematron rule available to consumers using different languages. Summarized below are the benefits resulting from using the sml:locid localization support:

  1. The Schematron rule is language agnostic in the sense that the author does not have to be aware of the locale of a potential consumer. The Schematron rule is defined generically, to be consumed by any producer for which a translation file is made available at the location defined by the sml:locid {namespace name} URI.

  2. 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.

Variable substitution support

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:

The specified ID <sch:value-of select="string(u:ID)"/> does not begin with 99.

This is not possible since the translated message contains the context where the rule has been applied:

<sch:value-of select="string(u:ID)"/>

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 these messages:

StudentIDErrorMsg = L'identifieur specifie <sch:value-of select="string(u:ID)"/> ne commence pas par 99.
StudentIDErrorMsg = Das angegebene Attributkennzeichen ID <sch:value-of select="string(u:ID)"/> beginnt nicht mit 99.

, the translation files should contain messages where the context of the Schematron rule is being replaced with a generic variable:

StudentIDErrorMsg = L'identifieur specifie <sch:value-of select="string($var)"/> ne commence pas par 99.
StudentIDErrorMsg = Das angegebene Attributkennzeichen ID <sch:value-of select="string($var)"/> beginnt nicht mit 99.

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:

<sch:schema xmlns:sch="http://purl.oclc.org/dsdl/schematron"
  xmlns:lang="http://www.university.example.org/translation/">
  
   <sch:ns prefix="u" uri="http://www.university.example.org/ns" />
   <sch:ns prefix="smlfn" uri="http://www.w3.org/2008/01/sml-function"/>

          <sch:pattern id="StudentPattern”>
          
            <sch:rule context="u:Students/u:Student">
              <sch:assert test="smlfn:deref(.)[starts-with(u:ID,'99')]"
                          sml:locid="lang:StudentIDErrorMsg">
                          
			<xsl:variable name="var” select=”u:ID” />                          
                      The specified ID <sch:value-of select="string($var)"/> does not begin with 99.
              </sch:assert>
            </sch:rule>
</sch:schema>

The error message in sch:assert and the localization identifier lang:StudentIDErrorMsg can now be reused in contexts other than u:Students/u:Student.

G. Acknowledgements (Non-Normative)

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), Jordan Boucher (Sun Microsystems, Inc.), Pratul Dublish (Microsoft Corporation), Zulah Eckert (BEA Systems, Inc.), Sandy Gao (IBM Corporation), Philippe Le Hégaret (W3C/MIT), Paul Lipton (CA), James Lynn (HP), Kumar Pandit (Microsoft Corporation), Valentina Popescu (IBM Corporation), Virginia Smith (HP), Michael Sperberg-McQueen (W3C/MIT), Kirk Wilson (CA).