1 <?xml version="1.0" encoding="UTF-8"?>
2 <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
6 XSDL schema for validation of mingw-get package specifications.
8 Written by Keith Marshall <keithmarshall@users.sourceforge.net>
9 Copyright (C) 2013, 2017, MinGW.org Project
12 This file is part of the mingw-dist catalogue validation suite.
14 This is free software. Permission is granted to copy, modify and
15 redistribute this software, under the provisions of the GNU General
16 Public License, Version 3, (or, at your option, any later version),
17 as published by the Free Software Foundation; see the file COPYING
18 for licensing details.
20 Note, in particular, that this software is provided "as is", in the
21 hope that it may prove useful, but WITHOUT WARRANTY OF ANY KIND; not
22 even an implied WARRANTY OF MERCHANTABILITY, nor of FITNESS FOR ANY
23 PARTICULAR PURPOSE. Under no circumstances will the author, or the
24 MinGW Project, accept liability for any damages, however caused,
25 arising from the use of this software.
28 Note to maintainers, (because this may seem counter intuitive, and
29 thus may be eminently forgettable): whilst the structure of any XML
30 document demands that attributes be specified in the opening tag of
31 their associated element, and thus they PRECEDE the element content,
32 XSDL requires that they be declared AFTER the corresponding content
33 model; please ensure that their declarations are correctly placed
34 within this XSDL schema.
37 <xs:element name="software-distribution" type="specification-document" />
39 The package specification document root is always an XML element
40 named "software-distribution", which must conform to the following
43 <xs:complexType name="specification-document">
46 The entire specification comprises a sequence of at most three
47 optionally repeating section types; unless it is omitted...
49 <xs:element name="package-group-hierarchy" minOccurs="0">
51 ...this must appear as the first section; only one instance
55 <xs:sequence maxOccurs="unbounded">
57 Within the package group hierarchy, at least one package
58 group must be specified. Additional group specifications
59 may be added, without limit; all must conform to the type
60 definition, as specified below.
62 <xs:element name="package-group" type="package-group-definition" />
67 When present, a package group hierarchy specification is typically
68 followed by one or more instances of...
70 <xs:element name="package-list" minOccurs="0" maxOccurs="unbounded">
72 ...this; it is optional, but when present, all instances must
73 follow the package group hierarchy specification, (if any), and
74 must precede any "package collection" specification.
78 This is an "attribute only" element. The "catalogue" attribute
79 must be specified; it represents the name of a further XML file
80 to be included within the specification document, omitting both
81 any directory path, and the ".xml" file name suffix.
83 <xs:attribute name="catalogue" type="xs:string" use="required" />
85 The specification author typically does NOT specify the "issue"
86 attribute; it is inserted automatically by the "mingw-dist" build
87 system, as an indicator to mingw-get when the catalogue named by
88 the "catalogue" attribute should be updated.
90 <xs:attribute name="issue" type="serial-number" />
94 Typically specified in isolation, (i.e. entirely separated from any
95 package group hierarchy or package list specification), the final
96 section which may appear in the specification document is...
98 <xs:element name="package-collection" minOccurs="0" maxOccurs="unbounded">
100 ...this. Although any number of instances may appear in a single
101 specification document, most commonly, each document will specify
102 only one package collection, which itself comprises...
106 ...a group of child elements, as defined below, specifying the
107 set of packages which are included in this collection.
109 <xs:group ref="package-collection-specification" />
111 All of the individual packages in any one collection MUST
112 be assigned to a common installation "subsystem", which is
113 identified by this required attribute.
115 <xs:attribute name="subsystem" type="xs:string" use="required" />
120 The specification document also supports three attributes: the "project"
121 and "host" attributes are optional; they are provided primarily as an aid
122 to documenting the origin of the specified package collection, but they
123 are not actually used by mingw-get.
125 <xs:attribute name="project" type="xs:string" default="MinGW" />
126 <xs:attribute name="home" type="xs:anyURI" default="http://www.mingw.org" />
128 On the other hand, the "issue" attribute is required; it takes a string
129 value, conforming to the type definition below; in the source context of
130 a mingw-dist catalogue build, it should be specified using the template
131 form for the value; other contexts should use the YYYYMMDDNN form.
133 <xs:attribute name="issue" type="serial-number" use="required" />
136 <xs:simpleType name="serial-number">
138 This specialization of the XSDL string type is to be used to specify the
139 value for the "issue" attribute, which is required in every specification
140 document. It may be either be the explicit "@YYYYMMDDNN@" substitution
141 template, as used in mingw-dist source documents, or any ten character
142 alpha-numeric pattern derived from this template.
144 <xs:restriction base="xs:string">
145 <xs:pattern value="(@YYYYMMDDNN@)|([0-9A-Z]{10})" />
149 <xs:complexType name="package-group-definition">
151 Defines the structure of the elements used to specify package groups,
152 within the package group hierarchy section of the specification document.
153 Elements of this type may repeat any number of times, both within this
154 context, and recursively nested within other package groups.
156 <xs:sequence minOccurs="0" maxOccurs="unbounded">
157 <xs:element name="package-group" type="package-group-definition" />
160 Every package group must be named; mingw-get uses the value of the "name"
161 attribute as a label, to create a tree-view display representation of the
162 package group hierarchy, in the left hand pane of the GUI client window.
164 <xs:attribute name="name" type="xs:string" use="required" />
166 The optional "expand" attribute provides a mechanism for specifying those
167 levels of a nested package group hierarchy which are to be shown expanded,
168 in the initial rendition of the tree-view display.
170 <xs:attribute name="expand" type="xs:boolean" />
173 <xs:group name="package-group-association-and-description">
175 Provides the mechanism for defining package to package group associations,
176 allowing multiple associations to be specified, and intermingled with any
177 number of package description elements, at the beginning of any individual
178 package specification.
181 <xs:choice minOccurs="0" maxOccurs="unbounded">
182 <xs:element name="affiliate">
184 Defines a single package to package group association, in terms of
185 a single attribute only specification element...
188 <xs:attribute name="group" type="xs:string" />
192 ...whilst this allows "description" blocks to be interspersed among
193 repeating "affiliate" specifications.
195 <xs:element name="description" type="package-description" />
200 <xs:complexType name="package-description">
202 Defines the structure of a "description" block as a container for a
203 sequence of one or more "paragraph" blocks...
206 <xs:element name="paragraph" maxOccurs="unbounded" />
209 ...optionally qualified by "lang" and/or "title" attributes.
211 <xs:attribute name="lang" type="xs:string" default="en" />
212 <xs:attribute name="title" type="xs:string" />
215 <xs:group name="package-collection-specification">
218 Defines the sequence of XML elements which are required to properly
219 specify any package group collection.
221 <xs:element name="download-host">
224 The first is always a specification for the URL whence all packages
225 in the collection may be downloaded; it is declared as a string type
226 because it is specified in a template format, which may violate the
227 constraints of the XSDL anyURI type, e.g.:
229 <download-host uri="http://host.domain.com/packages/%F" />
231 where "%F" is substituted, at download time, by the actual name of
232 the archive file wich is to be downloaded.
234 Note: only one template may be specified for any package collection;
235 thus all packages in any collection MUST be served from one common
238 <xs:attribute name="uri" type="xs:string" use="required" />
242 The download host specification may be followed by an optional sequence
243 of package group association specifications. These must conform to the
244 format defined above, where it may be seen that they comprise any number
245 of "affiliate" and "description" elements, in arbitrary order. If any
246 of these are specified here, they apply to every package subsequently
247 included within the collection.
249 <xs:group ref="package-group-association-and-description" />
250 <xs:choice maxOccurs="unbounded">
252 The principal content of any package collection comprises an arbitrary
253 number of "package" specification elements.
255 <xs:element name="package">
259 Each package specification begins with an optional description,
260 and an arbitrary set of package group association declarations.
262 <xs:group ref="package-group-association-and-description" />
264 This must be followed by an arbitray sequence of one or more
265 "source", "licence", "component", or "action" specifications.
267 <xs:choice maxOccurs="unbounded">
268 <xs:group ref="source-or-licence-archive-reference" />
269 <xs:element name="component" type="component-specification" />
270 <xs:element name="action" type="action-script" />
274 Each package MUST be named; it may also be assigned to the class
275 of "virtual" packages, so identifying it as a meta-package, may
276 be identified by a list of aliases, and may also be marked as
277 intended to be hidden from the user interface. (Note that, if
278 both class="virtual" and visibility="hidden" are specified, an
279 intent is implied to both conceal the package from the user, and
280 to suppress any record of its installation; this feature, which
281 is intended to facilitate forced dependency resolution, is not
282 currently supported by mingw-get).
284 <xs:attribute name="name" type="xs:string" use="required" />
285 <xs:attribute name="visibility" type="visibility-attribute" />
286 <xs:attribute name="class" type="package-class" />
287 <xs:attribute name="alias" type="xs:string" />
291 Actions may also be specified within the package-collection scope, in
292 which case they apply to all packages, and component packages, which
293 are declared within the collection.
295 <xs:element name="action" type="action-script" />
300 <xs:simpleType name="package-class">
302 Any package may be specified as a meta-package, by assigning it a "class"
303 attribute value of "virtual"; specification of this attribute is optional,
304 but no other value is permitted.
306 <xs:restriction base="xs:string">
307 <xs:pattern value="virtual" />
311 <xs:simpleType name="visibility-attribute">
313 Any package, or package component, may be marked with a visibility of
314 "hidden", indicating that mingw-get should not show it within the user
315 interface; (if specified, this attribute MUST have a value of "hidden";
316 it should normally be omitted entirely, for any package or component
317 which is to be visible within the user interface).
319 <xs:restriction base="xs:string">
320 <xs:pattern value="hidden" />
324 <xs:complexType name="component-specification">
326 Each "package" should be subdivided into one or more "component" packages,
327 each of which may bear its own individual description and/or package group
328 associations. Each "component" package should also define a sequence of
329 "release" specifications, optionally qualified by specifications of any
330 dependencies which are common to all releases of the "component" package,
331 and any actions which should be performed when installing or removing any
332 release of the "component" package.
334 <xs:choice maxOccurs="unbounded">
335 <xs:group ref="package-group-association-and-description" />
336 <xs:element name="release" type="release-specification" />
337 <xs:element name="requires" type="dependency-specification" />
338 <xs:element name="action" type="action-script" />
341 Every "component" package MUST be classified; however, the choice of
342 "class" name is unrestricted. Additionally, any component package may
343 be marked with the visibility="hidden" attribute, (although this will
344 be ignored if the component delivers installable content).
346 <xs:attribute name="class" type="xs:string" use="required" />
347 <xs:attribute name="visibility" type="visibility-attribute" />
350 <xs:complexType name="release-specification">
352 Each individual release of any component package must be specified by its
353 own "release" specification element; this may be qualified by a "download"
354 specification, (for cases where the actual archive file name differs from
355 the canonical "tarname", or is "none" in the case of a meta-release, for
356 which the container "package" element cannot be declared as "virtual");
357 each "release" may also specify its own set of dependencies, and/or its
358 own specific "source" and/or "licence" archive associations.
360 <xs:choice minOccurs="0" maxOccurs="unbounded">
361 <xs:element name="download" type="tarname-reference" />
362 <xs:element name="requires" type="dependency-specification" />
363 <xs:group ref="source-or-licence-archive-reference" />
366 Every "release" MUST be identified by a canonical "tarname" attribute.
368 <xs:attribute ref="tarname" use="required" />
371 <xs:complexType name="action-script" mixed="true">
373 Any action is specified as Lua script, appearing as textual content within
374 the body of the "action" element; it also requires a specification for its
375 "class" attribute, to identify the context in which it is to be executed.
377 <xs:attribute name="class" type="action-class" use="required" />
380 <xs:simpleType name="action-class">
382 The context in which any specified action is to be executed must be one of
383 "pre-install", "post-install", "pre-remove", or "post-remove".
385 <xs:restriction base="xs:string">
386 <xs:pattern value="(pre|post)-(install|remove)" />
390 <xs:group name="source-or-licence-archive-reference">
392 "source" and "licence" elements are simple "attribute only" elements, each
393 of which requires only a "tarname" attribute; note that the spelling which
394 is required for the "licence" element uses the noun form, as prescribed by
395 the Oxford Dictionary of World English; use of the US English form, where
396 noun and verb are both spelled as "license" is NOT supported.
399 <xs:element name="source" type="tarname-reference" />
400 <xs:element name="licence" type="tarname-reference" />
404 <xs:complexType name="tarname-reference">
406 When any element accepts a "tarname" attribute, then specification of that
407 attribute is mandatory.
409 <xs:attribute ref="tarname" use="required" />
412 The "tarname" attribute is a simple string type; it should match a specific
413 pattern, but for the time being, we do not attempt to verify it.
415 <xs:attribute name="tarname" type="xs:string" />
417 <xs:complexType name="dependency-specification">
419 Any "requires" specification MUST include one or more of the following
420 attributes, to declare an equality or a range dependency. It may be noted
421 that, while a range specification requires two such attributes, there will
422 be some combinations which will be mutually inconsistent; unfortunately,
423 XSDL provides no mechanism to filter out such combinations.
425 <xs:attribute name="lt" type="xs:string" />
426 <xs:attribute name="le" type="xs:string" />
427 <xs:attribute name="eq" type="xs:string" />
428 <xs:attribute name="ge" type="xs:string" />
429 <xs:attribute name="gt" type="xs:string" />
434 <!-- vim: set nocompatible fileformat=unix: -->
435 <!-- vim: set smartindent shiftwidth=2 expandtab textwidth=80 wrap: -->
436 <!-- $RCSfile$: end of file -->