<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE spec PUBLIC "-//W3C//DTD Specification V2.1//EN"
               "../xmlspec-v21/xmlspec.dtd" [
	<!-- ================================================================ -->
	<!ENTITY draft.day "03">
	<!ENTITY draft.month "10">
	<!ENTITY draft.monthname "Oct">
	<!ENTITY draft.year "2003">
	<!ENTITY iso6.doc.date "&draft.year;-&draft.month;-&draft.day;">
	<!ENTITY basename "http://www.w3.org/2001/tag/doc/versioning">
	<!ENTITY draftname "&basename;-&draft.year;&draft.month;&draft.day;">
]>
<spec w3c-doctype="other">
	<?CVS $Id: versioning.xml,v 1.13 2003/10/03 20:08:46 NormanWalsh Exp $?>
	<header>
		<title>[Editorial Draft] Versioning for Arch Doc</title>
		<w3c-designation>&basename;-&iso6.doc.date;</w3c-designation>
		<w3c-doctype>Proposed Text for Arch Doc</w3c-doctype>
		<pubdate>
			<day>&draft.day;</day>
			<month>&draft.monthname;</month>
			<year>&draft.year;</year>
		</pubdate>
		<publoc>
			<loc href="&draftname;">&draftname;</loc>
		</publoc>
		<!--
<latestloc>
<loc href="&draftname;">&draftname;</loc>
</latestloc>
-->
		<prevlocs>
			<loc href="&basename;">&basename;</loc>
		</prevlocs>
		<authlist>
			<author>
				<name>David Orchard</name>
				<affiliation>BEA Systems, Inc.</affiliation>
				<email href="mailto:David.Orchard@BEA.com">David.Orchard@BEA.com</email>
			</author>
			<author>
				<name>Norman Walsh</name>
				<affiliation>Sun Microsystems, Inc.</affiliation>
				<email href="mailto:Norman.Walsh@Sun.COM">Norman.Walsh@Sun.COM</email>
			</author>
		</authlist>
		<copyright>
			<p>
				<loc href="http://www.w3.org/Consortium/Legal/ipr-notice-20000612#Copyright">Copyright</loc> &#xA9; 2003
<loc href="http://www.w3.org/">W3C</loc>
				<sup>&#xAE;</sup>
(<loc href="http://www.lcs.mit.edu/">MIT</loc>,
<loc href="http://www.inria.fr/">INRIA</loc>,
<loc href="http://www.keio.ac.jp/">Keio</loc>),
All Rights Reserved. W3C
<loc href="http://www.w3.org/Consortium/Legal/ipr-notice-20000612#Legal_Disclaimer">liability</loc>,
<loc href="http://www.w3.org/Consortium/Legal/ipr-notice-20000612#W3C_Trademarks">trademark</loc>,
<loc href="http://www.w3.org/Consortium/Legal/copyright-documents-19990405">document use</loc>, and
<loc href="http://www.w3.org/Consortium/Legal/copyright-software-19980720">software licensing</loc>
rules apply.
</p>
		</copyright>
		<abstract>
			<p>This is the text that we propose for section 4.5 of the webarch doc.</p>
		</abstract>
		<status>
			<p>This document is a hacked shell for our proposed text.</p>
		</status>
		<pubstmt>
			<p>Chicago, Vancouver, Mountain View, et al.: World-Wide Web Consortium,
Draft TAG Finding, 2003.</p>
		</pubstmt>
		<sourcedesc>
			<p>Created in electronic form.</p>
		</sourcedesc>
		<langusage>
			<language id="EN">English</language>
		</langusage>
		<revisiondesc>
			<slist>
				<sitem>2003-07-29: Published draft</sitem>
			</slist>
		</revisiondesc>
	</header>
	<body>
		<div1 id="ext-version">
			<head>Extensibility and Versioning</head>
			<p>The primary motivation to allow instances of a language to be extended is to decentralize the task of designing, maintaining, and implementing extensions. It allows senders to change the instances without going through a centralized authority.  to a great extent, the Web rose dramatically in popularity because decentralized extensions to HTML, HTTP and URLs were all possible.  Each language provided explict extensibility points and rules for understanding extensions that enabled the decentralized evolution of the languages.  The support for the languages and their related rules are codified in a continuously evolving set of software agents.  The allowance for agents to continuously evolve, without a "big bang" upgrade, dir</p>
<p>It is almost unheard of for a single version of a language to be
deployed without requiring some kind of augmentation over time.
Knowing that a language will not be all things to all people, a
language designer can allow parties to extend instances of the
language or the language itself. Typically the language designer will
specify where extensions in the instance and extensions in the
language are allowed.</p>
			<p>As documents, or messages, are exchanged between agents, they
are processed. Most agents are designed to discriminate between
valid and invalid inputs. In order to have any sort of
interoperability, a language must be defined or described in some
normative way so that the terms <quote>invalid</quote> and
<quote>valid</quote> have meaning.</p>
			<p>There are a variety of tools that might be employed for this
purpose (DTDs, W3C XML Schema, RELAX NG, Schematron, etc.). These
tools might be augmented with normative prose documentation or even
some agent-specific validation logic. In many cases, the schema
language is the only validation logic that is available.</p>			
			<p>Whether you've deployed your agent on ten machines, or a
hundred, or a million, if you change a language in such a way that all
those appications will consider instances of the new language invalid,
you've introduced a versioning problem with real costs.</p>
			<p>Once a language is used outside of its development environment,
there will be some cost associated with changing it: software, user
expectations, and documentation may have to be updated to accomodate
the change. Once a language is used in multiple environments, any
changes made will introduce multiple versions of the language.</p>
	<div2 id="terminology">
				<head>Terminology</head>
				<p>Extensibility is a property that enables evolvability of software.  It is perhaps the biggest contributor to loose coupling in systems as it enables the independent and potentially compatible evolution of languages.  Languages are defined to be <termdef id="dt-extensibile" term="extensibile">
						<term>Extensible</term> if instances of the language can include terms from multiple vocabularies. </termdef>.   An extensible language is one with some syntax reserved for future use. To extend a language is to define the syntax for some of the reserved parts.</p>
<p><termdef id="dt-language" term="language">A
<term>language</term> is an identifiable set of vocabulary terms that has defined constraints.</termdef>
For example, the elements and attributes of XHTML 1.0 or the
names of built-in functions in XPath 2.0.The syntactic structure of the language is
constrained by the use of DTDs, XML Schema, other schema languages or
narrative constraints expressed in the relevant language
specification.  By language, we just mean the set of elements and
attributes, or components, used by a particular agent.
</p>
				<p>A language has one or more vocabularies.  <termdef id="vocabulary" term="vocabulary">A <term>vocabulary</term> is a set of terms</termdef>. In general, the intended meaning of a vocabulary term is scoped by
the language in which the term is found. However, there is some
expectation that terms drawn from an XML Namespace have a consistent
meaning across all languages in which they are used.</p>
				<p>An XML Namespace is a convenient container for collecting terms
that are intended to be used together within a language or across
languages. It provides a mechanism for creating globally unique names.</p>
				
				<p>
					<termdef id="instance" term="instance">An <term>instance</term> is a realization of a language</termdef>.  Documents are instances of a language.  They must have a root element in XML. </p>
				<p>
					<termdef id="content" term="content">
						<term>Content</term> is data that is part of an instance of a language.</termdef>  Content has one or more components.  </p>
				<p>
					<termdef id="component" term="component">a <term>Component</term> is a realization of a term in a language.</termdef> XML elements and attributes are components.  As a term has a name and the language has a namespace name, each component as QName, that is the combination of the namespace name and the name.</p>
				<p>The interaction between agents and
languages is described in terms of senders and receivers.
<termdef id="dt-sender" term="sender">A <term>sender</term> is an agent that creates or
produces an instance and sends it to another
agent for processing.</termdef>
					<termdef id="dt-receiver" term="receiver">A <term>receiver</term>
is an agent that consumes an instance that it obtained from a
sender.</termdef>
				</p>
				<p>These terms and their relationships are shown below</p>
				<graphic source="WebArchLanguages.gif" alt="UML diagram of language terms"/>
				<p>
					<termdef id="dt-backwards-compatible" term="backwards compatible">A language change is
<term>backwards compatible</term> if newer agents can process all instances of the old language. </termdef>
A software example is a word processor at version 5 being able to
read and process version 4 documents. A schema example is a schema at version 5 being able to
validate version 4 documents.  In the case of Web services, this means that
new Web services receivers, ones designed for the new version, will be
able to process all instances of the old language. This means that a
sender can send an old version of a message to a receiver that
understands the new version and still have the message successfully
processed.</p>
				<p>
					<termdef id="dt-forwards-compatible" term="forwards compatible">A language change is
<term>forwards compatible</term> if older agents can process all instances of the newer language.</termdef>
An example is a word processing software at version 4 being able to read and process version 5 documents.  A schema example is a schema at version 4 being able to validate version 5 documents.  In the case of Web services,
this means that existing Web service receivers,
designed for a previous version of the language, will be able to
process all instances of the new language.  This means that a sender
can send a newer version of a message to an existing receiver and still
have the message successfully processed.</p>
				<p>In broad terms, backwards compatibility means that newer senders
can continue to use existing services, and forwards compatibility
means that existing senders can use newer services</p>
				<p>The cost of changes that are not backward or forward compatible is
often very high. All the software that uses the language must be
updated to the newer version. The magnitude of that cost is directly
related to whether the system in question is open or closed.</p>
				<p>
					<termdef id="dt-closed-system" term="closed sytem">A <term>closed
system</term> is one in which all of the senders and receivers are
more-or-less tightly connected and under the control of a single
organization.</termdef> Closed systems can often provide integrity
constraints across the entire system. A traditional database is a good
example of a closed system: all of the database schemas are known at
once, all of the tables are known to conform to the appropriate
schema, and all of the elements in the each row are known to be valid
for the schema to which the table conforms.</p>
				<p>From a versioning perspective, it might be practical in a closed
system to say that a new version of a particular language is being
introduced into the system at such and such a time and all of the data
that conforms to the previous version of the schema will be migrated
to the new schema.</p>
				<p>
					<termdef id="dt-open-system" term="open system">An <term>open
system</term> is one in which some senders and receivers are loosely
connected or are not controlled by the same organization. The internet
is a good example of an open system.</termdef>
				</p>
				</div2>
			<div2 id="whyextend">
				<head>Why Extend languages?</head>
				<p>The primary motivation for allowing instances of a language to be
extended is to decentralize the task of designing, maintaining, and
implementing those extensions. It allows senders to change the instances
without going through a centralized authority. It means that changes
can occur at the sender or receiver without the language owner
approving of them. Consider the effort that the HTML Working Group put
into modularity of HTML. Without some decentralized process for
extension, every single variant of HTML would have to be called
something else <emph>or</emph> the HTML Working Group would have to
agree to include it in the next revision of HTML.</p>
				<p role="practice">Allow Extensibility: Languages designers SHOULD
create extensible languages.</p>
			</div2>
			<div2>
				<head>Identifying and Controlling Languages</head>
				<p>Some changes make a language completely incompatible with previous
versions. Changes can also be backwards and forwards compatible.
Designing languages to support compatible changes reduces the cost of
those changes.</p>
				
				<p>In an open system, it's simply not practical to handle language
evolution with universal, simultaneous, atomic upgrades to all of the
software components. Existing senders and recievers outside the
immediate control of the organization that's publishing a changed
language will continue to use the previous version for some
(possibly long) period of time.</p>
				<p>Finally, it's important to remember that systems evolve
over time and have different requirements at different stages in their
life cycle. During development, when the first version of a language
is under active development, it may be valuable to persue a much more
aggressive, draconian versioning strategy. After a system is in production and
there is an expectation of stability in the language, it may be
necessary to proceed with more caution. Being prepared to move forward
in a backwards and forwards compatible manner is the strongest
argument for worrying about versioning at the very beginning of a project.</p>
				<p>Controlling the evolution of a language relies on two assumptions:</p>
				<olist>
					<item>
						<p>The agent must understand the semantics of every valid message
that it receives. We must therefore define the semantics of messages
that contain new elements or attributes.
</p>
					</item>
					<item>
						<p>We assume that each service rejects invalid messages. Therefore,
it must be possible for our language to evolve without changing the
schema that we've defined for it.  New versions of a service might be deployed with newer schemas, but we want these new services to be able to communicate with the already deployed senders and receivers that will continue to use the old schemas.
That is why <termref def="dt-forwards-compatible">forwards compatible language</termref>
changes have to be possible without changing the schema.</p>
					</item>
				</olist>
				<p>In order for a schema to be extensible in the way described above,
to allow new elements or attributes to be added without changing the
schema, the schema must allow extension in any namespace.  This brings us to the next rule for enabling a must ignore
versioning strategy in XML languages:</p>
				<p role="practice">Any Namespace: Every language SHOULD provide for extension in any namespace. </p>
				<p>It usually makes sense to allow extension in attributes as well.</p>
				<p role="practice">Full Extensibility: All XML Elements that can allow attributes, ie ComplexTypes in XML Schema, SHOULD
allow any attributes and any elements in their content models.</p>
				<p>The corollary of extensibility in any namespace, including the language's namespace, is that a namespace does not identify a single version of a language or set of names.  A namespace identifies a compatible set of names.  </p>
				<p role="practice">Namespace identifies compatible names: The namespace name identifies names that are compatible within the same namespace name.</p>
				<p>Given that a namespace name is not for a single version of a
language or set of names, it may be useful to identify the particular
version. An example would be specifying in a policy statement the
exact language supported by a software agent. This use of version
identification could be considered each compatible "minor" version,
with the namespace name identifying the incompatible versions. </p>
				<p role="practice">Identify specific version with version attribute:
The specific version of a set of names within a given namespace may be
identified with a version attribute to differentiate between the
compatible versions</p>
			</div2>
			<div2>
				<head>Understanding Extensions</head>
				<p>The key value of the extension strategy described above is that
existing XML documents can be extended without having to change
existing implementations. For languages that are intended to be
extensible, specifications SHOULD provide a clear processing model for
extensions.
</p>
				<p role="practice">Provide Processing Model: Languages MUST
provide a processing model for dealing with extensions.</p>
				<p>Given that an existing agent cannot possibly know the intended
semantics of a component that its never seen before, only one semantic
is possible: ignore that component. We propose, therefore, that agents
<quote>must ignore</quote> elements and attributes they do not recognize.</p>
				<p>For many agents, including most Web services, the most
practical rule is: <emph>must ignore</emph>.</p>
				<p role="practice">Must Ignore: Receivers MUST ignore any XML
attributes or elements that they do not
recognize in a valid XML document.</p>
				<p>This rule does not require that the elements be physically removed;
only ignored for most processing purposes. It would be reasonable, for example,
if a logging agent included unrecognized elements in its log.  There are cases where the elements should not be physically removed.  An example is an agent that forwards the content to another receiver should preserve the unknown content.</p>
				<p>There are two broad types of languages relating to dealing with extensions.  These two types are presentation or document and data oriented agents.  For data oriented agents, such as Web services, the rule is:</p>
				<p role="practice">Must Ignore All: The Must Ignore rule applies to unrecognized elements and their descendents.</p>
				<p>agents must deal carefully with the ignored elements,
especially if any of them are counted or if the agent makes use
of information about their position.</p>
				<p>Document oriented languages need a different rule as the agent will still want to present the content of an unknown element.  The rule for document oriented agents is:</p>
				<p role="practice">Must Ignore Container: The Must Ignore rule applies only to unrecognized elements</p>
				<p>This retains the descendents of the ignored container element, such as for display purposes. </p>
				<p>In order to accomodate big bang changes when they are needed, the
must ignore rule is not expected to apply to the root element. If the
document root is unrecognized, the entire message must be
rejected.</p>
			</div2>
			<div2>
				<head>Versioning Languages</head>
				<p>The principles above distribute the notion of versioning
down into the messages. Changes that are compatible with the extension
mechanism do not require a namespace change.</p>
				<p role="practice">Re-use Namespace Names and Element Names: If
a backwards or forwards compatible change is made to an element
definition by the owner of the element's namespace, then the old
namespace name and element names SHOULD be used in conjunction with
the extensibility model.</p>
				<p>As indicated above, some changes simply introduce incompatibility.
There are a few distinct types of backwards incompatible change:</p>
				<olist>
					<item>
						<p>A required information item is added.</p>
					</item>
					<item>
						<p>The semantics of an existing information item are changed.</p>
					</item>
					<item>
						<p>The maximum number of allowable items is reduced. This change does
not guarantee incompatibility. Instance documents where the maximum
number allowable is still greater than or equal to the number of
occurrences will still be vaild. If the maximum number of allowable
items is reduced below the minimum number of a previous version, then
incompatibility is guaranteed.</p>
					</item>
				</olist>
			</div2>
			<div2>
				<head>Namespace content changes</head>
				<p>Only the owner of a namespace can change (ie. version) the
meaning of elements and attributes in that namespace.</p>
				<p role="constraint">Only Namespace Owners Change Namespace: The namespace name owner is the only entity that is allowed to change the meaning of names in a namespace.</p>
				<p>There is a school of thought that says that every extension should
be placed in a separate namespace; that after publication, no new
names should be added to a namespace. If you hold
that point of view then you may not feel that an extensibility element
is necessary or desirable.</p>
				<p>Another school of thought says that the maintainers of the language
have a right to add new names to a namespace as they see fit. There are certain advantages
associated with adding new names in the same namespace.</p>
				<olist>
					<item>
						<p>It reduces the number of namespaces needed to describe
instances of the document. There are significant convenience
advantages to using defaulted namespaces for document creation and
manipulation.</p>
					</item>
					<item>
						<p>It provides a clear separation between extensions by the
language designers and extensions by third parties.</p>
					</item>
					<item>
						<p>There may be additional benefits in code generation and reuse
if single namespace or a small set of namespaces can completely describe
the language.</p>
					</item>
				</olist>
				<p>A namespace name owner will use the lifecycle of the namespace as one of the factors in determining whether to revise the namespace or not.  Typically, the changes during development are not compatible changes.  The author of namespaces that are under development will typically follow a "big bang" approach.  This helps reduce the number of potentially buggy or immature implementations that are deployed.   A W3C specification is a good illustrative example.  It will probably change namespace names for each working draft.  The Candidate Recommendation, Proposed Recommendation and Recommendation namespaces names should only be changed if compatibility is not achieved.</p>
			</div2>
		</div1>
	</body>
</spec>

