MapServer banner Home | Docs | Issue Tracker | FAQ | Download
en de es fr zh_cn it

WFS Server

Author:Jean-François Doyon
Contact:jdoyon at nrcan.gc.ca
Author:Jeff McKenna
Contact:jmckenna at gatewaygeomatics.com
Revision:$Revision$
Date:$Date$

Introduction

A WFS ( Web Feature Service ) publishes feature-level geospatial data to the web. This means that instead of returning an image, as MapServer has traditionally done, the client now obtains fine-grained information about specific geospatial features of the underlying data, at both the geometry AND attribute levels. As with other OGC specifications, this interface uses XML over HTTP as it’s delivery mechanism, and, more precisely, GML (Geography Markup Language), which is a subset of XML.

Software Requirements

In order to enable MapServer to serve WFS, it MUST be compiled against certain librairies:

  • PROJ.4: The reprojection library. Version 4.4.3 or greater is required.
  • GDAL/OGR: I/O support libraries. Version 1.1.8 or greater is required.

Please see the MapServer UNIX Compilation and Installation HowTo for detailed instructions on compiling mapserver with support for these libraries and features. For Windows users, the MS4W installer comes ready to serve both WFS and WMS.

Versions of GML Supported

MapServer can output both GML2 and GML3. By default MapServer serves GML2. You can test this by adding an ‘OUTPUTFORMAT’ parameter to a GetFeature request, such as:

For a detailed discussion on the versions supported, see bug#884.

Configuring your MapFile to Serve WFS layers

Much as in the WMS support, WFS publishing is enabled by adding certain magic METADATA keyword/value pairs to a MapFile.

MapServer will serve and include in its WFS capabilities only the layers that meet the following conditions:

  • Data source is of vector type (Shapefile, OGR, PostGIS, SDE, SDO, ...)

  • LAYER NAME must be set. Layer names must start with a letter when setting up a WFS server (layer names should not start with a digit or have spaces in them).

  • LAYER TYPE is one of: LINE, POINT, POLYGON

  • The “wfs_onlineresource” metadata:

    The wfs_onlineresource metadata is set in the map’s web object metadata and specifies the URL that should be used to access your server. This is required for the GetCapabilities output. If wfs_onlineresource is not provided then MapServer will try to provide a default one using the script name and hostname, but you shouldn’t count on that too much. It is strongly recommended that you provide the wfs_onlineresource metadata.

    See section 12.3.3 of the WFS 1.0.0 specification for the whole story about the online resource URL. Basically, what you need is a complete HTTP URL including the http:// prefix, hostname, script name, potentially a “map=” parameter, and and terminated by ”?” or “&”.

    Here is a valid online resource URL:

    http://my.host.com/cgi-bin/mapserv?map=mywfs.map&

    By creating a wrapper script on the server it is possible to hide the “map=” parameter from the URL and then your server’s online resource URL could be something like:

    http://my.host.com/cgi-bin/mywfs?

    This is covered in more detail in the “More About the Online Resource URL” section of the WMS Server document.

  • The “wfs_enable_request” metadata (see below).

Example WFS Server Mapfile

The following is an example of a bare minimum WFS Server mapfile. Note the comments for the required parameters.

MAP
  NAME "WFS_server"
  STATUS ON
  SIZE 400 300
  SYMBOLSET "../etc/symbols.txt"
  EXTENT -180 -90 180 90
  UNITS DD
  SHAPEPATH "../data"
  IMAGECOLOR 255 255 255
  FONTSET "../etc/fonts.txt"


  #
  # Start of web interface definition
  #
  WEB
    IMAGEPATH "/ms4w/tmp/ms_tmp/"
    IMAGEURL "/ms_tmp/"
    METADATA
      "wfs_title"          "WFS Demo Server for MapServer" ## REQUIRED
      "wfs_onlineresource" "http://demo.mapserver.org/cgi-bin/wfs?" ## Recommended
      "wfs_srs"            "EPSG:4326 EPSG:4269 EPSG:3978 EPSG:3857" ## Recommended
      "wfs_abstract"       "This text describes my WFS service." ## Recommended
      "wfs_enable_request" "*"  # necessary
    END
  END

  PROJECTION
    "init=epsg:4326"
  END

  #
  # Start of layer definitions
  #

  ##################
  # World Continents
  ##################
  LAYER
    NAME "continents"
    METADATA
      "wfs_title"         "World continents" ##REQUIRED
      "wfs_srs"           "EPSG:4326" ## REQUIRED
      "gml_include_items" "all" ## Optional (serves all attributes for layer)
      "gml_featureid"     "ID" ## REQUIRED
      "wfs_enable_request" "*"
    END
    TYPE POLYGON
    STATUS ON
    DATA 'shapefile/countries_area'
    PROJECTION
      "init=epsg:4326"
    END
    CLASS
      NAME 'World Continents'
      STYLE
        COLOR 255 128 128
        OUTLINECOLOR 96 96 96
      END
    END
  END #layer

END #mapfile

Rules for Handling SRS in MapServer WFS

The OGC WFS 1.0 specification doesn’t allow a layer (feature type) to be advertised in more than one SRS. Also, there is no default SRS that applies to all layers by default. However, it is possible to have every layer in a WFS server advertised in a different SRS.

The OGC WFS 1.1 specification allows more than one SRS to be advertised, and one of the SRSs will be advertised as the default SRS (the default SRS will be the first in the list specified in the METADATA wfs_srs / ows_srs).

Here is how MapServer decides the SRS to advertise and use for each layer in your WFS:

  • If a top-level map SRS is defined then this SRS is used and applies to all layers (feature types) in this WFS. In this case the SRS of individual layers is simply ignored even if it is set.
  • If no top-level map SRS is defined, then each layer is advertised in its own SRS in the capabilities.

Note

By “SRS is defined”, we mean either the presence of a PROJECTION object defined using an EPSG code, or of a wfs_srs / ows_srs metadata at this level.

Note

At the map top-level the wfs_srs / ows_srs metadata value takes precedence over the contents of the PROJECTION block.

At the layer level, if both the wfs_srs / ows_srs metadata and the PROJECTION object are set to different values, then the wfs_srs / ows_srs metadata defines the projection to use in advertising this layer (assuming there is no top-level map SRS), and the PROJECTION value is assumed to be the projection of the data. So this means that the data would be reprojected from the PROJECTION SRS to the one defined in the wfs_srs / ows_srs metadata before being served to WFS clients.

Confusing? As a rule of thumb, simply set the wfs_srs / ows_srs at the map level (in web metadata) and never set the wfs_srs / ows_srs metadata at the layer level and things will work fine for most cases.

Axis Orientation in WFS 1.1

The axis order in previous versions of the WFS specifications was to always use easting (x or lon ) and northing (y or lat). WMS 1.1 specifies that, depending on the particular SRS, the x axis may or may not be oriented West-to-East, and the y axis may or may not be oriented South-to-North. The WFS portrayal operation shall account for axis order. This affects some of the EPSG codes that were commonly used such as ESPG:4326. The current implementation makes sure that coordinates returned to the server for the GetFeature request reflect the inverse axis orders for EPSG codes between 4000 and 5000.

Test Your WFS Server

Validate the Capabilities Metadata

OK, now that we’ve got a mapfile, we have to check the XML capabilities returned by our server to make sure nothing is missing.

Using a web browser, access your server’s online resource URL to which you add the parameter “REQUEST=GetCapabilities” to the end, e.g.

http://demo.mapserver.org/cgi-bin/wfs?SERVICE=WFS&VERSION=1.0.0&REQUEST=GetCapabilities

If everything went well, you should have a complete XML capabilities document. Search it for the word “WARNING”... MapServer inserts XML comments starting with “<!–WARNING: ” in the XML output if it detects missing mapfile parameters or metadata items. If you notice any warning in your XML output then you have to fix all of them before you can register your server with a WFS client, otherwise things are likely not going to work.

Note

The SERVICE parameter is required for all WFS requests. When a request happens, it is passed through WMS, WFS, and WCS in MapServer (in that order) until one of the services respond to it.

Test With a GetFeature Request

OK, now that we know that our server can produce a valid XML GetCapabilities response we should test the GetFeature request. Simply adding “SERVICE=WFS&VERSION=1.0.0&REQUEST=GetFeature&TYPENAME=yourlayername1,yourlayername2” to your server’s URL should return the GML associated with those layers.

http://demo.mapserver.org/cgi-bin/wfs?SERVICE=WFS&VERSION=1.0.0&REQUEST=getfeature&TYPENAME=continents&MAXFEATURES=100

Test with a Real Client

If you have access to a WFS client, then register your new server’s online resource with it and you should be off and running.

If you don’t have your own WFS client installed already, here are a few pointers:

  • MapServer itself can be used as a WFS client, see the WFS Client HowTo.
  • Quantum GIS is a full GIS package which includes WFS client support. (recommended)
  • Deegree provides a WFS client.
  • uDig can add layers from WMS/WFS servers.
  • The owsview Viewer Client Generator is an online application that allows users to validate WFS Capabilities XML (it does not allow you to view WFS data).

Support for GET and POST Requests

Starting from version 4.2 MapServer supports XML-encoded POST requests and GET requests. The default in MapServer is POST.

Support for Filter Encoding

Starting from version 4.2 MapServer supports Filter Encoding (FE) in WFS GetFeature requests. For more information on the server side of Filter Encoding see the Filter Encoding HowTo.

MapServer WFS Extensions

STARTINDEX
In addition to the MAXFEATURES=n keyword, MapServer also supports a STARTINDEX=n keyword in WFS GetFeature requests. This can be used to skip some features in the result set and in combination with MAXFEATURES provides for the ability to use WFS GetFeature to page through results. Note that STARTINDEX=1 means start with the first feature, skipping none.
OUTPUTFORMAT
Normally OUTPUTFORMAT should be GML2 for WFS 1.0 and either “text/xml; subtype=gml/2.1.2” or “text/xml; subtype=gml/3.1.1” for WFS 1.1. However as an extension to the specification, it is also possible to configure MapServer for a variety of other feature output formats. This is discussed in some detail in the OGR Output document.

Reference Section

The following metadata are available in the setup of the WFS Server mapfile:

Note

Each of the metadata below can also be referred to as ‘ows_*’ instead of ‘wfs_*’. MapServer tries the ‘wfs_*’ metadata first, and if not found it tries the corresponding ‘ows_*’ name. Using this reduces the amount of duplication in mapfiles that support multiple OGC interfaces since “ows_*” metadata can be used almost everywhere for common metadata items shared by multiple OGC interfaces.

Web Object Metadata

ows_schemas_location
(Optional) (Note the name ows_schemas_location and not wfs/_... this is because all OGC Web Services (OWS) use the same metadata) Root of the web tree where the family of OGC WFS XMLSchema files are located. This must be a valid URL where the actual .xsd files are located if you want your WFS output to validate in a validating XML parser. Default is http://schemas.opengis.net. See http://ogc.dmsolutions.ca for an example of a valid schema tree.
ows_updatesequence
(Optional) The updateSequence parameter can be used for maintaining the consistency of a client cache of the contents of a service metadata document. The parameter value can be an integer, a timestamp in [ISO 8601:2000] format, or any other number or string.
wfs_abstract

(Optional) Descriptive narrative for more information about the server.

WFS TAG Name: Abstract (WFS 1.0.0, sect. 12.3.3)

wfs_accessconstraints

(Optional) Text describing any access constraints imposed by the service provider on the WFS or data retrieved from this service.

WFS TAG Name: Accessconstraints (WFS 1.0.0, sect. 12.3.3)

wfs_enable_request (or ows_enable_request)

Space separated list of requests to enable. The default is none. The following requests can be enabled: GetCapabilities, GetFeature and DescribeFeatureType. A ”!” in front of a request will disable the request. “*” enables all requests.

Examples:

To enable only GetCapabilities and GetFeature:

"wfs_enable_request" "GetCapabilities GetFeature"

To enable all requests except GetCapabilities

"wfs_enable_request" "* !GetCapabilities"
wfs_encoding
(Optional) XML encoding for all XML documents returned by the server. The default is ISO-8859-1.
wfs_feature_collection
Replaces the default name of the feature-containing element (<msFeatureCollection>) with a user-defined value.
wfs_fees

(Optional) Any fees imposed by the service provider for usage of this service or for data retrieved from the WFS.

WFS TAG Name: Fees (WFS 1.0.0, sect. 12.3.3)

wfs_getcapabilities_version
(Optional) Default version to use for GetCapabilities requests that do not have a version parameter. If not set, the latest supported version will be returned.
wfs_keywordlist

(Optional) List of words to aid catalog searching.

WFS TAG Name: Keyword (WFS 1.0.0, sect. 12.3.3)

wfs_maxfeatures
(Optional) The number of elements to be returned by the WFS server. This has priority over the ‘maxfeatures’ parameter passed by the user. If the not set the current behaviour is not changed. Sensible values are integers greater than 0. If 0 is specified, no features will be returned.
wfs_namespace_prefix
(Optional) User defined namespace prefix to be used in the response of a WFS GetFeature request. E.g. “wfs_namespace_prefix” “someprefix”.
wfs_namespace_uri
(Optional) User defined namespace URI to be used in the response of a WFS GetFeature request. e.g. “wfs_namespace_uri” “http://somehost/someurl”.
wfs_onlineresource

(Recommended) The URL prefix for HTTP GET requests.

WFS TAG Name: Onlineresource (WFS 1.0.0, sect. 12.3.3)

wfs_service_onlineresource

(Optional) Top-level onlineresource URL. MapServer uses the onlineresource metadata (if provided) in the following order:

  1. wfs_service_onlineresource
  2. ows_service_onlineresource
  3. wfs_onlineresource (or automatically generated URL, see the onlineresource section of this document)
wfs_srs
(Recommended) The SRS to use for all layers in this server. (e.g. EPSG:4326) See the note about the SRS rules in WFS.
wfs_title

(Required) Human readable title to identify server.

WFS TAG Name: Title (WFS 1.0.0, sect. 12.3.3)

Layer Object

gml_constants

(Optional) A comma delimited list of constants. This option allows you to define data that are not part of the underlying dataset and add them to the GML output. Many application schemas require constants of one form or another. To specify the value and type of the constants use gml_[item name]_value and gml_[item name]_type.

"gml_constants" "const1,const2"
"gml_const1_type" "Character"
"gml_const1_value" "abc"
"gml_const2_type" "Integer"
"gml_const2_value" "999"
gml_exclude_items

(Optional) A comma delimited list of items to exclude. As of MapServer 4.6, you can control how many attributes (fields) you expose for your data layer with metadata. The previous behaviour was simply to expose all attributes all of the time. The default is to expose no attributes at all. An example excluding a specific field would be:

"gml_include_items" "all"
"gml_exclude_items" "Phonenum"
gml_featureid
(Required for MapServer 4.10) Field to be used for the ID of the feature in the output GML. wfs_featureid or ows_featureid can be specified instead.
gml_geometries
Provides a name other than the default “msGeometry” for geometry elements. The value is specified as a string to be used for geometry element names.
gml_[geometry name]_occurances
MapServer applies default values of 0 and 1, respectively, to the “minOccurs” and “maxOccurs” attributes of geometry elements, as can be seen in the preceding examples. To override these defaults, a value is assigned to a gml_[geometry name]_occurances layer metadata item, where again [geometry name] is the string value specified for gml_geometries, and the value is a comma-delimited pair containing the respective lower and upper bounds.
gml_[geometry name]_type

When employing gml_geometries, it is also necessary to specify the geometry type of the layer. This is accomplished by providing a value for gml_[geometry name]_type, where [geometry name] is the string value specified for gml_geometries, and a value which is one of:

  • point
  • multipoint
  • line
  • multiline
  • polygon
  • multipolygon
gml_groups
(Optional) A comma delimited list of group names for the layer.
gml_[group name]_group

(Optional) A comma delimited list of attributes in the group. Here is an example:

"gml_include_items" "all"
"gml_groups"        "display"
"gml_display_group" "Name_e,Name_f"
gml_include_items

(Optional) A comma delimited list of items to include, or keyword “all”. As of MapServer 4.6, you can control how many attributes (fields) you expose for your data layer with this metadata. The previous behaviour was simply to expose all attributes all of the time. You can enable full exposure by using the keyword “all”, such as:

"gml_include_items" "all"

You can specify a list of attributes (fields) for partial exposure, such as:

"gml_include_items" "Name,ID"

The new default behaviour is to expose no attributes at all.

gml_[item name]_alias

(Optional) An alias for an attribute’s name. The served GML will refer to this attribute by the alias. Here is an example:

"gml_province_alias" "prov"
gml_[item name]_precision
(Optional) Specifies the precision of the indicated field for formats where this is significant, such as Shapefiles. Precision is the number of decimal places, and is only needed for “Real” fields. Currently this is only used for OGR based output formats, not the WFS GML2/GML3 output.
gml_[item name]_type
(Optional) Specifies the type of the attribute. Valid values are Integer|Real|Character|Date|Boolean.
gml_[item name]_value
Used to specify values for gml_constants.
gml_[item name]_width
(Optional) Specifies the width of the indicated field for formats where this is significant, such as Shapefiles.
gml_types

(Optional) If this field is “auto” then some input feature drivers (ie. OGR, POSTGIS, ORACLESPATIAL and native shapefiles) will automatically populate the type, width and precision metadata for the layer based on the source file. Currently this is only used for OGR based output formats, not the WFS GML2/GML3 output.

"gml_types"   "auto"
gml_xml_items
(Optional) A comma delimited list of items that should not be XML-encoded.
wfs_abstract
Same as wfs_abstract in the Web Object.
wfs_enable_request (or ows_enable_request)

Space separated list of requests to enable. The default is none. The following requests can be enabled: GetCapabilities, GetFeature and DescribeFeatureType. A ”!” in front of a request will disable the request. “*” enables all requests.

Examples:

To enable only GetCapabilities and GetFeature:

"wfs_enable_request" "GetCapabilities GetFeature"

To enable all requests except GetCapabilities

"wfs_enable_request" "* !GetCapabilities"
wfs_extent
(Optional) Used for the layer’s BoundingBox tag for cases where it is impossible (or very inefficient) for MapServer to probe the data source to figure its extents. The value for this metadata is “minx miny maxx maxy” separated by spaces, with the values in the layer’s projection units. If wfs_extent is provided then it has priority and MapServer will NOT try to read the source file’s extents.
wfs_featureid
(Required for MapServer 4.10) Field to be used for the ID of the feature in the output GML. gml_featureid or ows_featureid can be specified instead.
wfs_getfeature_formatlist
(Optional) Comma-separted list of formats that sould be valid for a GetFeature request. If defined, only these formats are advertised through in the Capabilities document.
wfs_keywordlist
Same as wfs_keywordlist in the Web Object.
wfs_metadataurl_format
(Optional) The file format of the metadata record. Valid values are “XML”, “SGML”, or “HTML”. The layer metadata wfs_metadataurl_type and wfs_metadataurl_href must also be specified. Refer to section 12.3.5 of the WFS 1.0.0 spec.
wfs_metadataurl_href
(Optional) The URL to the layer’s metadata. The layer metadata wfs_metadataurl_type and wfs_metadataurl_format must also be specified. Refer to section 12.3.5 of the WFS 1.0.0 spec.
wfs_metadataurl_type
(Optional) The standard to which the metadata complies. Currently only two types are valid: “TC211” which refers to [ISO 19115], and “FGDC” which refers to [FGDC CSDGM]. The layer metadata wfs_metadataurl_format and wfs_metadataurl_href must also be specified. Refer to section 12.3.5 of the WFS 1.0.0 spec.
wfs_srs
If there is no SRS defined at the top-level in the mapfile then this SRS will be used to advertize this feature type (layer) in the capabilities. See the note about the SRS rules in WFS.
wfs_title
Same as wfs_title in the Web Object.

To-do Items and Known Limitations

  • This is just a basic WFS (read-only): transaction requests are not supported and probably never will given the nature of MapServer. GeoServer or TinyOWS is recommended for those needing WFS-T support.
  • WFS spec. seems to require that features of a given feature type must all be of the same geometry type (point, line, polygon). This works fine for shapefiles, but some data source formats supported by MapServer allow mixed geometry types in a single layer and this goes against the WFS spec. Suggestions on how to handle this are welcome (send suggestions to the mapserver-dev mailing list.