/[volute]/trunk/projects/grid/notes/schema-versioning/schemaVersioning.tex
ViewVC logotype

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 3008 - (show annotations)
Fri Jun 19 10:37:09 2015 UTC (6 years, 3 months ago) by harripa@gmail.com
File MIME type: application/x-tex
File size: 4292 byte(s)
skeleton of note
1 \documentclass[11pt,a4paper]{ivoa}
2 \input tthdefs
3
4 \usepackage{listings}
5 \lstloadlanguages{sh,make,[latex]tex}
6 \lstset{flexiblecolumns=true,numberstyle=\small,numbers=left,
7 identifierstyle=\texttt,defaultdialect=[latex]tex,language=tex}
8
9 \usepackage{todonotes}
10
11 \usepackage[utf8]{inputenc}
12
13 \definecolor{texcolor}{rgb}{0.4,0.1,0.1}
14 \newcommand{\texword}[1]{\texttt{\color{texcolor} #1}}
15
16 \iftth
17 \newcommand{\BibTeX}{BibTeX}
18 \fi
19
20 \iftth
21 \newcommand{\comicstuff}[1]{
22 \begin{html}<span class="comic">#1</span>\end{html}}
23 \else
24 \newcommand{\comicstuff}[1]{(HTML exclusive material)}
25 \fi
26 \customcss{custom.css}
27
28 \title{XML Schema Versioning Policies}
29
30 \ivoagroup{Standards and Processes}
31
32 \author[http://www.ivoa.net/cgi-bin/twiki/bin/view/IVOA/PaulHarrison]{Paul Harrison}
33 \author[http://www.ivoa.net/cgi-bin/twiki/bin/view/IVOA/MarkusDemleitner]{Markus Demleitner}
34 \author[http://www.ivoa.net/cgi-bin/twiki/bin/view/IVOA/BrianMajor]{Brian Major}
35 \author[http://www.ivoa.net/cgi-bin/twiki/bin/view/IVOA/PatDowler]{Pat Dowler}
36
37 \editor{Paul Harrison}
38
39 \previousversion{This is the first public release}
40
41
42 \begin{document}
43
44 \SVN$Rev: 2940 $
45 \SVN$Date: 2015-05-04 10:52:00 +0100 (Mon, 04 May 2015) $
46 \SVN$URL: https://volute.googlecode.com/svn/trunk/projects/ivoapub/ivoatexDoc/ivoatexDoc.tex $
47
48 \begin{abstract}
49 This note describes the recommended practice for the evolution of IVOA
50 standard XML schemata. The criteria for deciding what might be considered major
51 and minor changes and the policies for dealing with each case are described.
52 \end{abstract}
53
54
55 \section*{Acknowledgments}
56
57 The content of this note is derived from discussions that occurred in a splinter
58 session at the June 2015 IVOA interoperability meeting in Sesto, Italy.
59
60 \section{Introduction}
61
62 Many of the standard protocols and data models developed by
63 the International Virtual Observatory Association (IVOA) have used XML
64 \citet{std:XML} for message or object serialization. The content of this XML has
65 been defined using XML schema definition language (XSD) \citet{std:XSD}. As
66 these are normative texts, attention to detail is very important, and being able to rigorously track changes to the documents is highly advantageous.
67
68
69 As mandated by \citet{std:docSTD},
70
71 \url{http://www.xfront.com/Versioning.pdf}
72
73 \section{Schema Use}
74 \subsection{Server use}
75 \subsection{Client use}
76 \section{Schema Versioning}
77 \subsection{Minor changes}
78 \subsubsection{Determining if the changes are indeed minor}
79 \subsection{Indicating the version number}
80 \subse
81 \section{Hosting the Schema on the IVOA web site}
82 Existing practice has used namespace URIs that correspond to a URL that points
83 to the
84 \section{Summary of Recommendations}
85 This section summarizes the main recommendations contained within this document.
86
87 \begin{itemize}
88 \item Namespace URL should contain only the associated standard major number
89 (x.0).
90
91 \item Include a version attribute in the top level element to allow client
92 version discovery - this version number should include the full standard version
93 number including the minor version increment. - 1.1
94
95 \item Set the version attribute of the <schema> element in the XSD to be equal
96 to the full standard version including the minor version increment and document status - to
97 allow software writers to be clear about exactly which version of the schema
98 they are using 1.1-20150607-WD
99
100 \item Minor version changes should not break clients - i.e. in general they
101 should only add new elements/attributes, not remove formerly valid content -
102 correspondingly, this means that clients should quietly ignore things that they
103 do not know about in the XML - i.e. they should not automatically issue an error
104 if schema validation fails (though of course if they can determine that the
105 validation error is because of a missing required element then they should
106 issue an error).
107 \item In contrast servers must produce strictly valid documents, and service
108 validators must test strict validity against the relevant schema (discovered
109 from the namespace and the version element)
110 \end{itemize}
111
112
113
114
115 \appendix
116
117
118 \section{Changes from Previous Versions}
119
120 No previous versions yet.
121 % these would be subsections "Changes from v. WD-..."
122 % Use itemize environments.
123
124
125 \bibliography{ivoatex/ivoabib}
126
127
128 \end{document}

msdemlei@ari.uni-heidelberg.de
ViewVC Help
Powered by ViewVC 1.1.26