Please refer to the errata for this document, which may include some normative corrections.
This document is also available in these non-normative formats: XML.
See also translations.
Copyright © 2009 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
This specification defines the Service Modeling Language, Version 1.1 (SML) used to model complex services and systems, including their structure, constraints, policies, and best practices. SML uses XML Schema and Schematron.
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 12 May 2009 W3C Recommendation of the Service Modeling Language, Version 1.1 specification. This document has been developed by the Service Modeling Language (SML) Working Group, which is a part of the Extensible Markup Language (XML) Activity.
Comments on this document are welcome via the Working Group’s public mailing list (public archive). An implementation report is available.
The design of SML has been widely reviewed and satisfies the Working Group's technical requirements. Only minor editorial changes have been made since the 12 February 2009 Proposed Recommendation.
This document has been reviewed by W3C Members, by software developers, and by other W3C groups and interested parties, and is endorsed by the Director as a W3C Recommendation. It is a stable document and may be used as reference material or cited from another document. W3C's role in making the Recommendation is to draw attention to the specification and to promote its widespread deployment. This enhances the functionality and interoperability of the Web.
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.
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 SML
Reference Definitions
4.1.1 SML Reference
4.1.2 Null SML Reference
4.1.3 Unresolved SML Reference
4.1.4 SML Reference Target
4.2 SML
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 SML References
4.2.6 Deterministic Evaluation of SML
Constraints
4.2.7 smlfn:deref() XPath Extension
Function
4.3 SML
Reference Schemes
4.3.1 SML URI Reference Scheme
4.3.1.1
smlxpath1() scheme
5. SML Constraints
5.1 Constraints on SML
References
5.1.1 sml:acyclic
5.1.1.1
SML Constraint
Construction
5.1.1.2
Schema Component
Rules
5.1.1.3
Instance Validity
Rules
5.1.2 Constraints on SML Reference
Targets
5.1.2.1
SML Constraint
Construction
5.1.2.2
Schema Component
Rules
5.1.2.3
Instance Validity
Rules
5.1.3 SML Reference Constraints Summary
(Non-Normative)
5.2 SML
Identity Constraints
5.2.1 Syntax and
Semantics
5.2.1.1
SML Constraint
Construction
5.2.1.2
Schema
Component Rules
5.2.1.3
Instance
Validity Rules
5.3 Valid Restriction of SML
Constraint Values
5.4 SML Constraints and
Complex Type Derivation
5.4.1 Overview of SML
Constraint Processing and Complex Type Derivation
5.4.2 Formal Definition
5.4.2.1
Properties
5.4.2.2
SML Constraint
Construction
5.4.2.3
Instance Validity
Rules
6. Rules
6.1 Informal Description
(Non-Normative)
6.2 Rule
Support
6.3 Rules
Associated with Schema Components
6.3.1 SML Rule Construction
6.3.2 Schema Component Rules
6.3.3 Instance Validity Rules
6.4 Rules Authored in Rule
Documents
6.4.1 Rule Binding
7. Localization of Natural
Language Messages
7.1 Variable Substitution
8. Conformance Criteria
9. SML Extensions Reference
(Non-Normative)
9.1 Attributes
9.1.1 sml:acyclic
9.1.2 sml:ref
9.1.3 sml:nilref
9.1.4 sml:targetElement
9.1.5 sml:targetRequired
9.1.6 sml:targetType
9.1.7 sml:locid
9.2 Elements
9.2.1 sml:key
9.2.2 sml:keyref
9.2.3 sml:unique
9.2.4 sml:uri
9.3 XPath
functions
9.3.1 smlfn:deref
10. References
10.1 Normative
10.2 Non-Normative
A. Normative SML
Schema
B. Model Definition
Document Sample (Non-Normative)
C. SML References Sample
(Non-Normative)
D. SML URI Reference
Scheme Sample (Non-Normative)
E. SML Identity Constraints
Sample (Non-Normative)
F. Localization and Variable
Substitution Samples (Non-Normative)
G. Acknowledgements
(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.
Models focus on capturing all invariant aspects of a service/system that must be maintained for the service/system to function properly.
Models represent a powerful mechanism for validating changes before applying the changes to a service/system. Also, when changes happen in a running service/system, they can be validated against the intended state described in the model. The actual service/system and its model together enable a self-healing service/system ― the ultimate objective. Models of a service/system must necessarily stay decoupled from the live service/system to create the control loop.
Models are units of communication and collaboration between designers, implementers, operators, and users; and can easily be shared, tracked, and revision controlled. This is important because complex services are often built and maintained by a variety of people playing different roles.
Models drive modularity, reuse, and standardization. Most real-world complex services and systems are composed of sufficiently complex parts. Reuse and standardization of services/systems and their parts is a key factor in reducing overall production and operation cost and in increasing reliability.
Models enable increased automation of management tasks. Automation facilities exposed by the majority of services/systems today could be driven by software ― not people ― both for reliable initial realization of a service/system as well as for ongoing lifecycle management.
A model in SML is realized as a set of interrelated XML documents. The XML documents contain information about the parts of a service, as well as the constraints that each part must satisfy for the service to function properly. Constraints are captured in two ways:
Schemas ― these are constraints on the structure and content of the documents in a model. SML uses XML Schema [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.
Rules ― are Boolean expressions that constrain the structure and content of documents in a model. SML uses 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, Schematron usage in SML, as well as the process of model validation. It is assumed that the reader is familiar with XML Schema and Schematron.
SML scenarios require several features that either do not exist or are not fully supported in XML Schema. These features can be classified as follows:
SML references – XML documents introduce boundaries
across content that needs to be treated as a unit. XML Schema does
not have any support for references that cross documents, although
it does support references to elements in the same document through
xs:ID
, xs:IDREF
, xs:key
and
xs:keyref
. References between elements defined in
separate SML 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.
Rules – XML Schema does not support a language for defining arbitrary constraints on the structure and content of XML documents. SML uses Schematron to express assertions on the structure and content of XML documents.
XML Schema supports two forms of extension: "attributes in different namespace" and "application information elements"; both forms are used by SML extensions.
The keywords "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].
This specification uses the Augmented Backus-Naur Form (ABNF) notation [RFC 2234].
This specification follows the same conventions for schema components as those used in the XML schema specification [XML Schema Structures]. That is, references to properties of schema components, such as {example property}, are links to the relevant definition, set off with curly braces. References to properties of information items as defined in [XML Information Set], such as [children], are notated as links to the relevant section thereof, set off with square brackets.
This specification refers to terms such as XML document, element, attribute, etc. for the sake of brevity. The alternative would be to use terms like "XML document or a Synthetic Infoset", "element information item", "attribute information item", etc. at each place. This would make the specification excessively verbose without adding to or changing the meaning of the existing text. The use of the concise terms is not intended to exclude other XML representations. The concepts defined in this specification apply to all forms of XML representations.
The content of this specification is normative except for sections or texts that are explicitly marked as non-normative. If a section is marked as non-normative, then all contained sub-sections are non-normative, even if they are not explicitly marked as such. All notes are non-normative unless otherwise specified.
The following terms are used in this specification. They are listed here in alphabetical order.
A well-formed XML document, as defined in [XML].
An implementation-defined feature or behavior may vary among model processors; the precise behavior is not specified by this specification but MUST be specified by the implementor of each model processor.
An implementation-dependent feature or behavior may vary among model processors; the precise behavior is not specified by this or any other W3C specification and is not required to be specified by the implementor for any particular implementation.
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.
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 model validation.
The subset of documents in a model that describes the structure and content of the modeled entities.
A model processor is an embodiment that processes a conforming SML model using, in whole or in part, semantics defined by this specification.
Model validation is the process of determining whether or not a model is both conforming and valid. [8. Conformance Criteria]
A model validator is a model processor capable of performing model validation.
A rule is a boolean expression that constrains the structure and content of a set of documents in a model.
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 document and 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.
A rule document is a model definition document consisting of Schematron constraints.
A schema document is a model definition document that conforms to the XML Schema specification [XML Schema Structures] definition of a schema document.
The information contained within a single
sch:schema
element.
An SML Reference is an element with an sml:ref attribute whose value is "true".
Note:
Conceptually, an SML reference is used to signal a link from one element in an SML model to another element in the same model.
An SML Reference Scheme is a set of rules defining the syntax used to create an instance of the reference scheme in the context of an SML reference, plus a set of rules for resolving an instance of the reference scheme to its target. Whenever "reference scheme" occurs in this specification, it should be assumed to mean "SML reference scheme" unless otherwise noted. Despite similar names, the term SML reference scheme is unrelated to XPointer schemes and URI schemes.
An element in a model to which an SML reference resolves is called the target of that SML reference.
A target-complete identifier is a URI or IRI that contains all the information required to locate the target of an SML reference. It is a consequence of this definition that a target-complete identifier cannot be a relative URI/IRI.
Table 2-1 lists XML namespaces that are used in this specification. The choice of any namespace prefix is arbitrary and not semantically significant.
Prefix | XML Namespace | Specification(s) |
---|---|---|
sml |
http://www.w3.org/ns/sml |
This specification |
smlfn |
http://www.w3.org/ns/sml-function |
This specification |
xs |
http://www.w3.org/2001/XMLSchema |
[XML Schema Structures, XML Schema Datatypes] |
sch |
http://purl.oclc.org/dsdl/schematron |
[ISO/IEC 19757-3] |
Other specifications on which this one depends are listed in [Normative-References].
Support for SML references in an SML model includes:
The ability to use multiple SML reference schemes for an SML reference.
An extensibility mechanism allowing new SML reference schemes to be defined.
Constraints on the type of a referenced element.
The ability to define key, unique, and key reference constraints across SML references.
Model validators MUST support SML references as defined by this specification.
Appendix C. SML References Sample has an example that shows how SML references are defined and used.
An element information item in an SML model instance document is as an SML reference if and only if it has an attribute information item for which all of the following is true:
Its [local
name] is ref
Its [namespace
name] is http://www.w3.org/ns/sml
Its [normalized
value], after whitespace normalization using
collapse
following schema rules, is either
"true"
or "1"
.
Note:
This mechanism enables schema-less identification of SML references; i.e., SML references can be identified without relying on the Post Schema Validation Infoset (PSVI). [XML Schema Structures]
It is implementation-defined whether model processors that are not also model validators use the XML Infoset [XML Information Set] or the Post Schema Validation Infoset (PSVI) [XML Schema Structures] for SML reference identification.
Note:
SML model validators must use PSVI to identify SML references. See 8. Conformance Criteria.
An SML reference is considered to be an instance of a specific SML reference scheme if it can be identified as such according to that SML reference scheme's rules. See 4.3 SML Reference Schemes. An SML reference MAY be an instance of multiple SML reference schemes.
Although its normative definition allows several syntaxes to be
used to identify an SML reference, for the sake of brevity and
consistency, the rest of this specification uses
sml:ref="true"
to denote an SML reference in examples
and text.
The following example shows an SML reference that is an instance of the SML URI Reference scheme.
<RefElement sml:ref="true"> <sml:uri>targetDocument.xml</sml:uri> </RefElement>
An SML reference is null if and only if it has an attribute information item for which all of the following is true
Its [local
name] is nilref
Its [namespace
name] is http://www.w3.org/ns/sml
Its [normalized
value] after whitespace normalization using
collapse
following schema rules, is either
"true"
or "1"
.
It is a consequence of the preceding that this specification
assigns no meaning to the sml:nilref
attribute when it
is used on an element that is not an SML reference. Model
validators MAY choose to warn their
invokers should they detect this condition in a document.
The following example shows a null SML reference.
<RefElement sml:ref="true" sml:nilref="true"> <sml:uri>targetDocument.xml</sml:uri> </RefElement>
Note:
sml:nilref
may be useful in the case where the
schema author defines a complex type specifying
sml:ref="true"
with a fixed value of "true", but the
instance author wants to signal the absence of a target.
It is implementation-defined whether model processors that are not also model validators use the XML Infoset [XML Information Set] or the Post Schema Validation Infoset (PSVI) [XML Schema Structures] to identify null SML references.
Note:
SML model validators must use PSVI to identify null SML references. See 8. Conformance Criteria.
An SML reference is unresolved if and only if all of the following is true:
It is a non-null SML reference.
None of the reference schemes, which the SML reference is recognized as using, resolves to an element in the model.
Note:
The notion of unresolved reference is context-dependent. That is, different model processors, based on the set of SML reference schemes they understand and which are used in the model they process, may consider different SML references to be unresolved.
The following example shows an unresolved SML reference
(assuming that the document dummy.xml
does not exist
in the model).
<RefElement sml:ref="true"> <sml:uri>dummy.xml</sml:uri> </RefElement>
The element node that a non-null SML reference resolves to is its target. The target of an SML reference MUST be part of the same SML model as the SML reference. Null SML references have no target.
The method of determining which documents are part of an SML model is implementation-defined.
Note:
For example, an SML model may consist of documents listed in a configuration file or an SML model could be construed as the transitive closure of documents referred to by any SML references starting from a set of documents known to be in the model.
The following example shows an SML reference that targets the
second Course
child element of the root element of the
document target.xml
.
<RefElement sml:ref="true" xmlns:e="urn:example"> <sml:uri>target.xml#smlxpath1(e:Course[2])</sml:uri> </RefElement> document 'target.xml': ---------------------- <Courses xmlns="urn:example"> <Course> <Name>PHY101</Name> <Grade>A</Grade> </Course> <Course> <Name>MAT101</Name> <Grade>A</Grade> </Course> </Courses>
Model validators MUST attempt to resolve an SML reference using all the reference schemes of which the SML reference is recognized as an instance.
Every non-null SML reference MUST target at most one element in a model. This means that each recognized reference scheme used in the SML reference MUST NOT resolve to more than one target.
The following example shows an SML reference that violates the at-most-one-target rule.
<RefElement sml:ref="true" xmlns:e="urn:example"> <sml:uri>target.xml#smlxpath1(e:Course)</sml:uri> </RefElement> document 'target.xml': ---------------------- <Courses xmlns="urn:example"> <Course> <Name>PHY101</Name> <Grade>A</Grade> </Course> <Course> <Name>MAT101</Name> <Grade>A</Grade> </Course> </Courses>
If a non-null SML reference is an instance of multiple reference schemes, all recognized reference schemes MUST resolve to the same target or they all MUST be unresolved.
To determine if two targets are the same or different, model validators MUST obey the following rules.
If both of the following are true, then a model validator MUST consider both targets to be the same.
The definition of the reference scheme(s) specifies how URIs are transformed to target-complete identifiers.
The two target-complete identifiers are identical using a case-sensitive, codepoint-by-codepoint comparison.
Otherwise, 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.
For all other cases, it is implementation-defined whether to treat the targets as the same or not.
A null SML reference is an explicit declaration of intent by the document author that the target of the SML reference does not exist. If an SML reference is recognized as null, then model processors MUST NOT attempt to recognize any reference schemes used in it.
Each non-null SML reference MUST satisfy all of the following conditions in order to be able to deterministically evaluate SML constraints and rules associated with it.
The reference must have at most one target. [4.2.1 At Most One Target]
The reference MUST be consistent. [4.2.2 Consistent References]
The deref()
function takes a node set of elements
and returns a node set consisting of element nodes corresponding to
the elements referenced by the input node set. In particular,
for each SML reference R in the input node set the output node set
contains at most one element node.
Let I = input node set; that is, the set of nodes passed to the
deref()
function.
Let O = output node set; that is, the set of nodes returned by
the deref()
function.
The behavior of deref()
function MUST satisfy the following constraints:
For each SML reference R in the input node set I:
If the implementation recognizes no SML reference scheme used in the SML reference R, then no element is added to O.
If the implementation recognizes R as an instance of N supported
reference schemes, then deref()
is not required to
attempt to resolve all N schemes. Its behavior in this case is
implementation-defined and the set of reference schemes that are
actually attempted may be any subset of the recognized schemes.
This is subject to the following constraints:
If deref() doesn't attempt to resolve any reference scheme or if none of the attempted reference schemes resolves, then no element is added to O.
If at least one of the attempted reference schemes resolves to more than one target element, then 0 or 1 of the targets is added to O.
If one attempted reference scheme resolves to a target different from the target resolved by another attempted reference scheme, then 0 or 1 of the targets is added to O.
If one attempted reference scheme resolves and another doesn't, then 0 or 1 of the targets is added to O.
If none of the above is true (that is, all attempted reference schemes resolve to the same one and only one target element, call it T), then one target element (namely, T) is added to O, if it does not already exist in O.
Note:
The above describes the behavior required for a general XPath 1.0 deref() library function, and as such exhibits several significant differences from the behavior required to validate SML references during model validation. First, it can be used to successfully process instance documents whose SML model validity is unknown or invalid, although the results in this case may not be interoperable. Second, since XPath 1.0 defines no way for a function to signal erroneous input to its caller, the behavior here is specified to return results for SML references that do not obey all of the validity rules, e.g. a reference whose XPath expression evaluates to more than one node. As described in this section, such a function would be insufficient to check the validity of SML references.
Model validators MUST provide an implementation of the deref() XPath extension function. In addition to the above requirements for general deref() function implementations, for each SML reference using recognized schemes, deref() in model validators MUST attempt to resolve at least one of the recognized schemes.
An SML reference MAY be an instance of a variety of reference schemes. SML does not mandate the use of any specific reference schemes. An SML reference scheme MAY use child elements, attributes, both, or neither to capture the information necessary to identify the reference target. It is OPTIONAL 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 Reference Scheme for use in SML references.
An SML reference scheme definition MUST specify all of the following:
The set of rules that, when satisfied, identify an SML reference as an instance of the scheme. An SML reference scheme definition MAY impose additional validity requirements on SML references recognized as instances of that scheme. Model validators MUST NOT apply such requirements to SML references that are not instances of the corresponding reference scheme.
The set of rules that, when evaluated, resolve the SML reference to its target element node.
An assertion that states whether instances of the reference scheme are transformed to target-complete identifiers. If they are transformed to target-complete identifiers, the reference scheme definition MUST describe the transformation process.
An SML reference scheme definition MUST specify all of the preceding items as they apply to valid instances of the SML reference scheme, and MAY specify them for other (invalid) instances.
The SML URI Reference Scheme is defined as follows:
An SML reference is identified as an instance of the SML URI
Reference Scheme if and only if exactly one element information
item [XML Information Set]
whose [local name] is uri
and whose [namespace name]
is http://www.w3.org/ns/sml
is present as a child of
that reference element.
An instance of the SML reference scheme is valid if it meets all of the following requirements.
The content of the uri
element MUST be of type xs:anyURI
as defined
in the XML schema specification [XML Schema
Datatypes].
The fragment identifier (if present) MUST follow the syntax of one of the following.
An SML reference that is an instance of the SML URI Reference Scheme is resolved using the following steps:
An XML document D is obtained as follows:
If the URI reference is a same-document reference as defined in the applicable URI RFC, then D is the document containing the SML reference.
Otherwise, D is determined as follows:
If the URI reference is a relative reference, then let U
be the result of resolving the reference using the [base URI]
property [XML Information
Set] of the <sml:uri>
element as the
base URI. Otherwise, U is the URI reference itself. The
computation of the [base URI] property is
implementation-defined.
Dereference U as defined in the applicable specifications. If the document targeted by U is in the current SML model, then D is that document. Otherwise, if the document is not in the current SML model, then the SML URI Reference Scheme instance is unresolved (and D has no value).
Note:
As a result of the above definition, if the retrieved object is not of XML media type or if it is not well-formed XML then, by definition, that object is not a document as defined by this specification. In this case, the SML reference scheme instance is unresolved.
If no fragment component is present in the URI reference, the SML URI Reference Scheme instance resolves to the root element of D.
If a fragment component is present in the URI reference, then the appropriate case among the following applies:
If the fragment component complies with the
smlxpath1()
XPointer scheme syntax, then the reference
target is obtained by applying the fragment component to D,
as defined in section 4.3.1.1
smlxpath1() scheme .
If the fragment component complies with the Shorthand Pointer syntax, then the appropriate case among the following applies:
If a target T can be identified in D based on the XML-Schema-determined ID, then the reference target is T.
If a target in D cannot be identified based on the XML-Schema-determined ID, then it is implementation-defined whether the reference target in D is identified based on other criteria allowed for Shorthand Pointers.
Instances of the SML URI Reference Scheme are transformed to target-complete identifiers through standard URI processing, as described in the applicable URI RFC.
The following example shows an SML reference that is an instance
of the SML URI Reference scheme. The reference targets the element
with ID targetId
in document
target.xml
.
<RefElement sml:ref="true"> <sml:uri>target.xml#targetId</sml:uri> </RefElement>
smlxpath1()
schemeThe smlxpath1()
scheme is intended to be used with
the XPointer Framework [XPointer]
to allow addressing of elements. The 4.3.1 SML URI Reference Scheme
uses it to encode fragment identifiers.
This section describes the syntax and semantics of the
smlxpath1()
scheme and the behavior of XPointer
processors with respect to this scheme.
Scheme name: smlxpath1
Scheme syntax using ABNF [RFC 2234]:
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].
The deref()
XPath extension function MUST NOT be present in the expression evaluation
context function library when processing the location path in
SMLXPath1_SchemeData
.
Namespace Binding Context: The smlxpath1()
scheme
inherits the set of namespace bindings available to the parent
sml:uri
element.
For a given document D, the element targeted by a scheme
instance is obtained by applying the location path in
SMLXPath1_SchemeData
to the root element of D.
The result MUST either be 1 element
node or be empty. Otherwise, the XPointer result is an error.
Note:
In the case of instances of the SML URI Reference scheme, D is the document resolved to by the non-fragment part of the URI reference, as defined in item 2.a in section 4.3.1 SML URI Reference Scheme.
The following example shows an SML reference that is an instance
of the SML URI Reference scheme. The reference targets the root
element of the document target.xml
.
<RefElement sml:ref="true"> <sml:uri>target.xml#smlxpath1(/*)</sml:uri> </RefElement>
SML supports the following attributes for expressing constraints on SML references.
Name | Description |
---|---|
sml:acyclic |
Used to specify whether cycles are prohibited for an SML reference. |
sml:targetRequired |
Used to specify that an SML reference's target element is required to be present in the model. |
sml:targetElement |
Used to constrain the name of the SML reference's target. |
sml:targetType |
Used to constrain the type of the SML reference's target. |
SML defines a new property for every Complex Type Definition schema component:
The value of {acyclic} for
xs:anyType
is false
.
SML defines three new properties for every Element Declaration component:
An xs:boolean
value. Required.
An Element Declaration component. Optional.
A Type Definition component. Optional.
sml:acyclic
is used to specify whether or not a
cycle is allowed on instances of a complex type. Model validators 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
.
The {acyclic} property value of a complex type definition is as specified by the appropriate case among the following:
If sml:acyclic
is present, then {acyclic} has the actual value of this
attribute.
Otherwise, if its {base type definition} is a complex type definition, then {acyclic} has the same value of {acyclic} as its {base type definition}.
Otherwise ({base type definition} is a simple type definition), {acyclic} is false.
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.
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:
The nodes in the graph are all the elements resolved to by SML references of type CT or types derived from CT.
If a node N in the graph 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.
SML defines three attributes: sml:targetRequired
,
sml:targetElement
, and sml:targetType,
for constraining the target of an SML reference. These three
attributes are collectively called sml:target*
attributes. Model
validators MUST support these
attributes on all xs:element
elements with a name
attribute. The sml:target*
constraints are attached to
the element declaration schema component.
{target required} is as specified by the appropriate case among the following:
If sml:targetRequired
is present, then {target required} is the actual value of
this attribute.
Otherwise if the element declaration has a {substitution group affiliation}, then {target required} is the same as that of the {substitution group affiliation}.
Otherwise {target required} is false.
{target element} is as specified by the appropriate case among the following:
If sml:targetElement
is present, then its actual
value MUST resolve to a global element
declaration G, and {target
element} is G.
Otherwise if {substitution group affiliation} is present, then {target element} is the same as that of the {substitution group affiliation}.
Otherwise {target element} is absent.
{target type} is as specified by the appropriate case among the following:
If sml:targetType
is present, then its actual value
MUST resolve to a global type
definition T, and {target
type} is T.
Otherwise if {substitution group affiliation} is present, then {target type} is the same as that of the {substitution group affiliation}.
Otherwise {target type} is absent.
Model validators MUST enforce the following:
If a global element declaration E has a {substitution group affiliation} G, then the value of E's SML target constraint property P (one of {target required}, {target element} or {target type}) MUST be a valid restriction of the corresponding property of G as defined in section 5.3 Valid Restriction of SML Constraint Values.
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 have the same {target required}, {target element}, and {target type}.
Note:
The above condition #2 on the use of sml:target*
attributes has been defined to reduce the implementation
burden on model
validators. Please refer to section 5.4.1 Overview of SML
Constraint Processing and Complex Type Derivation for more
information.
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.
That is, 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.
The effect of the above instance validation rules is summarized in the following table.
Reference Category | Acyclic |
targetRequired |
targetElement |
targetType |
---|---|---|---|---|
Non-reference | Satisfied | Satisfied | Satisfied | Satisfied |
Null | Satisfied | Violated | Satisfied | Satisfied |
Unresolved | Satisfied | Violated | Satisfied | Satisfied |
Resolved | Check | Satisfied | Check | Check |
"Check" in the table above means that the appropriate constraint must be evaluated.
The constraints described above can be useful even on element declarations whose instances are not necessarily SML references, because the decision about whether to include a constraint and the decision about whether to make the element an SML reference can be made independently - some choices made by the schema author, other choices made by the instance document author.
XML Schema supports the definition of uniqueness and reference
constraints through xs:key
, xs:unique
,
and xs:keyref
elements. However, the scope of these
constraints is restricted to a single document. SML defines analogs
for these constraints, whose scope extends to multiple documents by
allowing them to traverse SML
references.
Model validators
MUST support the following elements
for defining SML identity constraints across SML references, as
child elements of xs:element/xs:annotation/xs:appinfo
where the xs:element
has a name attribute.
Name | Description |
---|---|
sml:key |
Similar to xs:key except
that the selector and field XPath expression can use the
smlfn:deref function |
sml:unique |
Similar to xs:unique
except that the selector and field XPath expression can use the
smlfn:deref function |
sml:keyref |
Similar to xs:keyref
except that the selector and field XPath expression can use the
smlfn:deref function |
Appendix B. Model Definition Document Sample and Appendix E. SML Identity Constraints Sample have examples that show how SML identity constraints are defined.
SML identity constraints are attached to the element declaration schema component. SML defines a new property for every element declaration schema component:
A set of SML identity constraint definitions components, which have the same set of properties as XML Schema identity constraint definitions.
Names of all SML identity constraint definitions exist in a single symbol space, which is disjoint from any symbol space of XML Schema components.
For each sml:key
, sml:unique
, or
sml:keyref
element without the ref
attribute specified, {SML
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:
The name attribute MUST NOT be specified.
The sml:selector
and sml:field
child
elements MUST NOT be specified.
If the element is sml:key
, then the value of
ref
attribute MUST
resolve to an SML key constraint.
If the element is sml:unique
, then the value of the
ref
attribute MUST
resolve to an SML unique constraint.
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.
sml:selector
XPath expression has the same syntax
as that defined in the XML Schema identity constraint selector
XPath syntax with one exception. The sml:selector
XPath MAY use
smlfn:deref()
functions, with function calls nested to
any depth, at the beginning of the expression. The XML Schema
identity constraint selector Path production is amended to support
this requirement as defined below.
Path ::= ('.//')? Step ( '/' Step)* | DerefExpr DerefExpr ::= NCName ':' 'deref' '(' Step ('/'Step)* ')' ('/'Step)* | NCName ':' 'deref' '(' DerefExpr ')' ('/'Step)*
sml:field
XPath expression has the same syntax as
that defined in the XML Schema identity constraint field XPath
syntax with one exception. The sml:field
XPath
MAY use smlfn:deref()
functions, with function calls nested to any depth, at the
beginning of the expression. The XML Schema identity constraint
field Path production is amended to support this requirement as
defined below.
Path ::= ('.//')? ( Step '/')* ( Step | '@' NameTest ) | DerefExpr ('/' '@' NameTest)? DerefExpr ::= NCName ':' 'deref' '(' Step ('/'Step)* ')' ('/'Step)* | NCName ':' 'deref' '(' DerefExpr ')' ('/'Step)*
The {SML identity-constraints definitions} of an element declaration MUST NOT contain two identity constraints with the same name.
Note:
This could happen if the ref attribute resolves to an identity constraint already contained in the same element declaration’s {SML identity-constraints definitions}.
If a global element declaration E has a {substitution group affiliation} G, then the value of E's {SML identity-constraints definitions} property MUST be a valid restriction of the value of the corresponding property of G as defined in section 5.3 Valid Restriction of SML Constraint Values.
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 rule is defined to reduce the implementation burden for model validators. Please refer to section 5.4.1 Overview of SML Constraint Processing and Complex Type Derivation for more information.
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.
Let BV = value of SML constraint property P (one of {target required}, {target element}, {target type} or {SML identity-constraints definitions}).
Let RV = value that restricts BV.
For RV to be a valid restriction of BV, the appropriate case among the following MUST be true.
For {target required}, the appropriate case among the following applies.
If BV is true, RV is true.
If BV is false, RV is either true or false.
For {target element}, one of the following applies.
RV is same as BV.
RV is in the substitution group of BV.
For {target type}, one of the following applies.
RV is same as BV.
RV is a type derived from BV.
For {SML identity-constraints definitions}, one of the following applies.
RV is same as BV. That is, all of the following is true.
The number of entries in RV is same as the number of entries in BV.
For each entry in BV, there exists an entry in RV with the same qualified name ({name} {target namespace}).
RV is a superset of BV. That is, RV has all of the entries from BV as defined in the previous item and it has one or more additional entries.
This section is non-normative.
For a complex type D derived from its {base type definition} B, if an element declaration ED is included in D and an element declaration EB is included in B, and ED and EB satisfy the "NameAndTypeOK" constraint, then the SML constraints (target* and SML identity constraints) applicable to ED must be
the same as those on EB in case of derivation by extension, and
the same or more restrictive compared to those on EB in case of derivation by restriction.
SML defines this behavior to ensure that one cannot get rid of SML constraints on elements in a complex type by simply deriving another type from that type.
Enforcing this condition across derivation by restriction would require an implementation to match a restricting particle to the corresponding restricted particle in order to evaluate condition 2 above. This level of support is not provided by most XML Schema frameworks; thus most SML validators would otherwise need to duplicate large parts of XML Schema's compilation logic to verify consistent usage of SML constraints across derivation by restriction. In order to reduce this implementation burden on model validators, SML requires that all element declarations with a given name that are included in a complex type definition must have the same SML constraint value. This allows model validators to find the restricted particle for a restricting particle using a simple name match.
This also means that the value of a given SML constraint applicable to all element declarations of a given name in complex type definition can be logically viewed as available at a single place, for example in a property attached to that complex type, rather than being scattered across element declarations in that type. The next section uses this logical view because it makes it easier to understand and formally define SML constraint behavior across complex type derivation.
SML defines four properties for every complex type definition schema component CT.
A list of (qname, value) pairs, where,
qname is a qualified name ({namespace name} {name}).
value is the value of a {target required} property.
A list of (qname, value) pairs, where,
qname is a qualified name ({namespace name} {name}).
value is the value of a {target element} property.
A list of (qname, value) pairs, where,
qname is a qualified name ({namespace name} {name}).
value is the value of a {target type} property.
A list of (qname, value) pairs, where,
qname is a qualified name ({namespace name} {name}).
value is the value of a {SML identity-constraints definitions} property.
The value of the above 4 properties for xs:anyType
is empty.
Let
CT = A complex type definition.
C = SML constraint (one of targetRequired, targetElement, targetType, SML identity constraint).
P = A property of CT corresponding to constraint C (one of {target required constraint list}, {target element constraint list}, {target type constraint list}, {identity constraint list}).
V = The value of P, a list of (qname, value) pairs.
ED = An element declaration contained in CT.
PED = A property of ED corresponding to constraint C (one of {target required}, {target element}, {target type}, {SML identity-constraints definitions}).
Property P is assigned value V as defined below:
For each element declaration ED, with qualified name qn, contained in CT:
If ED does not have constraint C, that is, the value of PED is absent (or false in case of targetRequired), then skip ED.
Otherwise, if there is already an entry in V for qn, then skip ED.
Note:
If the value of the existing entry is different from the value of PED then it is treated as a schema validation error as defined in section 5.1.2.2 Schema Component Rules and section 5.2.1.2 Schema Component Rules.
Otherwise, the entry (qn, value of PED) is added to the list V.
The appropriate case among the following applies:
If CT is derived by extension from a simple type definition then value V is empty.
If CT is derived by extension from a complex type definition BT:
The initial value of V is computed as defined in list item 1 above and then,
For each entry (qn, vb) in the value of P in BT:
If V has an entry (qn, vc) present, then ensure that vc is same as vb. If it is not same, then it is treated as a schema validation error.
If V does not have any entry (qn, vc) present, then copy (qn, vb) into V.
If CT is derived by restriction from a complex type definition BT:
The initial value of V is computed as defined in list item 1 above and then,
For each entry (qn, vb) in the value of P in BT:
If V has an entry (qn, vc) present, then ensure that vc is a valid restriction of vb as defined in section 5.3 Valid Restriction of SML Constraint Values. If it is not, then it is treated as a schema validation error.
If V does not have any entry (qn, vc) present, then copy (qn, vb) into V.
Let,
CT = the complex type of element declaration ED.
E = an instance of ED.
C = a child element of E.
If C matches an element declaration contained in CT and if one or more of CT's constraint properties, defined in 5.4.2.1 Properties, contain an entry matching C's qualified name ({namespace name} {name}) then the value of each of those entries is used for evaluating the corresponding constraint on C, as defined in section 5.1.2.3 Instance Validity Rules and section 5.2.1.3 Instance Validity Rules, as if the matching element declaration has the corresponding constraint with that value.
Note:
One way for constraints to be embedded in element declarations
or type definitions in a schema is for constraint element to be
included in a schema document, embedded at the appropriate
locations within the xs:element
or
xs:complexType
elements which describe the element
declaration or type definition.
Element declarations and type definitions created by other means can, however, also have constraints embedded within the {application information} of their {annotation} properties. How such embedding is accomplished is outside the scope of this specification and is likely to vary among model processors.
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 Schematron to add support for additional model constraints not supported in XML Schema.
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.
Constraints can be specified using the sch:assert
and sch:report
elements from Schematron. The
following example uses sch:assert
elements to specify
two constraints:
An IPv4 address must have four bytes
An IPv6 address must have sixteen bytes
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" targetNamespace="urn:x-example:IPAddress"> <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:x-example: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> </xs:schema>
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
sch:rule
elements and a single sch:rule
element contains one or more assert
and/or
report
elements. Each sch:rule
element
specifies its context using the context
attribute.
This context expression is evaluated in the context of each
applicable element and results in an element node set for which the
assert and report test
expressions contained in the
sch:rule
element are evaluated. The
context
expression is defined as an XSLT Pattern. This
means that the smlfn:deref
function may not be used in
the location path of a context
expression.
In the above example, context="."
. Therefore the
two assert expressions are evaluated in the context of each
applicable element; i.e., each element of type
IPAddress
. The test
expression for an
assert
is a boolean expression, and the
assert
is violated (or fires) if its test
expression evaluates to false. A report
is violated
(or fires) if its test
expression evaluates to true.
Thus, an assert
can be converted to a
report
by simply negating its test expression. The
following example uses report
elements to represent
the IP address constraints of the previous example:
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" targetNamespace="urn:x-example:IPAddress"> <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:x-example: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> </xs:schema>
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/ns/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 sch:rule
elements contained in
StudentPattern
are applicable to all element instances
of the StrictUniversity
global element declaration.
For each StrictUniversity
element, the XPath
expression specified as the value of the context
attribute is evaluated to return a node set, and the test
expressions for the two asserts are evaluated for each node in this
node set. Thus, these two asserts verify the following
conditions for each instance of StrictUniversity
.
The ID of each student must begin with '99'.
Each student must be enrolled in at least one course.
Schematron patterns can be authored in separate rule documents that are then bound to a set of documents in the model.
The following example shows the constraints for
StrictUniversity
expressed in a separate document:
<?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/ns/sml-function"/> <sch:pattern id="StudentPattern"> <sch:rule context="u:StrictUniversity/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 rule document containing the
StudentPattern
pattern to documents that may contain
instances of StrictUniversity
element is
implementation-defined.
Model validators 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"
.
Model validators
MUST support the "xslt"
query binding. Model
validators MAY additionally
support query bindings other than "xslt"
.
SML defines a new property for every complex type definition schema component and every element declaration schema component.
A set of Schematron constraints.
The {rules} property contains all
of the Schematron constraints applicable to instances of the given
type definition or element declaration. Its value is derived in
part from sch:schema
elements embedded within the
component, and sometimes in part from the {rules} properties of other components.
sch:schema
elements MAY appear as items in the {application
information} of the {annotation} of a global element declaration or
a global complex type definition. This specification assigns no
meaning to sch:schema
elements if they appear as items
in any other location.
Let the local-rules of a given global element declaration or global complex type definition be the set of Schematron constraints embedded in the {application information} of that schema component's {annotation} property. For other schema components, local-rules is empty.
The value of the {rules} property of a schema component is computed as follows:
The value of {rules} for
xs:anyType
is the empty set.
If the schema component is a global element declaration, then the value of its {rules} is the union of its local-rules and the appropriate case from the following:
If the element declaration has a {substitution group affiliation}, then the value of {rules} of the {substitution group affiliation}.
Otherwise (the element declaration has no {substitution group affiliation}), the empty set.
If the schema component is a complex type definition, then the value of its {rules} property is the union of its local-rules and the appropriate case from the following:
If the component's {base type definition} is a complex type definition, then the {rules} of the {base type definition}. This is true for derivation by extension as well as for derivation by restriction.
Otherwise (i.e., when {base type definition} is a simple type definition), the empty set.
Otherwise, the value of the {rules} property is not affected by this specification.
Model validators MUST enforce the following rules.
If a complex type D is derived by restriction or extension from {base type definition} B and if B has {rules} defined on it then they MUST be automatically copied to D and unioned with the {rules} defined on D.
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 MUST NOT be restricted to a local element declaration in D.
Note:
It is an error if all of the following are true.
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.
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]).
EB is a reference to a global element declaration with a Schematron constraint on it.
ED is a local element declaration with the same name as EB.
Model validators MUST behave as follows:
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.
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.
All of the assertion tests in fired rules MUST succeed.
Model validators MUST provide a mechanism to support the binding of Schematron patterns, authored in separate rule documents, to a set of documents in a model. Rule documents MAY be bound to model instance documents as well as model definition documents. The mechanism for binding rule documents to a set of documents in a model is implementation-defined.
SML defines the sml:locid
attribute in support of
localization of natural-language texts, for example,
smlif:description
or Schematron messages. Model validators MAY support sml:locid
attribute on
the following elements:
sch:assert
and sch:report
in a
rule document.
sch:assert
and sch:report
in a
Schematron pattern
embedded in the {application
information} of the {annotation} property of a complex type
definition or an element declaration.
Elements in instance documents with textual content.
Model validators that support the sml:locid
attribute MUST use the
sml:locid
attribute value to access the location of
the translated text.
Note:
The mechanism for using the QName
value of the
sml:locid
attribute to locate the translated text is
implementation-dependent. For example, the namespace name can
be used to identify the resource containing the text and the
local name
can be used to identify the text within such a resource. Refer to
Appendix F. Localization and
Variable Substitution Samples for a concrete sample of how
the sml:locid
attribute can be used to support text
localization.
It is often the case that a sch:assert
or
sch:report
message can be reused in different
situations. To be able to reuse a message, the rule author must be
able to substitute variable content based on the context in which
the message is being used.
Although this specification does not mandate the use of variable
substitution in Schematron messages, it suggests the use of
xsl:variable
when variable substitution is desired.
Refer to Appendix F. Localization
and Variable Substitution Samples section for a concrete
sample of how the xsl:variable
can be used in support
of reusing localized messages.
A program is a conforming SML model processor if and only if it satisfies all the constraints imposed on processors elsewhere in this specification.
A conforming SML model processor is a conforming SML model validator if and only if it satisfies the following conditions:
The validator MUST perform model validation as defined in this specification.
The validator MUST support XML 1.0 [XML], XML Schema 1.0 [XML Schema Structures, XML Schema Datatypes], and XPath 1.0 [XPath] but MAY also additionally support any future versions of these specifications.
The validator MUST support Schematron [ISO/IEC 19757-3].
The validator MUST perform Schematron rule evaluation on the #ALL phase.
The validator MUST support the
deref()
XPath extension function.
The validator MUST identify all SML references in the model using the Post Schema Validation Infoset. [XML Schema Structures]
The validator MUST use the Post Schema Validation Infoset to determine if an SML reference in the model is a null SML reference. [XML Schema Structures]
The conformance of a model and the validity of a model can be assessed if and only if all documents in the model are available to the model validator. A model validator MUST document its behavior when a model document is found to be unavailable (i.e. the behavior is implementation-defined). It MAY respond to this condition in ways that include but are not limited to: assessing the model as invalid, or treating this as a warning. The intent of the latitude granted to model validators in this case is to provide some implementation flexibility by not prescribing a limited set of choices, however it is be read narrowly rather than as a broad license to take unrelated actions like failing to enforce SML constraints on unrelated documents.
A model is a conforming SML model if and only if it satisfies the following conditions:
Each document in the model MUST be a well-formed XML document [XML]
For each XML Schema document in the model's definition documents, the [validity] property of the root element MUST be "valid" when schema validity is assessed with respect to a schema constructed from the XML Schema for Schemas and A. Normative SML Schema schema documents.
All schemas assembled from the XML Schema documents in the model's definition documents MUST satisfy the conditions expressed in Errors in Schema Construction and Structure (§5.1). [XML Schema Structures]
All schemas assembled from the XML Schema documents in the model's definition documents MUST satisfy the conditions expressed in sections 5.1.1.1 SML Constraint Construction, 5.1.1.2 Schema Component Rules, 5.1.2.1 SML Constraint Construction, 5.1.2.2 Schema Component Rules, 5.2.1.1 SML Constraint Construction, 5.2.1.2 Schema Component Rules, 6.3.1 SML Rule Construction and 6.3.2 Schema Component Rules.
Each Schematron document in the model's definition documents MUST be a valid Schematron document [ISO/IEC 19757-3]
Note:
This specification does not define how schemas are assembled and which schema documents contribute to assembling the schemas.
A conforming SML model is valid if and only if it satisfies all of the following conditions:
In each instance document in the model, which is bound to a schema, the [validity] property of the root element MUST be "valid", and the [validity] property of all the other elements and all the attributes MUST NOT be "invalid", when schema validity is assessed with respect to any schema that is bound to this instance document. The schema validity assessment starts with no stipulated declaration or definition at the root element. [XML Schema Structures]
The schema-validity of instance documents not bound to any schema does not contribute to the validity or invalidity of the model.
Note:
How schemas are bound to instance documents is not defined by this specification. Multiple schemas may be bound to the same instance document.
SML validity entails NOT being Schema-Invalid on the root or any descendant. SML validity can be non-vacuously checked only after assessment of Schema validity, and only on the portions of the subtree for which PSVI is available.
Because the depth of PSVI is implementation-dependent, there is variability in the visibility of SML constraints available to the SML validator, and consequently in SML validity results.
Each document in the model MUST satisfy all applicable Schematron constraints when validated in the #ALL phase.
Each document in the model MUST satisfy all normative statements in this specification that pertain to model documents.
Note:
This means, for example, that each document must satisfy all applicable sml:acyclic, sml:target*, and SML identity constraints.
This section is a reference guide to the SML extensions of XML Schema and XPath.
Used to specify that instances of an SML reference of a given type and its derived types do not create any cycles in a model
<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="HostedOnRefType" 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.
This global attribute is used to identify SML references.
<xs:attribute name="ref" type="xs:boolean"/>
Any element that has sml:ref="true" will be treated as an SML reference.
This global attribute is used to identify null SML references.
<xs:attribute name="nilref" type="xs:boolean"/>
Any SML reference that has sml:nilref="true"
or
sml:nilref="1"
will be treated as a null SML
reference.
A QName
representing the name of a referenced
element
<xs:attribute name="targetElement" type="xs:QName"/>
sml:targetElement
is supported as an attribute for
any element declaration. The value of this attribute must be
the name of some global element declaration. Let
sml:targetElement="ns:GTE"
for some element
declaration E. Then each element instance of E must
target an element that is an instance of ns:GTE or an
instance of some global element declaration in the substitution
group hierarchy whose head is ns:GTE.
In the following example, the element referenced by instances of
HostOS
must be an instance of
win:Windows
<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 or more sml:targetElement constraints.
Used to specify that instances of an SML reference must target
elements in the model; i.e., an instance of the SML reference can
not be null or contain an unresolved reference. Therefore it is an
error if targetRequired="true"
is specified on an
element declaration where the corresponding SML reference element R
has sml:nilref="true"
.
<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 or more
sml:targetRequired
constraints.
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 or more sml:targetType constraints.
This attribute can be defined on the sch:assert
,
sch:report
and on any element with textual content.
The sml:locid
attribute is used to define the
translation location for the text content of the containing
element.
<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 scope of this
specification.
This element is used to specify a key constraint in some scope.
The semantics are the same as that for xs:key
except
that sml:key
can also be used to specify key
constraints on other documents; i.e., the
sml:selector
child element of
sml:key
can contain deref
functions to
resolve elements in another document.
<xs:element name="key" type="sml:keybase"/>
sml:key
is supported in the appinfo
of
an xs:element
.
Applies a constraint in the context of the containing
xs:element
that scopes the range of a nested document
reference.
<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
.
This element is used to specify a uniqueness constraint in some
scope. The semantics are the same as that for
xs:unique
except that sml:unique
can also
be used to specify uniqueness constraints on other documents; i.e.,
the sml:selector
child element of
sml:unique
can contain deref
functions to
resolve elements in another document.
<xs:element name="unique" type="sml:keybase"/>
sml:unique
is supported in the appinfo
of an xs:element
.
node-set deref(node-set)
This function takes a node set and attempts to resolve the SML references. The resulting node set is the set of elements that are obtained by successfully resolving (or de-referencing) the SML references. For example,
deref(/u:Universities/u:Students/u:Student)
will resolve the SML reference, Student
. The target
of an SML reference must always be an element.
<!-- /* * Copyright © ns 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:sml="http://www.w3.org/ns/sml" xmlns:xs="http://www.w3.org/2001/XMLSchema" targetNamespace="http://www.w3.org/ns/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 a global 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. See Section 5.1.1.3 titled "Instance Validity Rules". </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>
This model definition document sample illustrates the use of the following SML extensions:
key
and keyref
constraints
Schematron 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/ns/sml" xmlns:smlfn="http://www.w3.org/ns/sml-function" xmlns:sch="http://purl.oclc.org/dsdl/schematron" targetNamespace="http://example.org/SampleModel" elementFormDefault="qualified" finalDefault="" blockDefault="" attributeFormDefault="unqualified"> <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/ns/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/ns/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>
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 SML references as shown below:
<Student xmlns="http://www.university.example.org/ns" xmlns:sml="http://www.w3.org/ns/sml" xmlns:u="http://www.university.example.org/ns"> <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 #smlxpath1(/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 #smlxpath1(/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 an SML reference since it specifies
sml:ref="true"
. It uses the SML URI Reference Scheme
to target the element for course PHY101. The second and third
EnrolledCourse
elements are not SML references; the
second element specifies sml:ref="false"
and the third
element does not specify the sml:ref
attribute. Note
that the second EnrolledCourse
element contains an
sml:uri
element which satisfies the syntax of the SML
URI Reference Scheme (referring to course MAT100) but this will be
ignored since sml:ref="false"
for this
EnrolledCourse
element.
Note that, there are no SML constraints defined on the
EnrolledCourse
element or on the type of that element
in the schema. Therefore, even if the first
EnrolledCourse
element instance is marked as an SML
reference, no SML constraints are evaluated for that element during
model validation. However, checks such as the ones defined in
section 4.2.1 At Most One
Target and section 4.2.2 Consistent References are
still performed on that SML reference during model validation.
An EnrolledCourse
SML reference can be a marked as
a null reference if it specifies the sml:nilref="true"
attribute as shown in the following example (the first
EnrolledCourse
element is a null SML reference):
<Student xmlns="http://www.university.example.org/ns" xmlns:sml="http://www.w3.org/ns/sml" xmlns:u="http://www.university.example.org/ns"> <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 #smlxpath1(/u:Courses/u:Course[u:Name='MAT100']) </sml:uri> </EnrolledCourse> <EnrolledCourse> <Name>SocialSkills</Name> <Grade>F</Grade> </EnrolledCourse> </EnrolledCourses> </Student>
In the above example, the first SML reference,
EnrolledCourse
, defines the
sml:nilref="true"
attribute which marks this as a null
SML reference. By specifying a null reference, the document author
makes an explicit declaration that this Student
element does not refer to any target element. Specifying a null
reference does not have any SML-defined effect on the
interpretation of element in non-SML contexts. In particular, in
this case, SML says nothing about the interpretation of the
Grade
and Name
elements. Any such
interpretation is left to the application, its usage context, other
specifications, etc.
The following example illustrates the use of the SML URI
Reference Scheme [4.3.1 SML URI
Reference 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 Courses
is 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>
An SML reference can also 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.
The following example will be used to illustrate the
sml:key
, sml:unique
, and
sml:keyref
constraints across SML references. This
example consists of three schema documents.
university.xsd
contains the type definitions for a
University element, a Student SML reference and a Course SML
reference. students.xsd
contains the type definitions
for an EnrolledCourse SML reference and a Student element.
courses.xsd
contains the type definition for a Course
element.
<!-- 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.
The following examples demonstrate how localization can be
applied to a message text resulting from Schematron rule
evaluation, allowing a model
processor to support multiple locales without changes to either
the model processor or the Schematron rules. Summarized below are
the benefits resulting from using the sml:locid
localization support:
The Schematron rule message text is locale-independent in the
sense that the author does not have to be concerned with the rule
evaluator's runtime locale. The Schematron rule is defined
generically, consumable for any evaluator (including a model
processor) for which a translation file is made available at the
location defined by the sml:locid
value's namespace name.
There is a clear separation between the message text
translation, Schematron rule authoring, and Schematron rule
evaluator code. The Schematron rules require no changes when
translations for other languages are made available. The same
Schematron rule can be used by multiple evaluators, each supporting
a distinct set of languages. 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
value's namespace name.
Building on the preceding university example, the following
example of a Schematron rule uses the sml:locid
attribute to locate 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/ns/sml-function"/> <sch:pattern id="StudentPattern”> <sch:rule context="u:Students/u:Student"> <sch:assert test=".[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:pattern> </sch:schema>
In general, the namespace name can point to a file containing the translated message, a folder containing a set of translated files or any other type of resource that can help locate the translated message. It is implementation-dependent how the model validator makes use of this information for finding the actual resource containing the translated message.
In this concrete example, the namespace name of
the sml:locid
attribute value is used to define the
location of the resource containing the translated text:
xmlns:lang="http://www.university.example.org/translation/"
Also, in this concrete example,
http://www.university.example.org/translation/
names a
folder containing a set of translation resources, and there is one
set of translation files located under
http://www.university.example.org/translation/
. Each
of these translation files corresponds to a language into which the
messages have been translated. The translations to French and
German are available in the following files:
File
http://www.university.example.org/translation/lang_fr.txt
contains the French translation of the sch:assert
message.
File
http://www.university.example.org/translation/lang_de.txt
contains the German translation of the sch:assert
message.
The {local part} of the sml:locid
attribute value
(StudentIDErrorMsg
) is used to define the identity of
the message being translated. This identity is used to locate the
translated text within the translation resource.
The French translation of the sch:assert
message is
found in the following entry:
StudentIDErrorMsg = L'identifiant specifié <sch:value-of select="string(u:ID)"/> ne commence pas par 99.
The German translation for the sch:assert
message
is found in the following entry:
StudentIDErrorMsg = Der angegebene Wert des Attributs ID (<sch:value-of select="string(u:ID)"/>) beginnt nicht mit "99".
Translatable messages, especially strings containing XML tags
(such as <sch:value-of select="string(u:ID)"/>
in the example below), may be best stored in XML containers. This
allows more flexibility to manipulate and translate the data. For
example, the XML document could utilize ITS (see Internationalization Tag Set (ITS)
specification) to add localization-related information.
<?xml version="1.0" encoding="UTF-8"/> <messages xml:lang="en" xmlns:sch="http://purl.oclc.org/dsdl/schematron" xmlns:its="http://www.w3.org/2005/11/its"> <msg xml:id='StudentIDErrorMsg' its:locNote="This message should not be longer than 128 characters"> The specified ID <sch:value-of select="string(u:ID)"/> does not begin with 99. </msg> </messages>
Best Practice Recommendation for Variable Substitution
It is often the case that translated text can be reused, for
example, a Schematron message can be reused in different
sch:assert
or sch:report
rules and
patterns. 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.
Reuse opportunities for this message are limited since the
translated message contains implicit assumptions about the rule
context. To be able to reuse this message more widely, the message
author should substitute a context-independent expression, such as
a variable, in place of the u:ID
in
<sch:value-of select="string(u:ID)"/>
.
Thus, the original message translations
StudentIDErrorMsg = L'identifiant specifié <sch:value-of select="string(u:ID)"/> ne commence pas par 99. StudentIDErrorMsg = Der angegebene Wert des Attributs ID (<sch:value-of select="string(u:ID)"/>) beginnt nicht mit "99".
should instead be coded to use a variable's value, as shown below.
StudentIDErrorMsg = L'identifiant specifié <sch:value-of select="$studentID"/> ne commence pas par 99. StudentIDErrorMsg = Der angegebene Wert des Attributs ID (<sch:value-of select="$studentID"/>) beginnt nicht mit "99".
The error message in sch:assert
, identified by the
lang:StudentIDErrorMsg
value, can now be reused in
Schematron rule contexts other than the one described by the sample
above. In cases where variable substitution is used in this way,
the responsibility for setting the variable in the message's
various usage contexts rests with the rule author(s). Specifically,
the Schematron rule used to start the Appendix F portion of this
running example would need to set the value of the
studentID
variable. The sample below shows how the
revised translation resources would be referenced from a Schematron
rule.
<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/ns/sml-function"/> <sch:pattern id="StudentPattern”> <sch:rule context="u:Students/u:Student"> <sch:let name="studentID" value="u:ID"/> <sch:assert test="starts-with(u:ID,'99')" sml:locid="lang:StudentIDErrorMsg"> The specified ID <sch:value-of select="$studentID"/> does not begin with 99. </sch:assert> </sch:rule> </sch:pattern> </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
.
If the translated string named by StudentIDErrorMsg
is intended for use only in the context of Schematron elements,
this mechanism is sufficient. If the message is intended for use in
additional contexts, the preceding syntax is not necessarily
sufficient. In order to allow reuse of translated strings
exploiting variable substitution in other contexts, a syntax
understood both inside and outside of Schematron elements is
required. xsl:variable
and sch:let
are
possible choices, made more practical by SML’s requirement that
validators support the “xslt" query binding for Schematron.
However, there is currently insufficient practical experience to
label this a best practice.
The editors acknowledge the members of the Service Modeling Language Working Group, the members of other W3C Working Groups, and industry experts in other forums who have contributed directly or indirectly to the process or content of creating this document.
At the time this specification was published, the members of the Service Modeling Language Working Group were:
John Arwe (IBM Corporation), Len Charest (Microsoft Corporation), Sandy Gao (IBM Corporation), Paul Lipton (CA), James Lynn (HP), Kumar Pandit (Microsoft Corporation), Valentina Popescu (IBM Corporation), Virginia Smith (HP), Henry Thompson (W3C/ERCIM), David Whiteman (IBM Corporation), Kirk Wilson (CA).
The Service Modeling Language Working Group has benefited in its work from the participation and contributions of a number of people not currently members of the Working Group, including in particular those named below.
Dave Ehnebuske (IBM), Jon Hass (Dell), Steve Jerman (Cisco), Heather Kreger (IBM), Vincent Kowalski (BMC), Milan Milenkovic (Intel), Bryan Murray (HP), Phil Prasek (HP), Junaid Saiyed (EMC), Harm Sluiman (IBM), C. Michael Sperberg-McQueen (W3C/MIT), Bassam Tabbara (Microsoft), Vijay Tewari (Intel), William Vambenepe (HP), Marv Waschke (CA), Andrea Westerinen (Microsoft), Pratul Dublish (Microsoft), Julia McCarthy (IBM).
Affiliations given above are those current at the time of their work with the working group.