# Diff of /trunk/projects/grid/notes/schema-versioning/schemaVersioning.tex

revision 3141 by harripa, Thu Sep 3 07:45:37 2015 UTC revision 3142 by harripa, Wed Oct 28 14:45:14 2015 UTC
# Line 144  Line 144
144  circumstances in which it is permissible to make changes to a schema and not  circumstances in which it is permissible to make changes to a schema and not
145  change its namespace.  change its namespace.
146
\url{http://www.xfront.com/Versioning.pdf}\todo{What's the meaning of
this URI?}

147
148  \section{Schema Versioning}  \section{Schema Versioning}
149  It is the case that two XML instances are formally regarded by XML  It is the case that two XML instances are formally regarded by XML
# Line 159  Line 156
156  changes.  changes.
157  \subsection{Minor changes}  \subsection{Minor changes}
158  In general the class of changes that might be considered minor are those  In general the class of changes that might be considered minor are those
159  which; \todo{Actually, I'd prefer to have a functional criterion here,  which allow legacy clients (i.e. without rewriting) to keep functioning with
160  along the lines of: when legacy clients ignoring any additional  content produced against the new schema.
161  content keep functioning''}  Specific structual changes to the schema that allow that goal to be achieved
162    include:
163
164  \begin{itemize}  \begin{itemize}
165    \item Do not remove concepts (i.e. elements or attributes) from the old    \item Not removing concepts (i.e. elements or attributes) from the old
166    schema.    schema.
167    \item Make any new concepts that are introduced optional.    \item Making any new concepts that are introduced optional.
168  \end{itemize}  \end{itemize}
169  Even with the restrictive conditions above it is still necessary that any  Even with the restrictive conditions above it is still necessary that any
170  consumer of XML instance documents takes the approach that it does not do strict  consumer of XML instance documents takes the approach that it does not do strict
# Line 251  Line 249
249  As mentioned in the introduction the schemata are typically associated with a  As mentioned in the introduction the schemata are typically associated with a
250  particular version of a standard and so are typically included in an appendix of  particular version of a standard and so are typically included in an appendix of
251  the standard. In addition they are located on the ivoa website  the standard. In addition they are located on the ivoa website
252  \url{http://www.ivoa.net/schema} to allow software authors interactively to  \url{http://www.ivoa.net/xml} to allow software authors interactively to
254
255  The availability of the schemata via the IVOA web site also  The availability of the schemata via the IVOA web site also
# Line 264  Line 262
262  namespace is owned'' by the IVOA and there is therefore much less chance of  namespace is owned'' by the IVOA and there is therefore much less chance of
263  accidental clashes of namespaces.  accidental clashes of namespaces.
264
265    Thus a current schema is usually available at two URLs on the IVOA site;
266    \begin{enumerate}
267      \item at a URL that corresponds to the namespace \newline e.g.
268      \texttt{http://www.ivoa.net/xml/UWS/v1.0}
269      \item at a URL that corresponds to the filename of the schema \newline e.g.
270      \texttt{http://www.ivoa.net/xml/UWS/UWS-v1.0.xsd}
271    \end{enumerate}
272
273  As this note now recommends that there are potentially many minor versions of a  As this note now recommends that there are potentially many minor versions of a
274  schema all in the same namespace this one-to-one correspondence between  schema all in the same namespace the actual file than the first from of the URL
275  namespace and URL needs to be broken if all versions of the XSD schema documents  above points to must be updated when a new minor version is published. The
276  are to be available to download. It is recommended that the URL that  various minor versions of a particular schema should be available at the
277  corresponds to namespace be the location of the the latest (possibly minor)  filename'' style URLs of the second kind. It should be noted that the
278  version of schema, and that the older minor versions of the schema be moved to  actual file pointed to by the namespace'' style URL should only be updated to
279  be available at other locations on the IVOA web site.  point to the new minor version when the associated standard has reached the
280  \todo{We need to determine what would be a good URL strategy that is not too  recommendation'' stage.
burdensome on the IVOA document coordinator to implement - need to think up a
general scheme for finding old versions.}
281
282  \subsection{Client use of schema}  \subsection{Client use of schema}
283  Using this strategy means that client software that simply uses validation with  Using this strategy means that client software that simply uses validation with
# Line 299  Line 303
303  This section summarizes the main recommendations contained within this document.  This section summarizes the main recommendations contained within this document.
304
305  \begin{itemize}  \begin{itemize}
306  \item The namespace URL should contain only the associated standard major number  \item The namespace URI should contain only the associated standard major number,
307  (x.0), and therefore does not change when a minor version increment occurs.  and therefore does not change when a minor version increment occurs.
308  e.g.\ \texttt{http://www.ivoa.net/xml/UWS/v1.0}\todo{Markus believes the  e.g.\ \texttt{http://www.ivoa.net/xml/ABC/v1}. However, existing namespace URIs
309  .0'' should not be present here.  Namespace URIs should always point  which contain a \texttt{.0}'' minor increment suffix should not be changed to
310  to major versions only.}  conform to this rule.
311
312  \item Include a \xmlel{version} attribute in the top level element to allow  \item Include a \xmlel{version} attribute in the top level element to allow
313  client version discovery - this version number should include the full standard version  client version discovery - this version number should include the full standard version

Legend:
 Removed from v.3141 changed lines Added in v.3142