1. Introduction
(Non-Normative)
As defined in the Service Modeling Language, Version 1.1 (SML)
Specification [SML 1.1] an SML
model is a collection of XML documents that may be used to describe
complex services and systems such as a set of IT resources,
services and their interrelations.
In every SML model there are two distinguished subsets of the
model's documents, the definition documents and the instance
documents. The model's definition documents describe the abstract
structure of the model, and provide much of the information a model
validator needs to decide whether the model, as a whole, is valid.
The model's instance documents describe or support the description
of the individual resources that the model portrays.
The SML Specification identifies two categories of model
definition documents that participate in SML model validation:
Schema documents and rule documents. Schema documents in a model
are XML documents that conform to the [SML
1.1] defined extensions to XML Schema [XML Schema Structures, XML
Schema Datatypes]. Rule documents in a model include XML
documents that conform to the [SML
1.1] defined extensions of Schematron [ISO/IEC 19757-3].
To ensure accurate and convenient interchange of the documents
that make up an SML model, it is useful to define both an
implementation-neutral interchange format that preserves the
content and interrelationships among the documents and a
constrained form of SML model validation. For this purpose, this
specification defines a standard format called the SML Interchange
Format (SML-IF) and a process called interchange model
validation.
The specification consists of two parts. The first part is an
informal description of SML-IF to set the context. This is followed
by SML-IF's normative definition.
4.
Informal Description (Non-Normative)
To represent an SML model in a standard way for interchange, the
following topics need to be addressed.
Packaging: The collection of XML documents that make up a
model to be interchanged need to be gathered together. In doing so,
the model definition and model instance documents need to be
distinguished from one another since they play distinct roles in
the model.
Explicit references: The documents to be interchanged may
explicitly refer to one another and to documents that are not
packaged with the documents being interchanged. [SML 1.1] SML references among SML model instance
documents are an obvious example. Less obvious are such references
as certain schemaLocation attributes in schema
documents and xsi:schemaLocation attributes in
instance documents. Section 4.4
Schema Bindings defines how schemaLocation is
processed in these cases.
Rule bindings and schema bindings: [SML 1.1] permits models in which rule documents
apply to all, none, or subsets of the model's documents. SML-IF
specifies how to describe which rule documents apply to which of
the model's documents.
Model validation: The process of SML model validation
defined in [SML 1.1] contains
points of variability that, left unconstrained, would make it
difficult for SML-IF to ensure interoperability of independent
implementations in any practical way. Many of these sources of
variability are inherited from other specifications that SML uses,
e.g. URI comparison RFC 3986 ([IETF RFC
3986]) and the source of Schema components
([XML Schema Structures]) used to
validate model instance documents. SML-IF constrains these points
of variability, with the goal of ensuring interoperability when
specific conditions are met and of increasing the likelihood of
interoperability in other cases. The enforcement of these
additional constraints on SML model validation occurs during the
process of interchange
model validation.
4.1 Packaging
An SML-IF document packages a collection of SML model documents
to be interchanged as a single XML document. All SML-IF documents
conform to the XML Schema defined in the normative part of this
specification.
Informally, the structure of SML-IF documents, using the
pseudo-schema notation from WSDL 2.0 [WSDL
2.0 Core Language] is as follows:
<?xml version="1.0" encoding="UTF-8"?>
<model xmlns="http://www.w3.org/ns/sml-if"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
SMLIFVersion="xs:token Version number of the SML-IF spec used to generate the current document"
schemaComplete="xs:boolean">
<identity>
<name>
xs:anyURI Namespace identifying the model
</name>
<version> ?
xs:token <!-- The version of this model. E.g., 1.2 or 0.3 -->
</version>
<displayName sml:locid="xs:anyURI URI identifying the translation
resource for the display name" ?> ?
xs:string Descriptive name of model intended for display
</displayName>
<baseURI>
xs:anyURI <!-- Base URI for relative references defined in the interchange model;
must be an absolute reference -->
</baseURI> ?
<description sml:locid="xs:anyURI URI identifying the translation
resource for the description" ?> ?
xs:string Textual description of model for human consumption
</description>
</identity>
<ruleBindings> ?
<ruleBinding> *
<documentAlias="xs:anyURI"/> ?
<ruleAlias="xs:anyURI"/>
</ruleBinding>
</ruleBindings>
<schemaBindings> ?
<defaultSchema> ?
<namespaceBinding/> *
</defaultSchema>
<schemaBinding> *
<namespaceBinding/> *
<documentAlias/> *
</schemaBinding>
<noSchemaBinding> ?
<documentAlias/> *
</noSchemaBinding>
</schemaBindings>
<definitions> ?
<document> *
<docInfo> ?
<baseURI> ?
xs:anyURI <!-- If a document has a baseURI, then this will be used to form the
base URI for all relative URIs subject to SML URI processing
contained by that document. -->
</baseURI>
<aliases> ?
<alias> *
xs:anyURI <!-- A URI by which SML references from other documents may refer to this document. -->
</alias>
</aliases>
</docInfo>
[
<data>
xs:any <!-- At most one definition document goes here -->
</data>
|
<base64Data>
xs:any <!-- At most one base64 encoded definition document goes here -->
</base64Data>
|
<locator>
<documentURI/> ?
xs:any <!-- A URI or IRI that points to a definition document goes here -->
</locator>
]
</document>
</definitions>
<instances> ?
<document> *
<docInfo> ?
<baseURI> ?
xs:anyURI <!-- If a document has a baseURI, then this will be used to form the
base URI for all relative URIs subject to SML URI processing
contained by that document. -->
</baseURI>
<aliases> ?
<alias> *
xs:anyURI <!-- A URI by which SML references from other documents may refer to this document. -->
</alias>
</aliases>
</docInfo>
[
<data>
xs:any<!-- At most one instance document goes here -->
</data>
|
<base64Data>
xs:any <!-- At most one base64 encoded instance document goes here -->
</base64Data>
|
<locator>
<documentURI/> ?
xs:any <!-- A URI or IRI that points to an instance document goes here -->
</locator>
]
</document>
</instances>
</model>
A document producer can specify the version of the specification
under which the current document was generated, and with which
conformance is claimed, in the SMLIFVerion attribute.
For example, if this version of SML-IF is used as the basis of a
document, the value of this attribute would be the value "1.1".
The identity element provides information
applications can use to identify and describe the set of SML
documents being interchanged. The baseURI child
element is one way to specify a base URI to be used by relative URI
references in the interchange
model. Another way to specify a base URI is to use the
document/docInfo/baseURI element. [5.3.2 Base URIs]
The SMLIFVersion attribute is defined on the
model element and may be useful when diagnosing
failures encountered while processing SML-IF documents. For
example, if a document asserts conformance with version 1.1 of the
SML-IF specification and a human can see that it is not in fact
conformant, then it is likely that the problem occurred during the
production of the document. If the same document appears to humans
to be conformant, then the focus of diagnosis might shift toward
the SML-IF consumer and its
invocation parameters.
The schemaComplete attribute is defined on the
model element and is used to indicate that the schemas
constructed from the definition documents in the interchange model
are complete, in the sense that the validity of the interchanged
SML model is fully determined by these schemas. Formally, however,
the schemaComplete attribute does not express any
assertion that the schemas so constructed are in fact complete, or
that interchange model
validation using these schemas will not result in any errors
indicating that some components are missing from the schemas. The
only formal effect of schemaComplete attribute with a
value of true or 1 is to specify
precisely the schemas with which interchange model validation is to
be performed.
The optional ruleBindings element is used to
contain information that associates rule documents with the
documents they apply to. See 4.3 Rule
Bindings for further details.
Every document in the interchange model appears as content of a
document element in either the
definitions or the instances element,
depending on whether the document in question is a model definition
or a model instance document. There can be at most one embedded
document contained by a document/data element. Both
definitions and instances are optional.
So, for example, if there are no model definition documents being
packaged, the definitions element must be omitted.
The first child of each document is typically a
docInfo element that contains a baseURI
element and a list of alias elements. The
baseURI element can be used to specify a base URI for
relative references in the document. Defining base URIs is
specified in 5.3.2 Base URIs. The
content of each alias element is a URI with no
fragment component (i.e., one with no "#" in it). Each of the
alias elements serves as a name that other documents
can use to refer to this document. Examples of how aliases are used
to handle URI references are given in 4.2 URI References.
A document in the interchange model can be represented in either
of two ways, by embedding its content, or by providing a reference
to it. Which is being used is indicated by the child of the
document element. A document can be embedded as-is or
in a base64 encoded format. In the former case, a data
element is used to contain the actual content of the document
whereas a base64Data element is used for the latter.
The base64 format is typically used for, but is not restricted to,
documents with DTD. If the document is being referenced rather than
embedded, a locator element is used to contain the
reference. The content of a locator can be a
documentURI element defined by SML-IF or anything else
understood by the SML-IF
consumer.
Although it is not fully shown in the pseudo-schema above, the
SML-IF schema has an "open content model." To provide
extensibility, essentially every element in it can contain
additional content and/or attributes from other XML namespaces.
4.2 URI
References
When processing the SML model packaged inside an SML-IF
document, certain URI references (as defined in RFC 3986
[IETF RFC 3986]) may need to be
processed to find their corresponding target. For example, in order
to assess SML validity of the interchanged model, SML references
using the SML URI Reference Scheme [SML
1.1] need to be resolved. In addition, in order to
assemble schemas from multiple schema documents as part of the
interchange model validity assessment, the schemaLocation attribute
on an xs:include element needs to be processed to
locate the schema document.
To see how these URI references are handled, consider the
following SML-IF document:
<?xml version="1.0" encoding="UTF-8"?>
<model xmlns="http://www.w3.org/ns/sml-if" version="1.0">
<identity>
<name>http://www.university.example.org/sml/models/Sample/InterDocReferences</name>
<baseURI>http://www.university.example.org/Universities/</baseURI>
</identity>
<definitions>
<document>
<data>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:include schemaLocation="http://www.university.example.org/university/enrollmodel.xsd"/>
</xs:schema>
</data>
</document>
</definitions>
<instances>
<document>
<data>
<Student xmlns="http://www.university.example.org/ns"
xmlns:sml="http://www.w3.org/2007/09/sml"
xmlns:u="http://www.university.example.org/ns">
<ID>1000</ID>
<Name>John Doe</Name>
<EnrolledCourses>
<EnrolledCourse sml:ref="true">
<!-- SML Reference to a course INside the interchange model -->
<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="true">
<!-- SML Reference to a course INside the interchange model -->
<sml:uri>
http://www.university.example.org/Universities/SFU/Courses.xml#smlxpath1(/u:Courses/u:Course[u:Name='MUSIC205'])
</sml:uri>
</EnrolledCourse>
<EnrolledCourse sml:ref="true">
<!-- SML Reference to a course OUTside the interchange model -->
<sml:uri>
http://www.university.example.org/Universities/Capella/Courses.xml#smlxpath1(/u:Courses/u:Course[u:Name='LIT103'])
</sml:uri>
</EnrolledCourse>
</EnrolledCourses>
</Student>
</data>
</document>
<document>
<!-- The following alias matches the first course referenced above -->
<docInfo>
<aliases>
<alias>http://www.university.example.org/Universities/MIT/Courses.xml</alias>
</aliases>
</docInfo>
<data>
<Courses xmlns="http://www.university.example.org/ns">
<Course>
<Name>PHY101</Name>
</Course>
<Course>
<Name>MAT200</Name>
</Course>
</Courses>
</data>
</document>
<document>
<docInfo>
<baseURI>SFU/Courses.xml</baseURI>
<!-- The following alias matches the second course referenced above (after
being converted to an absolute URI) -->
</aliases>
<alias>SFU/Courses.xml</alias>
</aliases>
</docInfo>
<data>
<Courses xmlns="http://www.university.example.org/ns">
<Course>
<Name>ENG106</Name>
</Course>
<Course>
<Name>MUSIC205</Name>
</Course>
</Courses>
</data>
</document>
</instances>
</model>
When not packaged in an SML-IF document, certain URI references
(e.g. values of sml:uri elements or certain
schemaLocation attributes) are dereferenced to find
their corresponding document. When these references are packaged in
an SML-IF document, consumers of the SML-IF document need to first
examine whether the target document or element is packaged in the
same SML-IF document. To determine this, the fragment component, if
any, is temporarily ignored to form a URI. This URI is then
compared against the alias URIs of packaged model
documents.
If the URI is equal to the URI in an alias element
(see 5.3.1 URI equality), the
SML-IF consumer will not
attempt to look for targets of this URI outside of the SML-IF
document, although there may exist a document retrievable at this
URI. If the URI is not equal to the URI in any alias
element, then the SML-IF document does not contain the
corresponding target of the original URI reference. The consumer
may or may not attempt to look for targets outside of the SML-IF
document, depending on the nature of the URI reference. Formal
rules about how URI references are processed are defined in section
5.3.4 URI Reference
Processing.
Several examples of resolving references can be seen in the
example SML-IF document shown above, illustrating the use of both
relative and absolute alias URI values. In the first example, a
reference with an absolute URI, the following SML reference, must
first be separated into its document URI and fragment
components:
http://www.university.example.org/Universities/MIT/Courses.xml#smlxpath1(/u:Courses/u:Course[u:Name='PHY101'])
After removing the fragment, the document portion of the
reference is:
http://www.university.example.org/Universities/MIT/Courses.xml
This document URI is equal to the URI listed in an
alias accompanying the Courses document.
So, by applying the fragment in the URI reference to the
Courses document, we determine that the reference is
to the Course element whose Name element
has "PHY101" as its content.
The second example reference, using a relative URI, is processed
similarly. The full reference is:
http://www.university.example.org/Universities/SFU/Courses.xml#smlxpath1(/u:Courses/u:Course[u:Name='MUSIC205'])
After removing the fragment, the document portion of the
reference is:
http://www.university.example.org/Universities/SFU/Courses.xml
This URI is equal to an alias defined on the last
instance document in the interchange model, after the
model/identity/baseURI content is applied to the
relative URI contained by the document’s alias
element. So, by applying the fragment in the reference to the
Courses document, we determine that the reference is
to the Course element whose Name element
has "MUSIC205" as its content.
The third example, showing an unresolved reference, is processed
similarly. The full reference is:
http://www.university.example.org/Universities/Capella/Courses.xml#smlxpath1(/u:Courses/u:Course[u:Name='LIT103'])
After removing the fragment, the document portion of the
reference is:
http://www.university.example.org/Universities/Capella/Courses.xml
This document URI is not equal to the URI in any
alias element. This means that it is an unresolved SML
reference.
The URI:
http://www.university.example.org/university/enrollmodel.xsd
(value of the schemaLocation attribute on the
include element) is not equal to any
alias. The SML-IF
consumer may or may not attempt to locate a schema document
using this URI reference.
4.3 Rule
Bindings
[SML 1.1] uses Schematron
patterns embedded in SML schemas and in separate explicitly bound
rule documents to express constraints that cannot be expressed in
XML Schemas. Schematron patterns embedded in SML Schema documents
all have well defined targets. [SML
1.1] permits models in which rule documents apply to
all, none, or subsets of the model's documents. SML-IF uses the
list of ruleBinding elements contained in the optional
ruleBindings element to associate rule documents with
the documents in the interchange model to which they apply. Each
ruleBinding associates the documents having an alias
beginning with the URI prefix given in the
documentAlias with the rule documents having an alias
beginning with the prefix given in the ruleAlias. So,
for example, the ruleBinding:
<ruleBinding>
<documentAlias="http://www.university.example.org/sml/infrastructure/"/>
<ruleAlias="http://www.university.example.org/sml/infrastructurerules/"/>
</ruleBinding>
Would associate documents that have the aliases such as:
http://www.university.example.org/sml/infrastructure/server427.xml
and
http://www.university.example.org/sml/infrastructure/switch6E.xml
with rule documents that have aliases such as:
http://www.university.example.org/sml/infrastructurerules/assetistracked.sch
and
http://www.university.example.org/sml/infrastructurerules/managedbycorporate.sch
SML-IF specifies rule bindings among documents in the
interchange model. It does not specify rule bindings that apply to
documents not in the interchange model. That said, it is often the
case that the intent of transferring an SML-IF document is to
relate its contents with other SML documents not in the interchange
model. For example, the intent might be to merge the interchange
model with an existing SML model. In such cases the context of use
may choose to extend the definition of ruleBinding to
bind documents not in the interchange model. For example, if the
interchange model is merged into an existing model, the merge
process might choose to extend the definition of
ruleBinding elements to bind rule documents in the
interchange model to documents in the merged model that weren't
included in the interchange model.
4.4 Schema
Bindings
Schema documents can be connected with other schema documents
using composition features provided by XML Schema. This includes
xs:include, xs:redefine, and
xs:import. A schema document's validity may depend on
other schema documents it includes/redefines/imports, or even other
schema documents that include/redefine/import it. When performing
interchange model
validation over the SML model packaged in an SML-IF instance,
an SML-IF consumer must draw associations between XML Schema
definition documents and instance documents, both to completely
validate XML Schema documents themselves and to establish the
schema-validity of the instance documents.
The XML Schema specification provides more flexibility in
constructing the schema used for assessment than is appropriate for
the semantics defined by SML and SML-IF for interchange model validation.
-
It allows XML Schema processors latitude in terms of locating
schema documents (resolving namespace and schema location
attributes) and composing schema documents together to form a
single schema.
-
Schema location attributes can be ignored in some cases
(xsi:schemaLocation in instance documents and
schemaLocation attribute on xs:import)
and allowed to "fail to resolve" in others
(schemaLocation attribute on xs:include
and xs:import).
-
Multiple imports of the same namespace allow all but the first
one to be ignored.
As a result, SML-IF cannot guarantee general case
interoperability based only on XML Schema and, therefore, needs to
specify how to determine such associations. This section describes
a method to achieve this goal.
An SML-IF document can be:
-
Schema-complete - All schema documents are included in
the SML-IF document, either as an 5.2.1 Embedded Documents or as
5.2.2 Referenced
Documents.
-
Schema-incomplete - Some required schema documents may
not be included in the SML-IF document, either as an embedded
document or a referenced document.
It is necessary for an SML-IF producer to declaratively
distinguish between these two cases because making that distinction
is not always possible for an SML-IF consumer based on the content alone.
SML-IF uses the schemaComplete attribute on the
model element to indicate whether this SML-IF document
includes all necessary schema definition documents. When this
attribute is specified with a value of "true", then the schema
validity of the schema definition documents and instance documents
depend only on built-in components or components from definition
documents included in the SML-IF document. Built-in components
include:
-
four xsi: attributes (defined by XML Schema)
-
all schema built-in types (xs:anyType and simple types defined
in XML Schema Part 2)
-
sml:ref attribute declaration
-
sml:uri element declaration
An SML model represented by a schema-incomplete SML-IF document
is not necessarily invalid. However, SML-IF cannot guarantee
interoperability for a schema-incomplete SML-IF document.
SML-IF uses a list of schemaBinding elements
contained in the optional schemaBindings element to
associate a namespace with a set of schema documents in the
interchange model and the instance documents that should be
validated against this set of schema documents. Each
namespaceBinding child of a schemaBinding
element associates the namespace specified in its
namespace attribute with the schema documents whose
aliases are specified in its aliases attribute. In
addition, the instance documents that are to be assessed against
this set of schemas are specified in the documentAlias
child element of the same schemaBinding element.
The following example illustrates schema bindings.
<schemaBindings>
<!-- Each "schemaBinding" element corresponds to a schema and model
instance documents that are assessed against this schema -->
<schemaBinding>
<!-- all "namespaceBinding" children together build the schema -->
<namespaceBinding namespace="ns1" aliases="xsd1-a xsd1-b"/>
<namespaceBinding namespace="ns2" aliases="xsd2-v1"/>
<!-- list all applicable instances; same as for rule bindings -->
<documentAlias>doc1</documentAlias>
<documentAlias>doc2-v1-a</documentAlias>
<documentAlias>doc2-v1-b</documentAlias>
</schemaBinding>
<schemaBinding>
<namespaceBinding namespace="ns1" aliases="xsd1-a xsd1-b"/>
<namespaceBinding namespace="ns2" aliases="xsd2-v2"/>
<documentAlias>doc1</documentAlias>
<documentAlias>doc2-v2</documentAlias>
</schemaBinding>
</schemaBindings>
<definitions>
<!-- schema documents for xsd1-a, xsd1-b, xsd2-v1, xsd2-v2 -->
</definitions>
There are cases where many instance documents use the same
schema. In this case, it is desirable to have a default schema
binding rather than specifying a schemaBinding that
lists all these instance documents. The defaultSchema
can be used to cover instance documents not included in any
otherschemaBinding as in the following example.
<schemaBindings>
<!-- The "defaultSchema" element corresponds to a schema that governs
all instance documents *not* included in any "schemaBinding". -->
<defaultSchema>
<!-- all "namespaceBinding" children together build the schema -->
<namespaceBinding namespace="ns1" aliases="ns1.xsd"/>
<namespaceBinding namespace="ns2" aliases="ns2.xsd"/>
</defaultSchema>
</schemaBindings>
There may be cases where an instance document should not be
bound to any schema, including the default schema. The
noSchemaBinding element can be used in this case to
cover such instance documents as in the following example.
<schemaBindings>
<!-- The "noSchemaBinding" element contains the aliases for
all instance documents *not* bound to any schema. -->
<noSchemaBinding>
<documentAlias>doc-a</documentAlias>
<documentAlias>doc-b</documentAlias>
</noSchemaBinding>
</schemaBindings>
4.5
Interoperability of SML Models
The goal of SML-IF is to enable the exchange of SML models.
However, this interoperability goal is affected by several aspects
of SML models.
-
Use of the SML URI Reference Scheme as defined in the SML
specification is the only guaranteed way of achieving
interoperability for all SML references in the model. Use of any
other reference scheme requires that the SML-IF consumer know about its use in the
document and understand how to dereference it.
-
SML documents can be included by reference using the
locator element and, therefore, are not directly
embedded in the SML-IF document. This can be very useful,
especially when the SML-IF document is large or when the documents
are readily accessible to the consumer. However, the
locator element may be ignored by the consumer, may
not resolve, or may resolve to different resources in different
contexts. Because of these uncertainties, interoperability is not
guaranteed when documents are included by reference.
-
The SML-IF document may be schema-incomplete [4.4 Schema Bindings]. An SML model
represented by a schema-incomplete SML-IF document is not
necessarily invalid. However, SML-IF cannot guarantee
interoperability for a schema-incomplete SML-IF document.
-
The SML-IF document may use reference schemes that do not use
target-complete identifiers. In addition to the requirements
imposed by SML on reference scheme definitions, SML-IF imposes
additional requirements on references schemes that do not use
target-complete identifiers in order to make them useful in the
context of SML-IF [5.3.4 URI Reference
Processing].
-
The presence of relative references subject to SML-IF URI
processing introduces the necessity to transform them into absolute
references [5.3.4 URI Reference
Processing]. SML-IF provides two alternative mechanisms
[5.3.2 Base URIs] for doing so, one
of which is deprecated. SML-IF producers can construct SML-IF
documents that use either only absolute URIs or both base URI
mechanisms in order to achieve interoperability with the maximum
number of consumers.