Service Modeling Language, Version 1.1

...

6. Rules

XML Schema supports a number of built-in grammar-based constraints but it does not support a language for defining arbitrary rules for constraining the structure and content of documents. Schematron [ISO/IEC 19757-3] is an ISO/IEC standard for defining assertions concerning a set of XML documents. SML uses Schematron to add support for additional model constraints not supported in XML Schema.

6.1 Informal Description (Non-Normative)

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

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:simpleType  name="IPAddressVersionType">
       <xs:restriction base="xs:string" >
           <xs:enumeration value="V4" />
           <xs:enumeration value="V6" />
        </xs:restriction>
</xs:simpleType>

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

A Schematron constraint embedded in the xs:annotation/xs:appinfo element for a complex type definition or an element declaration is applicable to all instances of the complex type or element. In the above example, the pattern Length (which is a part of the containing Schematron constraint) is applicable for all elements whose type is IPAddress or a derived type of IPAddress. A pattern element contains one or more 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:simpleType  name="IPAddressVersionType">
        <xs:restriction base="xs:string">
           <xs:enumeration value="V4"/>
           <xs:enumeration value="V6"/>
        </xs:restriction>
    </xs:simpleType>

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

If a sch:assert or sch:report is violated, the violation is reported together with the specified message. The message can include substitution strings based on XPath expressions. These can be specified using the sch:value-of element. The following example uses the sch:value-of element to include the number of specified address bytes in the message:

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

In addition to being embedded in complex type definitions, constraints can also be embedded in global element declarations. Such constraints are evaluated for each instance element corresponding to the global element declaration. Consider the following example:

<xs:element name="StrictUniversity" type="tns:UniversityType">
    <xs:annotation>
        <xs:appinfo>
            <sch:schema xmlns:sch="http://purl.oclc.org/dsdl/schematron">
                <sch:ns prefix="u" uri="http://www.university.example.org/ns" />
                <sch:ns prefix="smlfn"  
                        uri="http://www.w3.org/@@@@/@@/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 which 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/@@@@/@@/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-dependent and hence outside the scope of this specification.

6.2 Rule Support

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

6.3 Rules Embedded in Schema DocumentsAssociated with Schema Components

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

{rules}: A set of Schematron constraints.

6.3.1 Mapping from schemaCalculating the effective value of the {rules} property

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 can be embedded in members of the {application information} of the {annotation} of a global element declaration or a global complex type definition. They MUST NOT be embedded in any other kind of schema component.

Note:

This note is non-normative. One way for sch:schema elements to be embedded in element declarations or type definitions in a schema is for the sch:schema elements 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 sch:schema elements 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 from processor to processor.

Let the local-rules of a given global element declaration or global complex type definition be the set of Schematron constraints attached to a global element declaration or a global complex type definitionembedded in the {application information} of that schema component's {annotation} property.

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} property is same as itsthe local-rules of that global element declaration.
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:
1. 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.
2. Otherwise (i.e., when {base type definition} is a simple type definition), the empty set.

6.3.2 Schema Validity Rules

Model validators MUST enforce the following rules.

The value of {rules} MAY be non-empty for global element declarations, global complex type definitions or anonymous complex type definition of global element declarations. It MUST be empty for any other schema component.
If a complex type D is derived by restriction or extension from {base type definition} B and if B has Schematron constraints defined on it then they are automatically copied to D and unioned with the Schematron constraints defined on D.
If a complex type D is derived by restriction from {base type definition} B then, a global element declaration with non-empty {rules} contained in B cannot be restricted to a local element declaration in D.

Non-normative note: It is an error if all of the following are true.
1. An element declaration ED is contained (directly, indirectly, or implicitly) in D and an element declaration EB is contained (directly, indirectly, or implicitly) in B,
2. ED and EB satisfy the "NameAndTypeOK" constraint (for XML Schema's definition of valid restrictions, see Schema Component Constraint: Particle Valid (Restriction), Constraints on Particle Schema Components in [XML Schema Structures])
3. EB is a reference to a global element declaration with a Schematron constraint on it.
4. ED is a local element declaration with the same name as EB.

6.3.3 Instance Validity Rules

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.

6.4 Rules Authored in Rule Documents

6.4.1 Rule Binding

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-dependent and hence outside the scope of this specification.

7. Localization of Natural Language Messages

SML defines the sml:locid attribute in support of localization of the natural-language texts or 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 xs:annotation/xs:appinfo element for {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:

This note is non-normative. The mechanism for using the QName value of the sml:locid attribute to locate the translated text is implementation dependent. For example, the {namespace name} can be used to identify the resource containing the text and the {local name} can be used to identify the text within such resource. Refer to F. Localization and Variable Substitution Sample section for a concrete sample of how the sml:locid attribute can be used to support text localization.

7.1 Variable Substitution

There is often the case that a sch:assert or sch:report message can be reused in different situations. To be able to re-use a message, the schema author must be able to substitute variable content based on the context in which the message is being used.

Although this specification does not mandate the use of variable substitution in Schematron messages, it suggests the use of xsl:variable when variable substitution is desired. Refer to F. Localization and Variable Substitution Sample section for a concrete sample of how the xsl:variable can be used in support of reusing localized messages.

...