1
<?xml version="1.0" encoding="UTF-8"?>
2
<?xml-stylesheet type="text/xsl" href="../xslt/schema.xslt"?>
4
<!-- (C) 2011 OpenStack LLC., All Rights Reserved -->
6
<xs:schema elementFormDefault="qualified" attributeFormDefault="unqualified"
7
targetNamespace="http://docs.openstack.org/common/api/v1.0"
8
xmlns:vers="http://docs.openstack.org/common/api/v1.0"
9
xmlns:vc="http://www.w3.org/2007/XMLSchema-versioning"
10
xmlns:xsdxt="http://docs.rackspacecloud.com/xsd-ext/v1.0"
11
xmlns:html="http://www.w3.org/1999/xhtml"
12
xmlns:atom="http://www.w3.org/2005/Atom"
13
xmlns:xs="http://www.w3.org/2001/XMLSchema">
18
xmlns="http://www.w3.org/1999/xhtml">
19
<xsdxt:title>Version Types</xsdxt:title>
20
<xsdxt:link rel="index" href="api-common.xsd" />
24
xmlns="http://www.w3.org/1999/xhtml">
26
This schema file defines all types related to versioning.
31
<!-- Import ATOM specific schema definitions -->
32
<xs:import namespace="http://www.w3.org/2005/Atom" schemaLocation="atom/atom.xsd" />
34
<!-- Multiple choices -->
35
<xs:element name="choices" type="vers:VersionChoiceList">
39
xmlns="http://www.w3.org/1999/xhtml">
41
This element is returned when the version of the
42
resource cannot be determined. The element
43
provides a list of choices for the resource.
49
<xsdxt:code type="application/xml" href="../samples/choices.xml" />
52
<xsdxt:code type="application/json" href="../samples/choices.json" />
60
<xs:element name="versions" type="vers:VersionChoiceList">
64
xmlns="http://www.w3.org/1999/xhtml">
66
Provides a list of supported versions.
72
<xsdxt:code type="application/xml" href="../samples/versions.xml" />
75
<xsdxt:code type="application/json" href="../samples/versions.json" />
78
<xsdxt:code type="application/atom+xml" href="../samples/versions-atom.xml" />
84
<xs:element name="version" type="vers:VersionChoice" vc:minVersion="1.0" vc:maxVersion="1.1">
88
xmlns="http://www.w3.org/1999/xhtml">
90
This element provides detailed meta information
91
regarding the status of the current API version.
92
This is the XSD 1.0 compatible element definition.
98
<xs:element name="version2" type="vers:VersionChoiceRoot" vc:minVersion="1.1">
102
xmlns="http://www.w3.org/1999/xhtml">
104
This element provides detailed meta information
105
regarding the status of the current API
106
version. The description should include a pointer
107
to both a human readable and a machine processable
108
description of the API service.
114
<xsdxt:code type="application/xml" href="../samples/version.xml" />
117
<xsdxt:code type="application/json" href="../samples/version.json" />
120
<xsdxt:code type="application/atom+xml" href="../samples/version-atom.xml" />
128
<xs:simpleType name="VersionStatus">
132
The VersionStatus type describes a service's operational status.
137
<xs:restriction base="xs:string">
138
<xs:enumeration value="ALPHA">
142
This is a new service the API. Thi API
143
contract may be set, but the implementaiton
144
may not be 100% complient with it. Developers
145
are encouraged to begin testing aganst an
146
ALPHA version to provide feedback.
151
<xs:enumeration value="BETA">
155
A status of BETA indicates that this
156
version is a candidate for the next major
157
release and may feature functionality not
158
available in the current
159
version. Developers are encouraged to test
160
and begin the migration processes to a
161
BETA version. Note that a BETA version is
162
undergoing testing, it has not been
163
officially released, and my not be stable.
168
<xs:enumeration value="CURRENT">
172
The API version is stable and has been
173
tested. Developers are encouraged to
174
develop against this API version. The
175
current released version of the API will
176
always be marked as CURRENT.
181
<xs:enumeration value="DEPRECATED">
185
A status of DEPRECATED indicates that a
186
newer version of the API is
187
available. Application developers are
188
discouraged from using this version and
189
should instead develop against the latest
190
current version of the API.
198
<xs:complexType name="VersionChoiceList">
202
A version choice list outlines a collection of
203
resources at various versions.
208
<xs:element name="version" type="vers:VersionChoice" minOccurs="1" maxOccurs="unbounded" />
209
<xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded" />
211
<xs:anyAttribute namespace="##other" processContents="lax"/>
212
<!--TODO(Ziad)resolve assert issue
213
<xs:assert vc:minVersion="1.1" test="every $v in vers:version satisfies $v/atom:link[@rel='self']">
217
In version lists, every single version must
218
contain at least one self link.
225
<xs:complexType name="VersionChoiceRoot" vc:minVersion="1.1">
227
<xs:extension base="vers:VersionChoice">
228
<!--TODO(Ziad)resolve asser issue
229
<xs:assert test="atom:link[@rel='describedby']">
233
When used as a root element, a version choice
234
must contain at least one describedby link.
243
<xs:complexType name="VersionChoice">
247
A version choice contains relevant information
248
about an available service that a user can then
249
use to target a specific version of the service.
255
<xs:element name="media-types" type="vers:MediaTypeList" minOccurs="0" maxOccurs="1" />
256
<!--<xs:element vc:minVersion="1.1" ref="atom:link" minOccurs="0" maxOccurs="unbounded" />-->
257
<xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded" />
260
<xs:attribute name="id" type="xs:string" use="required">
264
The ID of a version choice represents the service version's unique
265
identifier. This ID is guaranteed to be unique only among the
266
service version choices outlined in the VersionChoiceList.
272
<xs:attribute name="status" type="vers:VersionStatus" use="required">
276
A version choice's status describes the current operational state of
277
the given service version. The operational status is captured in a
278
simple type enumeration called VersionStatus.
284
<xs:attribute name="updated" type="xs:dateTime" use="optional">
288
A version choice's updated attribute describes
289
the time when the version was updated. The
290
time should be updated anytime
291
<html:strong>anything</html:strong> in the
292
version has changed: documentation,
293
extensions, bug fixes.
298
<xs:anyAttribute namespace="##other" processContents="lax"/>
301
<xs:complexType name="MediaTypeList">
305
A MediaTypeList outlines a collection of valid media types for a given
312
<xs:element name="media-type" type="vers:MediaType" minOccurs="1" maxOccurs="unbounded" />
313
<xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded" />
315
<xs:anyAttribute namespace="##other" processContents="lax"/>
318
<xs:complexType name="MediaType">
322
A MediaType describes what content types the service version understands.
327
<xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded" />
329
<xs:attribute name="base" type="xs:string" use="optional" default="">
333
The base of a given media type describes the
334
simple MIME type that then a more complicated
335
media type can be derived from. These types
336
are basic and provide no namespace or version
337
specific data are are only provided as a
344
<xs:attribute name="type" type="xs:string" use="required">
348
The type attribute of a MediaType describes
349
the MIME specific identifier of the media type
355
<xs:anyAttribute namespace="##other" processContents="lax"/>