Version numbering and negotiation

Version number form

The Web Map Service (WMS) defines a protocol version number. The version number applies to the XML schema and the request encodings defined in this International Standard. The version number contains three non-negative integers, separated by decimal points, in the form "x.y.z". The numbers "y" and "z" shall not exceed 99.

Version number changes

The protocol version number shall be changed with each revision of this International Standard. The number shall increase monotonically and shall comprise no more than three integers separated by decimal points, with the first integer being the most significant. There may be gaps in the numerical sequence. Some numbers may denote draft versions. Servers and their clients need not support all defined versions, but shall obey the negotiation rules below.

Appearance in requests and in service metadata

The version number shall appear in at least two places: in the service metadata and in the parameter list of client requests to a server. The version number used in a client’s request of a particular server shall be equal to a version number which that server has declared it supports (except during negotiation, as described below). A server may support several versions, whose values clients may discover according to the negotiation rules.

Version number negotiation

A WMS client may negotiate with a server to determine a mutually agreeable protocol version. Negotiation is performed using the GetCapabilities operation according to the following rules.

All service metadata shall include a protocol version number and shall comply with the XML DTD or Schema defined for that version. In response to a GetCapabilities request (for which the VERSION parameter is optional) that does not specify a version number, the server shall respond with the highest version it supports. In response to a GetCapabilities request containing a version number that the server implements, the server shall send that version. If the server does not support the requested version, the server shall respond with output that conforms to a version it does support, as determined by the following rules:

• If a version unknown to the server and higher than the lowest supported version is requested, the server shall send the highest version it supports that is less than the requested version.
• If a version lower than any of those known to the server is requested, then the server shall send the lowest version it supports.
• If the client does not support the version sent by the server, it may either cease communicating with the server or send a new request with a different version number that the client does support.

The process may be repeated until a mutually understood version is reached, or until the client determines that it will not or cannot communicate with that particular server.

EXAMPLE 1, Server understands versions 1, 2, 4, 5 and 8. Client understands versions 1, 3, 4, 6, and 7. Client requests version 7. Server responds with version 5. Client requests version 4. Server responds with version 4, which the client understands, and the negotiation ends successfully.

EXAMPLE 2, Server understands versions 4, 5 and 8. Client understands version 3. Client requests version 3. Server responds with version 4. Client does not understand that version or any higher version, so negotiation fails and client ceases communication with that server.

The VERSION parameter is mandatory in requests other than GetCapabilities.