From http://www.jwz.org/xscreensaver/xscreensaver-5.35.tar.gz
[xscreensaver] / hacks / config / xss.xsd
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!-- xscreensaver, Copyright (c) 2001-2005 Jamie Zawinski <jwz@jwz.org> -->
3 <!--
4  Permission to use, copy, modify, distribute, and sell this software and its
5  documentation for any purpose is hereby granted without fee, provided that
6  the above copyright notice appear in all copies and that both that
7  copyright notice and this permission notice appear in supporting
8  documentation.  No representations are made about the suitability of this
9  software for any purpose.  It is provided "as is" without express or
10  implied warranty.
11 -->
12 <!--  XScreenSaver schema version 0.5
13
14 This schema validates the format of the XScreenSaver configuration files.
15
16 The notices shown above, appear at the top of the source of 'demo-Gtk-conf.c'.
17 Since this schema (attempts to) describe the format of the existing
18 XScreenSaver configuration files, it seems appropriate to reproduce them here.
19 If it is not appropriate, please ignore/remove them rather than sue me.
20
21 To check a savername.xml, reference this XSD from the file and validate it at
22   http://www.w3.org/2001/03/webdata/xsv
23
24 ** Background
25 Andrew Thompson defined a DTD based on his understanding of the
26 XScreenSaver configuration files after examining the files..
27 xscreensaver-4.22
28   |- hacks
29   |    |- config
30   |         README
31   |         *.xml
32   |- driver
33        demo-Gtk-conf.c
34
35 Paul Dennis generated an XSD file (xscreensaver.xsd) from the DTD.
36 This is a stricter version of that XSD, with more comments and
37 documentation by Andrew Thompson.
38
39 Note that Andrew does not program in c, and has not had the
40 opportunity to see XScreenSaver in action (he runs Windows),
41 so some of the details of the schema may be incorrect.  It aims
42 to be cautious, and thus might be more strict than is actually
43 required.
44
45 ** .XSD started as version 0.1
46 - generated from the DTD.
47 - checked parameter types
48   - mostly as xs:string, except for..
49   - ID's - checked as xs:ID.
50 - provided grouping parse logic, but specified elements
51     with maxOccurs 'unbounded'
52
53 ** Tightened parsing in 0.2
54 - The only field still defined as xs:string is the _description.
55 - A substitutionArgumentType has been introduced to lock the form of
56     the arg to '-lettersandnumbers %'
57 - An argumentType has been introduced to ensure other
58     arg/arg-set/arg-unset attributes begin with '-' and
59     are followed by at least one letter or number.
60 - Float and integer numeric values (low/high/default) are checked as xs:decimal
61 - Remaining attributes were tightened from xs:string to xs:token.
62
63 ** Tightened parsing in 0.3
64   * Note that no maximums at all are stated in the XScreenSaver README!
65 - maxOccurs lowered from 'unbounded' to
66   - screensaver: '200' components/groups
67   - screensaver: '40' commands/fullcommands
68   - select: '100' options
69   - hgroup: '6' components/groups per row
70   - vgroup: '40' components/groups per column
71 - maxLength of _description set to '2000' chars.
72
73 ** Changes in version 0.4 - Strict
74     After testing against the configuration files of the XScreenSaver
75     hacks, the following changes were made..
76 - Added (+ _ / $) to allowable characters for substitutionArgumentType
77     & argumentType, but tightened baseType to xs:token
78 - maxOccurs changed to
79   - screensaver: '200' -> '30' components/groups
80       (xmountains.xml has 24)
81   - screensaver: '40' -> '10' commands/fullcommands
82   - select: '100' -> '200' options
83       (to account for polyhedra.xml, which has 152 options!)
84   - hgroup: '6' -> '4' components/groups per row
85       (glplanet.xml has 4)
86   - vgroup: '40' -> '10' components/groups per column
87       (bsod.xml has 9)
88 - maxLength of _description changed from '2000' to '3000' chars,
89     (covers the largest _description, 'jigglypuff.xml', at 852 chars,
90     'magicrainbow.xml', at 2837 chars.)
91 - introduced idType to facilitate maintenance between the
92     strict and loose schemas.
93
94 ** Changes in version 0.4 - Loose
95 - made _label of number element optional (when using sliders, some
96     developers put what would normally appear in the _label, as a
97     prefix to _low-label instead)
98 - widens the idType base type from xs:ID to xs:token.  Since the ID is
99     unimplemented and will most likely remain so, it makes little
100     sense to ensure they are unique & valid ID's.
101
102 ** Changes in 0.5 - Strict
103 - Minor typos. to 0.4 docs fixed.
104 - Since both the XScreenSaver code and Saverbeans SettingsDialog
105 seem tolerant to the _label of the number element missing, it is
106 marked as 'optional' now, even in the strict version.
107
108 ** Limits: This version
109 - specifies the 'arg-set'/'arg-unset' of 'boolean' as optional, whereas it
110     requires exactly one of either 'arg-set' or 'arg-unset'.
111 - cannot properly distinguish between the 'slider' and 'spinbutton' types
112     of the 'number' element.  As a result of that, '_low-label'/'_high-label'
113     are specified as not required, whereas they are actually undefined for
114     'spinbutton' and required for 'slider'.
115 - has no checks to ensure that 'default' values of ranges in the
116     number element fall between 'low' & 'high' values.
117 - Selects can have no more than one option missing an arg-set attribute. 
118 - Arguments must be unique, but this schema does not check that.
119 - _label is effectively optional for the slider type of the number element,
120     since this info can be preprended to the _low-label, but no checks are 
121     done to ensure that the spinbutton type has the _label.
122
123 ** Undocumented.
124 'undocumented' means that the element/feature was not mentioned in the
125 official documentation of the format available in the -
126 xscreensaver-4.22/hacks/config/README.
127 -->
128 <xs:schema
129   xmlns:xs="http://www.w3.org/2001/XMLSchema"
130   elementFormDefault="qualified">
131
132   <!-- The root element of any XScreenSaver configuration file. -->
133   <xs:element name="screensaver">
134     <xs:complexType>
135       <xs:sequence>
136         <!-- Every XScreenSaver hack has exactly one of either
137         command or fullcommand, but my understanding is that
138         demo-Gtk-conf.c chains them together.
139         This specifies a maximum numner of commands. -->
140         <xs:choice minOccurs="0" maxOccurs="10">
141           <xs:element ref="command"/>
142           <xs:element ref="fullcommand"/>
143         </xs:choice>
144         <!-- A maximum number of components/groups is specified.  -->
145         <xs:choice minOccurs="0" maxOccurs="30">
146           <xs:element ref="boolean"/>
147           <xs:element ref="number"/>
148           <xs:element ref="select"/>
149           <xs:element ref="string"/>
150           <xs:element ref="file"/>
151           <xs:element ref="hgroup"/>
152           <xs:element ref="vgroup"/>
153         </xs:choice>
154         <xs:element ref="_description"/>
155       </xs:sequence>
156       <xs:attribute name="name" type="xs:token" use="required"/>
157       <xs:attribute name="_label" type="xs:token" use="required"/>
158     </xs:complexType>
159   </xs:element>
160
161   <!-- Added to the command line when invoked.  -->
162   <xs:element name="command">
163     <xs:complexType>
164       <xs:attribute name="arg" type="argumentType"/>
165     </xs:complexType>
166   </xs:element>
167
168   <!-- Unimplemented in SaverBeans as of API 0.2.
169   Used only by cosmos.xml.  Undocumented. -->
170   <xs:element name="fullcommand">
171     <xs:complexType>
172       <xs:attribute name="arg" type="argumentType"/>
173     </xs:complexType>
174   </xs:element>
175
176   <!-- Checkbox -->
177   <xs:element name="boolean">
178     <xs:complexType>
179       <xs:attribute name="id" type="idType"/>
180       <xs:attribute name="_label" type="xs:token" use="required"/>
181       <!-- Exactly one of either arg-set or arg-unset is required -->
182       <xs:attribute name="arg-set" type="argumentType"/>
183       <xs:attribute name="arg-unset" type="argumentType"/>
184     </xs:complexType>
185   </xs:element>
186
187   <!-- Slider and Spinbutton -->
188   <xs:element name="number">
189     <xs:complexType>
190       <xs:attribute name="id" type="idType"/>
191       <xs:attribute name="type" use="required">
192         <xs:simpleType>
193           <xs:restriction base="xs:NMTOKEN">
194             <xs:enumeration value="slider"/>
195             <xs:enumeration value="spinbutton"/>
196           </xs:restriction>
197         </xs:simpleType>
198       </xs:attribute>
199       <!-- Listed as 'required' in the documentation, though XScreenSaver is
200       tolerant to it being left out.  A number of hacks deliberately exclude it
201       for formatting purposes, and put the _label as prefix to _low-label -->
202       <xs:attribute name="_label" type="xs:token" />
203       <!-- _low/_high-label not defined for type spinbutton,
204       but required for slider -->
205       <xs:attribute name="_low-label" type="xs:token"/>
206       <xs:attribute name="_high-label" type="xs:token"/>
207       <xs:attribute name="arg" type="substitutionArgumentType" use="required"/>
208       <xs:attribute name="low" type="xs:decimal" use="required"/>
209       <xs:attribute name="high" type="xs:decimal" use="required"/>
210       <!-- Must logically fall between low and high, but not checked. -->
211       <xs:attribute name="default" type="xs:decimal" use="required"/>
212       <xs:attribute name="convert">
213         <xs:simpleType>
214           <xs:restriction base="xs:NMTOKEN">
215             <xs:enumeration value="invert"/>
216           </xs:restriction>
217         </xs:simpleType>
218       </xs:attribute>
219     </xs:complexType>
220   </xs:element>
221
222   <!-- Drop-down list -->
223   <xs:element name="select">
224     <xs:complexType>
225       <xs:sequence>
226         <!-- A maximum number of options is specified, as a longer
227         drop down becomes kludgy and difficult to use.  -->
228         <xs:element ref="option" maxOccurs="200"/>
229       </xs:sequence>
230       <xs:attribute name="id" type="idType"/>
231     </xs:complexType>
232   </xs:element>
233
234   <!-- List item -->
235   <xs:element name="option">
236     <xs:complexType>
237       <xs:attribute name="id" type="idType"/>
238       <xs:attribute name="_label" type="xs:token" use="required"/>
239       <xs:attribute name="arg-set" type="argumentType"/>
240     </xs:complexType>
241   </xs:element>
242
243   <!-- String or textual input -->
244   <xs:element name="string">
245     <xs:complexType>
246       <xs:attribute name="id" type="idType"/>
247       <xs:attribute name="_label" type="xs:token" use="required"/>
248       <xs:attribute name="arg" type="substitutionArgumentType" use="required"/>
249     </xs:complexType>
250   </xs:element>
251
252   <!-- File browser. -->
253   <xs:element name="file">
254     <xs:complexType>
255       <xs:attribute name="id" type="idType"/>
256       <xs:attribute name="_label" type="xs:token" use="required"/>
257       <xs:attribute name="arg" type="substitutionArgumentType" use="required"/>
258     </xs:complexType>
259   </xs:element>
260
261     <!-- Free Text.  The description of the Screen Saver. -->
262     <xs:element name="_description">
263       <!-- The _description must contain text only, with no HTML formatting.
264
265       Character entities are also valid, which suggests that..
266         http://www.w3.org/TR/REC-html40/sgml/entities.html
267       ..are valid entities, though this, ..
268         http://www.w3.org/TR/1998/REC-html40-19980424/sgml/entities.html#h-24.4.1
269       ..may represent a safer sub-set.
270
271       The main entities you might require (none of which are allowed
272       in textual content in an XML file) are..
273        &lt; (= <)
274        &gt; (= >)
275        &amp; (= &)
276
277       XScreenSaver itself will probably* turn any URL enclosed in
278       &lt; / &gt; into a clickable link.
279
280       Conversion to an URL is unimplemented in SaverBeans as of API 0.2.
281
282       It might be possible to implement this in SaverBeans with the help of
283       BrowserLauncher, though that would require about 20Kb (AFAIR) of extra
284       classes in the core API distributable.
285
286       * This is based solely on the use of the delimiters in many of the
287       XScreenSaver hacks, but has not been investigated in any depth.
288       -->
289       <xs:simpleType>
290         <xs:restriction base="xs:string">
291           <xs:maxLength value="3000"/>
292         </xs:restriction>
293       </xs:simpleType>
294     </xs:element>
295
296     <!-- Horizontal grouping element, a row of components or groups.
297     Unimplemented in SaverBeans as of API 0.2,
298     components inside groups do not appear.  -->
299     <xs:element name="hgroup">
300       <xs:complexType>
301         <!-- A maximum number of components/groups per row is specified. -->
302         <xs:choice minOccurs="0" maxOccurs="4">
303           <xs:element ref="boolean"/>
304           <xs:element ref="number"/>
305           <xs:element ref="select"/>
306           <xs:element ref="string"/>
307           <xs:element ref="file"/>
308           <xs:element ref="vgroup"/>
309         </xs:choice>
310       </xs:complexType>
311     </xs:element>
312
313     <!-- Vertical grouping element, a column of components or groups.
314     Since the components are normally arranged in a column,
315     this is only of use within an hgroup.
316     Unimplemented in SaverBeans as of API 0.2,
317     components inside groups do not appear.  -->
318     <xs:element name="vgroup">
319       <xs:complexType>
320         <!-- A maximum number of components/groups per column is specified. -->
321         <xs:choice minOccurs="0" maxOccurs="10">
322           <xs:element ref="boolean"/>
323           <xs:element ref="number"/>
324           <xs:element ref="select"/>
325           <xs:element ref="string"/>
326           <xs:element ref="file"/>
327           <xs:element ref="hgroup"/>
328         </xs:choice>
329       </xs:complexType>
330     </xs:element>
331
332     <!-- Checks that the command arguments (non substitution arg, as
333     well as arg-set/arg-unset) are of a logical (and restricted) form.
334     This determines that the type must start with '-', and contain at
335     least one letter, number or the other characters shown in the RegEx.
336     It is stricter than the XScreenSaver documentation suggests. -->
337     <xs:simpleType name="argumentType">
338       <xs:restriction base="xs:token">
339         <xs:minLength value="2"/>
340         <xs:pattern value="-([a-zA-Z0-9 .,;:+_$#%?/\\\-])*"/>
341       </xs:restriction>
342     </xs:simpleType>
343
344     <!-- Checks that the command arguments that use substitution are of
345     a logical (and quite restricted) form.  This determines that the
346     type must start with '-', contain at least one letter, number
347     or the other characters shown in the RegEx.
348     It is stricter than the XScreenSaver documentation suggests. -->
349     <xs:simpleType name="substitutionArgumentType">
350       <xs:restriction base="xs:token">
351         <xs:minLength value="4"/>
352         <xs:pattern value="-([a-zA-Z0-9.,;:+_$#%?/\\\-])* %"/>
353       </xs:restriction>
354     </xs:simpleType>
355
356     <!-- idType is used to validate the ID's
357     Many ID's do not parse as type xs:ID, so this type was created to
358     allow easy maintenance between the strict and loose versions of the schema.
359     The base type should be
360      - xs:ID in the strict schema, and
361      - xs:token in the loose schema.
362     Note that the base type of xs:ID overrides the minLength value of '0'
363     -->
364     <xs:simpleType name="idType">
365       <!-- strict -->
366       <xs:restriction base="xs:ID">
367       <!-- loose -->
368       <!--
369       <xs:restriction base="xs:token">
370       -->
371         <xs:minLength value="0"/>
372       </xs:restriction>
373     </xs:simpleType>
374
375 </xs:schema>