git.hungrycats.org Git - xscreensaver/blob - 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>