Service Modeling Language Interchange Format Version 1.1 http://www.w3.org/TR/2007/WD-sml-if-20070926/ W3C Working Draft 26 September 2007 http://www.w3.org/TR/2007/WD-sml-if-20070926/ XML http://www.w3.org/TR/2007/WD-sml-if-20070806/ http://www.w3.org/TR/sml-if/ James Lynn HP Bhalchandra Pandit Microsoft Corporation Valentina Popescu IBM Corporation Virginia Smith HP This specification defines the interchange format for Service Modeling Language, Version 1.1 (SML) models. Markup is defined to identify the model being interchanged, to distinguish between model definition documents and model instance documents, and to bind rule documents with other documents in the interchange set. This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/. This is the second Public Working Draft of the Service Modeling Language Interchange Format Version 1.1 specification for review by W3C members and other interested parties. It has been developed by the Service Modeling Language (SML) Working Group, which is a part of the Extensible Markup Language (XML) Activity. The features and algorithms described in the normative portion of the document are specified in enough detail adequate for early implementation experiments. Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress. Comments on this document are invited and are to be sent to the public-sml@w3.org mailing list (public archive). This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy. English Last Modified: $Date: 2007/09/25 17:21:48 $ Introduction As defined in the Service Modeling Language, Version 1.1 (SML) Specification [] 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 [, ]. Rule documents in a model include XML documents that conform to the SML-defined extensions of 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. 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 [] or have had cryptographic digests made of them for other purposes, documents exchanged using SML-IF must be invariant with respect to XML Canonicalization. [] 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. 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 [] is as follows: xs:anyURI Namespace identifying the model ? xs:token ? xs:string Descriptive name of model intended for display ? xs:string Textual description of model for human consumption ? * ? ? * ? ? * xs:anyURI A URI by which this document may be referred to [ xs:any | ? xs:any ] ? * ? ? + xs:anyURI A URI by which this document may be referred to [ xs:any | ? xs:any ] 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 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 [], or a Web Services Addressing endpoint reference []. 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. 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: http://www.university.example.org/sml/models/Sample/InterDocReferences 1000 John Doe 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']) 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']) /Universities/MIT/Courses.xml PHY101 MAT200 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 and . 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. 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: 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. 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. 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. 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 []. 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. The SML-IF interchange set is the set of documents that constitute the SML model to be interchanged. An SML-IF document MUST: conform to XML [] specification. be valid under the XML Schema given in Appendix A. 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. 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: The XML declaration and document type declaration (DTD) are removed. The stream is converted to the encoding of the SML-IF document into which it will be packaged. If the SML-IF document uses UTF-8 encoding, the octet-stream result of XML Canonicalization [] 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. 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!] Inter-document References 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 [] 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. Definition of inter-document references in SML-IF 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. 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 [] 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. SML reference schemes that are not SML-IF inter-document references SML [] 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. 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. 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 [] MUST be used to specify a base URI for these references. 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. Rule Document Bindings 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 . 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. References Normative References Canonical XML, J. Boyer, Author. World Wide Web Consortium, 15 March 2001. This version of the Canonical XML Recommendation is http://www.w3.org/TR/2001/REC-xml-c14n-20010315. The latest version of Canonical XML is available at http://www.w3.org/TR/xml-c14n. Key words for use in RFCs to Indicate Requirement Levels, S. Bradner, Author. Internet Engineering Task Force, June 1999. Available at http://www.ietf.org/rfc/rfc2119.txt. Service Modeling Language, Version 1.1, John John, Editors. World Wide Web Consortium, 26 September 2007. This version of the Service Modeling Language specification is available at http://www.w3.org/TR/2007/WD-sml-20070926/. The latest version of Service Modeling Language, Version 1.1 is available at http://www.w3.org/TR/sml Information technology ― Document Schema Definition Languages (DSDL) ― Part 3: Rule-based validation ― Schematron. International Organization for Standardization and International Electrotechnical Commission, 1 January 2006. Available at http://standards.iso.org/ittf/PubliclyAvailableStandards/c040833_ISO_IEC_19757-3_2006(E).zip Web Services Addressing 1.0 - Core, M. Gudgin, M. Hadley, and T. Rogers, Editors. World Wide Web Consortium, 9 May 2006. This version of the WS-Addressing Core Recommendation is http://www.w3.org/TR/2006/REC-ws-addr-core-20060509. The latest version of WS-Addressing Core is available at http://www.w3.org/TR/ws-addr-core. Web Services Description Language (WSDL) Version 2.0 Part 1: Core Language, R. Chinnici, M. Gudgin, J-J. Moreau, S. Weerawarana, Editors. World Wide Web Consortium, 23 May 2007. This version of the "Web Services Description Language (WSDL) Version 2.0 Part 1: Core Language" Specification is available is available at http://www.w3.org/TR/2007/PR-wsdl20-20070523. The latest version of "Web Services Description Language (WSDL) Version 2.0 Part 1: Core Language" is available at http://www.w3.org/TR/wsdl20. Extensible Markup Language (XML) 1.0 (Fourth Edition), T. Bray, J. Paoli, C. M. Sperberg-McQueen, and E. Maler, Editors. World Wide Web Consortium, 10 February 1998, revised 16 August 2006. This version of the XML 1.0 Recommendation is http://www.w3.org/TR/2006/REC-xml-20060816. The latest version of XML 1.0 is available at http://www.w3.org/TR/REC-xml. XML Linking Language (XLink) Version 1.0, Steve DeRose, Eve Maler, David Orchard, Editors. World Wide Web Consortium, 27 June 2001. This version of the XLink Recommendation is http://www.w3.org/TR/2001/REC-xlink-20010627/ The latest version of XLink is available at http://www.w3.org/TR/xlink/. XML Schema Part 1: Structures Second Edition, H. Thompson, D. Beech, M. Maloney, and N. Mendelsohn, Editors. World Wide Web Consortium, 2 May 2001, revised 28 October 2004. This version of the XML Schema Part 1 Recommendation is http://www.w3.org/TR/2004/REC-xmlschema-1-20041028. The latest version of XML Schema Part 1 is available at http://www.w3.org/TR/xmlschema-1. XML Schema Part 2: Datatypes Second Edition, P. Byron and A. Malhotra, Editors. World Wide Web Consortium, 2 May 2001, revised 28 October 2004. This version of the XML Schema Part 2 Recommendation is http://www.w3.org/TR/2004/REC-xmlschema-2-20041028. The latest version of XML Schema Part 2 is available at http://www.w3.org/TR/xmlschema-2. XML-Signature Syntax and Processing, D. Eastlake, J. Reagle, and D. Solo, Editors. Internet Engineering Task Force & World Wide Web Consortium, 12 February 2002. This version of the XML-Signature Syntax and Processing Recommendation is http://www.w3.org/TR/2002/REC-xmldsig-core-20020212/. The latest version of XML-Signature Syntax and Processing is available at http://www.w3.org/TR/xmldsig-core/. XML Information Set, John Cowan and Richard Tobin, Editors. World Wide Web Consortium, 4 February 2004. This version of the XML Infoset Recommendation is http://www.w3.org/TR/2004/REC-xml-infoset-20040204/. The latest version of the XML Infoset is available at http://www.w3.org/TR/xml-infoset/. XML Base, Jonathan Marsh, Editor. World Wide Web Consortium, 27 June 2001. This version of the XML Base Recommendation is http://www.w3.org/TR/2001/REC-xmlbase-20010627/. The latest version of XML Base is available at http://www.w3.org/TR/xmlbase/. SML-IF Schema Open Issues Should the spec provide a means to designate zero or more instance documents as "root" documents for the model? Decide which elements should be changed to global. Do rule bindings need a name or identifier to enable management by consumers like repositories? Should they be moved to the SML specification? Reference: email to list 2006-11-27 from Dave Ehnebuske. Do we need a general facility to allow keyword substitutions in translated text, e.g. the localization resources named via smlerr:localizationid? How to specify that definitional schema documents should be preferentially used over all other sources when validating instances. Do we need to say whether the normative text or XSD takes precedence, should a conflict between them be found? Should elements other than be made global? If so, which ones. Remove requirement that anyURI and its derivations be treated as inter-document references; more generally, do not require PSVI to locate references. Remove requirement that SML IF documents must be encoded using UTF-8 or UTF-16.