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.