1. Introduction
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 the model portrays.
The SML Specification identifies two categories of model definition
documents that participate in model validation: Schema documents and
rule documents. Schema documents in a model are XML documents that
conform to the SML-defined extensions to XML Schema [XML Schema Structures, XML Schema Datatypes].
Rule documents in a model include XML documents that conform to the SML-defined
extensions of Schematron [Schematron].
To ensure accurate and convenient interchange of the documents that
make up an SML model or a portion of an SML model, it is useful to
define an implementation-neutral interchange format that preserves the
content and interrelationships among the documents. This specification
defines a standard format called the SML Interchange Format (SML-IF)
for this purpose.
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.
2. Informal Description
To represent an SML model in a standard way for interchange, three
topics need to be addressed.
Packaging: The collection of XML documents that make up a
model (or model portion) 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.
Since documents may have been signed using XML Signature [XML-Signature] or have had cryptographic digests made of them
for other purposes, documents exchanged using SML-IF must be invariant
with respect to XML Canonicalization. [Canonical XML]
Explicit inter-document 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 uses such
references for many purposes, and permits many different addressing
mechanisms. The arcs in SML models are an obvious example. Less
obvious are such references as xsi:schemaLocation. The
SML-IF specifies a uniform mechanism for unambiguously resolving
references among the documents being interchanged.
Binding of rule documents to the documents to which they
apply: SML 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.
2.1 Packaging
An SML-IF document packages a collection of SML 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
pseudoschema 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/2007/09/sml-if"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
<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 smlerr:localizationid=
"xs:anyURI URI identifying the translation
resource for the display name" ?> ?
xs:string Descriptive name of model intended for display
<displayName/>
<description smlerr:localizationid=
"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>
<definitions> ?
<document> *
<docInfo> ?
<aliases> ?
<alias> *
xs:anyURI A URI by which this document may be referred to
</alias>
</aliases>
</docInfo>
[
<data>
xs:any <!—A definition document goes here>
</data>
|
<locator>
<documentURI/> ?
xs:any <!—A reference to a definition document goes here>
</locator>
]
</document>
</definitions>
<instances> ?
<document> *
<docInfo> ?
<aliases> ?
<alias> +
xs:anyURI A URI by which this document may be referred to
</alias>
</aliases>
</docInfo>
[
<data>
xs:any<!—An instance document goes here>
</data>
|
<locator>
<documentURI/> ?
xs:any <!—A reference to an instance document goes here>
</locator>
]
</document>
</instances>
</model>
The identity element provides information applications
can use to identify and describe the set of SML documents being
interchanged.
The optional ruleBindings element is used to contain
information that associates Schematron Rule documents with the
documents they apply to. See 2.3 Rule Document Bindings
for further details.
The set of SML documents that are interchanged in an SML-IF
document is called the interchange set. Every document in the
interchange set 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. 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 (indirectly) contains a list of
alias elements whose content is a URI with no fragment
components (i.e., one with no "#" in it). Each of these URIs serves as
a name that other documents can use to refer to this
document. Examples of how aliases are used to resolve inter-document
references are given below.
A document in the interchange set 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 next child of the
document element. If the document is to be embedded, a
data element is used to contain the actual content of the
document. If the document is to be referred to, a locator
element is used to contain the reference. Syntactically, the content
of a locator can be a documentURI element
defined by SML-IF or anything else understood by the
consumer. Typically it is a URI, an XLink [XLink], or
a Web Services Addressing endpoint reference [WS-Addressing Core].
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.
2.2 Inter-document References
Explicit inter-document references can appear in SML documents as
elements. For example, model arcs are represented by elements marked
with the global attribute
sml:ref="true". Inter-document references can
also appear as attributes. For example, an
xsi:schemaLocation attribute provides a hint about where
to find a relevant schema document.
To see how inter-document references are handled, consider the
following SML-IF document:
<?xml version="1.0" encoding="UTF-8"?>
<model xml:base="http://www.university.example.org/sml/models/"
xmlns="http://www.w3.org/2007/09/sml-if"
xmlns:sml="http://www.w3.org/2007/09/sml"
xmlns:xml="http://www.w3.org/XML/1998/namespace"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="1.0">
<identity>
<name>http://www.university.example.org/sml/models/Sample/InterDocReferences</name>
</identity>
<instances>
<document>
<data>
<Student xmlns="http://www.university.example.org/ns"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.university.example.org/ns
http://www.university.example.org/university/enrollmodel.xsd">
<ID>1000</ID>
<Name>John Doe</Name>
<EnrolledCourses>
<EnrolledCourse sml:ref="true">
<sml:uri>
http://www.university.example.org/Universities/MIT/Courses.xml#xmlns(u=http://www.university.example.org/ns)
xpointer(/u:Courses/u:Course[u:Name='PHY101'])
</sml:uri>
</EnrolledCourse>
<EnrolledCourse sml:ref="true">
<sml:uri>
http://www.university.example.org/Universities/Capella/Courses.xml#xmlns(u=http://www.university.example.org/ns)
xpointer(/u:Courses/u:Course[u:Name='LIT103'])
</sml:uri>
</EnrolledCourse>
</EnrolledCourses>
</Student>
</data>
</document>
<document>
<docInfo>
<aliases>
<alias>/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>
</instances>
</model>SML-IF uses equivalence of URIs to resolve inter-document
references among documents being interchanged. For more on URI equivalence and
resolving inter-documents references see sections 3.4.1 URI equivalence and
3.4.6 Resolving Inter-document References.
Although the example above defines the xml:base attribute
on the document element, the xml:base attribute may also
be defined on other element information items.
With the exceptions explained in the normative part of this
specification, content whose type is anyURI or a type
derived from anyURI and is contained in a document in the
interchange set is considered to be an inter-document reference.
If the URI in such a reference is equivalent to the URI in an
alias, the reference is to the document with that alias,
irrespective of any document that may be retrievable at this URI. If
the reference has a fragment, the fragment is applied to the
referred-to document to establish which element the reference points
to; otherwise the reference is to the root element of the referred-to
document.
If the element in a reference is not equivalent to the URI in any
alias, the reference is to some (element of a) document
not included in the interchange set. Such references are called
unresolved references.
SML-IF specifies how sets of SML documents are interchanged. If and
how an SML-IF document's interchange set relates to a complete (i.e.,
"validatible") model is implementation-defined and is not a part of this
specification. One common relationship is that the interchange set
constitutes a complete SML model. In such a case, the documents that
unresolved references refer to are simply unavailable to the
validation process. When SML-IF documents are used in other contexts,
such as when they are the content of Web services requests or
responses, the set of documents constituting a complete model may
include more or fewer documents than those in the interchange set, and
the conventions with respect to unresolved references may be
different. For example, the convention may specify how to (attempt to)
resolve such references.
The absolute URI form of every alias in an interchange, like all
absolute URIs, contains an "authority" component. A reasonable
interpretation of SML-IF aliases is that the SML-IF document
containing them is asserting that the content marked with a given
alias is a true copy of the content identified by that URI and issued
by the authority in the alias URI. Since this may or may not be true,
consumers need to be cautious with this interpretation.
Referring now to the example SML-IF document, above. The
reference:
http://www.university.example.org/Universities/MIT/Courses.xml#xmlns(u=http://www.university.example.org/ns)
xpointer(/u:Courses/u:Course[u:Name='PHY101'])
is equivalent to the URI listed in the alias
accompanying the Courses document. (i.e.,
"http://www.university.example.org/Universities/MIT/Courses.xml"). 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 "PHY101" as its content.
The reference:
http://www.university.example.org/Universities/Capella/Courses.xml#xmlns(u=http://www.university.example.org/ns)
xpointer(/u:Courses/u:Course[u:Name='LIT103'])
is not equivalent to the URI in any alias. This means
that it is an unresolved reference. Since the reference is written as
a relative reference, URI coming out of the reference resolution
algorithm:
http://www.university.example.org/Universities/Capella/Courses.xml
#xmlns(u=http://www.university.example.org/ns)
xpointer(/u:Courses/u:Course[u:Name='LIT103'])
is a hint for where to find the document.
The URI:
http://www.university.example.org/university/enrollmodel.xsd
(in the content of xsi:schemaLocation for the Student
document) isn't equivalent to any alias. Since it is
written as an absolute URI, the reference is to the document the URL
locates. The same is true for all of the absolute URIs in the
documents being interchanged:
http://www.university.example.org/ns
and
http://www.w3.org/2001/XMLSchema-instance
The other URIs in the example SML-IF document are not parts of the
SML model being interchanged, so they are not SML inter-document
references.
2.3 Rule Document Bindings
SML 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 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 set 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
set. It does not specify rule bindings that apply to documents not in
the interchange set. 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 set. For example, the
intent might be to merge the interchange set 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 set. For example, if the interchange set 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 set to documents in the merged model that weren't
included in the interchange set.
3. SML Interchange Format Definition (Normative)
This section normatively defines the Service Modeling Language
Interchange Format (SML-IF). It is not intended as
motivational or introductory material. For such material, please see
the non-normative informal description, above. Instead, this section
is intended to concisely define the requirements that SML-IF documents must
adhere to and to define how inter-document references contained in
them are to be interpreted by consumers of SML-IF documents.
3.1 Conformance Criteria
An XML document is a conforming SML-IF Document
if it adheres to this specification as described in the normative sections.
A program is a conforming SML-IF Producer
if it can generate a conforming SML-IF Document from an SML model.
A program is a conforming SML-IF Consumer
if it processes a conforming SML-IF Document using, in whole or part,
semantics defined by this specification. A conforming SML-IF Consumer is not
required to process all elements defined in this specification, but
any element that is processed must be processed
in a manner that is consistent with the semantics defined here.
3.2 Terminology
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].
3.3 SML-IF Documents
The purpose of SML-IF is to package the set of documents
that constitute an SML model into a standard format so that it can be exchanged in a standard way. [Definition: The SML-IF interchange set is the set of
documents that constitute the SML model to be interchanged.]
An SML-IF document MUST:
An SML-IF document MAY form a valid SML model
but it is not required to do so. Various uses of SML-IF may define
requirements with respect to model validity and the interchange set,
but this specification does not.
Each document in the interchange set MUST be represented in the SML-IF document by
a separate document element as follows:
Each definition document [Ed. note: insert link to definition]
in the interchange set MUST appear as a child
of a document element that is a child of the
definitions element of the SML-IF document. The order of
the document children is not significant.
Each instance document [Ed. note: insert link to definition] in the interchange set
MUST appear as a child of a document element that is a child
of the instances element of the SML-IF document. The order of
the document children is not significant.
Each document in the interchange set MUST be included in the SML-IF document either as an embedded document (where the
octet stream representing the document to be
included is embedded in the SML-IF
document) or by including a reference to the document.
3.3.1 Embedded Documents
If a document is to be embedded in the SML-IF document,
the octet stream representing it MUST first be
processed as follows:
Note:
If the SML-IF document uses UTF-8 encoding, the
octet-stream result of XML Canonicalization [Canonical XML] is more than sufficient to accomplish this
processing.
The resulting octet stream MUST be embedded
as the content of the data child of the
corresponding document
element.
3.3.2 Document References
If a document is to be referred to rather than embedded, a reference
to it MUST placed in the locator child of the corresponding
document element. SML-IF specifies one way such
references may be constructed, the documentURI element,
however any representation on which the producer and consumer agree may be
used. [Ed. note: the previous statement is not very portable!]
3.4 Inter-document References
3.4.1 URI equivalence
SML-IF uses URI equivalence extensively to resolve references among
documents in the interchange set. To determine whether two URIs are
equivalent, consumers MUST perform case sensitive simple
string comparison based on codepoint-by-codepoint comparison of the corresponding
characters in the URIs.
Whenever a relative URI is tested for equivalence with another URI,
SML-IF uses the [base URI] property as specified in
the Infoset [XML Information Set] to define a base URI for relative URIs.
The [base URI] property can be defined on any of the
information items in the interchange set.
3.4.2 Definition of inter-document references in SML-IF
[Definition: In the context of SML-IF, an inter-document reference is
any content in a document in the interchange set whose type is
xs:anyURI or a type derived from xs:anyURI
and whose context in the document implies that the URI can (given the
right permissions and connectivity) be dereferenced using the default
retrieval action for the URI's scheme.]
Note:
This definition WILL change to not require PSVI once the
schema binding issue is resolved.
For example, an xsi:schemaLocation attribute is
defined to be of type list of xs:anyURI. These come in
pairs, one for the namespace name, and one for a hint as to the
location of a schema document defining names for that namespace
name. This makes the "hint" URIs in xsi:schemaLocation
attributes inter-document references in the context of SML-IF. Similarly, an sml:uri element contained in an element
marked with sml:ref="true" is an inter-document
reference because its content is of type xs:anyURI and
the definition of sml:uri is that the referred-to
document can be obtained by dereferencing the URI using the default
retrieval action.
In contrast, the wsa:address in a Web
Services Addressing [WS-Addressing Core] endpoint reference
is not an inter-document reference in the context of an SML-IF
document. This is because, although a wsa:address is
defined to be of type anyURI, the action needed to
dereference the URI is not the default retrieval action for the scheme
of the URI. Instead, the action required is defined by protocol
binding used to interact with the endpoint.
SML-IF Consumers MUST interpret
xsi:schemaLocation hints and sml:uri content
used as SML reference schemes as inter-document references. SML-IF Consumers
MUST NOT interpret wsa:address content
as inter-document references.
3.4.3 SML reference schemes that are not SML-IF inter-document references
SML [SML 1.1] defines two reference
schemes, the sml:uri scheme and the EPR scheme. It also
permits new schemes to be created without limit. Schemes that do not
use URIs or whose use of URIs does not imply that the URIs may be
dereferenced for retrieval using the default action (e.g., for the
HTTP scheme, the GET method) are not inter-document references in the
context of SML-IF. Three consequences flow from this.
First, to successfully interchange documents using such schemes,
the sml:ref elements containing them
MUST also contain an sml:ref scheme that is an
inter-document reference in the SML-IF context. For example, an
sml:ref that contains an EPR scheme reference (which is
not an inter-document reference in SML-IF) could also contain an
sml:uri scheme reference (which is).
Second, the producer of the SML-IF document and the consumer of
must agree on the scheme(s) being used since SML-IF only requires
consumers to understand the sml:uri scheme.
Third, when creating a new sml:ref scheme, authors
MUST be explicit about whether the scheme is an
SML-IF inter-document reference.
3.4.4 Document aliases
In addition to containing or referring to one of the documents in
the interchange set, each document element may
(indirectly) contain a list of alias elements. Each
alias contains a URI. The set of alias URIs for a given
document constitutes the set of identifiers by which documents in the
interchange set may make inter-document references to the document in
question.
A document element containing no alias
elements signals that the document in question has no aliases. By
implication having no alias also signals that there can
be no inter-document references to it.
3.4.5 Relative references
If any inter-document reference or any alias of any document
in the interchange set is a relative URI,
then the [base URI] property as defined by Infoset [XML Information Set]
MUST be used to specify a base URI for these references.
3.4.6 Resolving Inter-document References
If the URI representing an inter-document reference contains only a
fragment, the inter-document reference is to the document in which it
occurs. Otherwise, if the URI representing an inter-document reference
is equivalent to a URI that is an alias of some document in the
interchange set, the inter-document reference is to that document. In
either case, such a reference is called "a resolved inter-document
reference." If neither of these cases applies, the inter-document
reference is to a document not included in the interchange set. Such a
reference is called "an unresolved inter-document reference."
If the URI representing a resolved inter-document reference has no
fragment, the reference is to the root element of the referred-to
document.
If the URI representing a resolved inter-document reference has a
fragment, the reference is to the element obtained by applying the
fragment to the referred-to document starting with its root
element.
3.5 Rule Document Bindings
3.5.1 URI prefix matching
To associate SML rule documents [Ed. note: add link to definition] with the subset of documents in the
model to which they apply, SML-IF uses a combination of alias
mechanism described above and URI prefix matching.
Two URIs, one called the prefix, and one called the
target participate in URI prefix matching. The target is
said to match the prefix if and only if the target, truncated to the length of
the prefix, is equivalent to the prefix as defined in section 3.4.1 URI equivalence.
3.5.2 Bindings defined
A 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 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.
The ruleBinding element is used in SML-IF to express
bindings. In any given binding the set of rule documents is that
subset of rule documents in the interchange set with an alias that
matches the URI prefix given by the content of the
ruleAlias element. The set of model documents in the
binding is that subset of the documents in the interchange set with an
alias that matches the URI prefix given by the content of the
documentAlias element. If the documentAlias
element is omitted in a ruleBinding, the set of model
documents in the binding is all documents in the interchange set.
Although SML-IF itself does not do so, various uses of SML-IF may
well choose to extend the sets of documents involved in bindings to
include documents not contained in the interchange set. For example,
if an SML-IF document is used to represent a model fragment that is
intended to be merged with some other model, it is entirely possible
that some or all of the bindings may involve not just the documents in
the interchange set, but documents in the other model.