Web Map Service Implementation Specification

The published specification version number contains three positive integers, separated by decimal points, in the form "x.y.z". The numbers "y" and "z" will never exceed 99. Each OWS specification is numbered independently.

A particular specification's version number shall be changed with each revision. 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 experimental or interim versions. Service instances and their clients need not support all defined versions, but shall obey the negotiation rules below.

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

An OWS Client may negotiate with a Service Instance to determine a mutually agreeable specification version. Negotiation is performed using the GetCapabilities operation (described in Section 7.1, GetCapabilities) according to the following rules.

All Capabilities XML shall include a protocol version number. In response to a GetCapabilities request containing a version number, an OGC Web Service shall either respond with output that conforms to that version of the specification, or negotiate a mutually agreeable version if the requested version is not implemented on the server. If no version number is specified in the request, the server shall respond with the highest version it understands and label the response accordingly.

Version number negotiation occurs as follows:

1) If the server implements the requested version number, the server shall send that version.

2a) If a version unknown to the server is requested, the server shall send the highest version less than the requested version.

2b) If the client request is for a version lower than any of those known to the server, then the server shall send the lowest version it knows.

3a) If the client does not understand the new version number sent by the server, it may either cease communicating with the server or send a new request with a new version number that the client does understand but which is less than that sent by the server (if the server had responded with a lower version).

3b) If the server had responded with a higher version (because the request was for a version lower than any known to the server), and the client does not understand the proposed higher version, then the client may send a new request with a version number higher than that sent by the server.

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

The URL specification [IETF RFC 2396] reserves particular characters as significant and requires that these be escaped when they might conflict with their defined usage. The present WMS specification explicitly reserves several of these characters for use in the query portion of HTTP GET requests. When the characters "?", "&", "=", "/", ":" and "," appear in one of the roles defined in Table 1, they are to appear literally in the URL. When such characters appear elsewhere (for example, in the value of a parameter), they are to be encoded as defined in [IETF RFC 2396].

An Online Resource URL intended for HTTP GET requests is in fact only a URL prefix to which additional parameters are appended in order to construct a valid Operation request. A URL prefix is defined as an opaque string including the protocol, hostname, optional port number, path, a question mark '?', and, optionally, one or more server-specific parameters ending in an ampersand '&'. The prefix uniquely identifies the particular service instance. A client appends the necessary request parameters as name/value pairs in the form "name=value&". The resulting URL shall be valid according to the HTTP Common Gateway Interface standard [CGI], which mandates the presence of '?' before the sequence of query parameters and the '&' between each parameter.

The URL prefix shall end in either a '?' (in the absence of additional server-specific parameters) or a '&'. In practice, however, Clients should be prepared to add a necessary trailing '?' or '&' before appending the Operation parameters defined in this specification in order to construct a valid request URL.

Table 2 summarizes the components of an operation request URL.

An Online Resource URL intended for HTTP POST requests is a complete and valid URL to which Clients transmit request parameters in the body of the POST request. A WMS shall not require additional parameters to be appended to the URL in order to construct a valid target for the Operation request.

Operation requests using HTTP POST have not yet been defined for the basic Web Map Service.

Parameter names shall not be case sensitive, but parameter values shall be case sensitive. In this document, parameter names are typically shown in uppercase for typographical clarity, not as a requirement.

Parameters in a request may be specified in any order.

An OGC Web Service shall be prepared to encounter parameters that are not part of this specification. In terms of producing results per this specification, an OGC Web Service shall not require such parameters.

Parameters consisting of lists (for example, the LAYERS and STYLES in WMS GetMap) shall use the comma (",") as the separator between items in the list. Additional white space shall not be used to delimit list items. If a parameter value includes a space or comma, it shall be escaped using the URL encoding rules [IETF RFC 2396].

Individual entries in a list may be empty, as represented by two successive commas (",,").

The VERSION parameter specifies the protocol version number. The format of the version number, and version negotiation, are described in Section 6.1, Version Numbering and Negotiation.

The REQUEST parameter indicates which service operation is being invoked. The value shall be the name of one of the operations offered by the OGC Web Service Instance.

The FORMAT parameter specifies the output format of the response to an operation.

An OGC Web Service may offer only a subset of the formats known for that type of operation, but the server shall advertise in its Capabilities XML those formats it does support and shall accept requests for any format it advertises. A Service Instance may optionally offer a new format not previously offered by other instances, with the recognition that clients are not required to accept or process an unknown format. If a request contains a Format not offered by a particular server, the server shall throw a Service Exception (with code "InvalidFormat").

A Client may accept only a subset of the formats known for that type of operation. If a Client and Service do not support any mutually agreeable formats, the Client may, at its discretion, cease communicating with that service, or search for an intermediary service provider that performs format conversion, or allow the user to choose other disposition methods (e.g., saving to local storage or passing to helper application).

Formats are expressed in both Capabilities XML and in operation requests using MIME types. Each Operation has a distinct list of supported formats. Some formats may be offered by several operations, and are then duplicated as needed in each list.

Generally, OGC Web Service MIME types are chosen from among those in common use on the Internet [9]. However, additional OGC-specific types have been adopted to distinguish among different types of XML-formatted content (the generic XML MIME types being text/xml and application/xml), as listed in Table 3.

The EXCEPTIONS parameter states the format in which to report errors. See Section 6.7, Service Exceptions below.

The Spatial Reference System (SRS) is a text parameter that names a horizontal coordinate reference system code. The name includes a namespace prefix, a colon, a numeric identifier, and possibly a comma followed by additional parameters. This specification defines two namespaces, EPSG and AUTO, which are discussed below.

OGC Web Services are not required to support all possible SRSes, but shall advertise in their Capabilities XML those projections which they do offer and shall accept requests for all advertised projections. If a request contains an SRS not offered by a particular server, the server shall throw a Service Exception (code = "InvalidSRS").

Clients are not required to support all possible SRSes. If a Client and Service do not support any mutually agreeable SRS, the Client may, at its discretion, cease communicating with that service, or search for an intermediary service provider that performs coordinate transformations, or allow the user to choose other disposition methods.

AUTO:auto_proj_id,epsg_units_id,lon0,lat0

The Bounding Box (BBOX) is a set of four comma-separated decimal, scientific notation, or integer values (if integers are provided where floating point is needed, the decimal point is assumed at the end of the number). These values specify the minimum X, minimum Y, maximum X, and maximum Y ranges, in that order, expressed in units of the SRS of the request, such that a rectangular area is defined in those units. When the SRS is a Platte Carre projection of longitude and latitude coordinates, X refers to the longitudinal axis and Y to the latitudinal axis. The four bounding box values indicate the outside edges of a rectangle, as in Figure 5: minimum X is the left edge, maximum X the right, minimum Y the bottom, and maximum Y the top. The relation of the Bounding Box to the image pixel matrix is shown in the figure: the bounding box goes around the "outside" of the pixels of the image rather than through the centers of the border pixels. In this context, individual pixels have an area.

Figure 5. Bounding Box representation

A Bounding Box should not have zero area.

If a request contains an invalid Bounding Box (e.g., one whose minimum X is greater than or equal to the maximum X, or whose minimum Y is greater than or equal to the maximum Y) the server shall throw an exception.

If a request contains a Bounding Box whose area does not overlap at all with the BoundingBox advertised in the Capabilities XML for the requested geodata object, the server should return empty content (e.g., a blank map, empty coverage file, null feature set) for that element. Any elements that are partly or entirely contained in the Bounding Box should be returned in the appropriate format.

If the Bounding Box values are not defined for the given SRS (e.g., latitudes greater than 90 degrees in EPSG:4326), the server should return empty content for areas outside the valid range of the SRS.

In the particular case of longitude, the following behavior may apply regarding the anti-meridian at 180 degrees of longitude. There is a legitimate desire for maps that span the

anti-meridian (for example, a map centered on the Pacific Ocean). However, a strict interpretation of the previous paragraph suggests that areas beyond 180 degrees should be shown as empty content; this corresponds to the STRICT constraint below. A server may choose to relax this behavior by instead applying the LOOSE constraint below. If minx is the west-most longitude in degrees and maxx is the east-most, then:

STRICT longitude constraint (default):

-180 <= minx < maxx <= 180

LOOSE longitude constraint (optional):

-180 <= minx < maxx < minx + 360 < 540

Some geospatial information may be available at multiple times (for example, an hourly weather map). An OGC Web Service may announce available times in its Capabilities XML, and some operations include a parameter for requesting a particular time. The format of a time string is specified in Annex C, Handling Multi-Dimensional Data. Depending on the context, time values may appear as a single value, a list of values, or an interval, as specified in Annex D, Conformance Tests. When providing temporal information, Servers should declare a default value in Capabilities XML unless there is compelling reason to behave otherwise, and Servers shall respond with the default value if one has been declared and the Client request does not include a value.

Some geospatial information may be available at multiple elevations (for example, ozone concentrations at different heights in the atmosphere). An OWS may announce available elevations in its Capabilities XML, and some operations include a parameter for requesting a particular elevation. A single elevation value is an integer or real number whose units are declared by naming an EPSG datum. Depending on the context, elevation values may appear as a single value, a list of values, or an interval, as specified in Annex D, Conformance Tests. When providing elevation information, Servers should declare a default value in Capabilities XML unless there is compelling reason to behave otherwise, and Servers shall respond with the default value if one has been declared and the Client request does not include a value.

Some geospatial information may be available at other dimensions (for example, satellite images in different wavelength bands). The dimensions other than the four space-time dimensions are referred to as "sample dimensions". An OWS may announce available sample dimensions in its Capabilities XML, and some operations include a mechanism for including dimensional parameters. Each sample dimension has a Name and one or more valid values. The declaration and use of sample dimensions are specified in Annex D, Conformance Tests.

Most service requests require additional parameters (beyond REQUEST) to unambiguously state what result to construct. Each OGC Web Service specification defines the required and optional parameters for its operation(s).

Finally, the requests allow for optional vendor-specific parameters (VSPs) that will enhance the results of a request. Typically, these are used for private testing of non-standard functionality prior to possible standardization. A generic client is not required or expected to make use of these VSPs.

An OGC Web Service shall produce a valid result even if VSPs are missing or malformed (i.e., the Service shall supply a default value), or if VSPs are supplied that are not known to the Service (i.e., the Service shall ignore unknown request parameters).

An OGC Web Service may choose not to advertise some or all of its VSPs. If VSPs are included in the Capabilities XML, then they shall be defined within an internal DTD section of that XML document. (An internal DTD comprises declarations enclosed in square brackets [] within the <DOCTYPE> element of the XML [see ref. 9].) In the absence of such parameters, the internal DTD is absent.

Clients may read the internal DTD and formulate requests using any VSPs advertised therein.

Vendors should choose vendor-specific parameter names with care to avoid clashes with standard parameters.

The purpose of the GetCapabilities operation is described in the Basic Service Elements section, above. In the particular case of a Web Map Service, the response of a GetCapabilities request is general information about the service itself and specific information about the available maps.

The general form of a GetCapabilities request is defined in the Basic Service Elements section. When making this request of a WMS, which may offer other OGC Web Services as well, it is necessary to indicate that the client seeks information about the WMS in particular. Thus, the SERVICE parameter of the request shall have the value "WMS" as shown in Table 4 below.

The Basic Service Elements section specifies general rules about the GetCapabilities response.

In the particular case of a Web Map Service complying with this version of the standard, the Extensible Markup Language (XML) [XML 1.0] response shall be valid according to the XML Document Type Definition (DTD) in Annex A.1, WMS Capabilities DTD of this document. The DTD specifies the required and optional content of the response and how the content is formatted.

A server's Capabilities XML may reference an exact copy of the DTD in Annex A.1, WMS Capabilities DTD instead of the master copy at the URL stated in the Annex. The DTD copy shall be located at a fully-qualified and accessible URL to permit XML validating software to retrieve it.

A server may comply with other published or experimental versions, in which case it shall support Version Negotiation as described in the Basic Service Elements section. A DTD for version 1.0.0 was published as an annex to that version of the WMS specification. Other DTDs are archived at <http://www.digitalearth.gov/wmt/xml/>.