1.1   WFS-Related Information

Here are some WFS related links (including a newly added OGC services workshop with MapServer). Since these are highly detailed technical specifications, there is no need to read through them in their entirety to get a MapServer WFS up and running. It is still recommended however to read them over and get familiar with the basics of each of them, in order to understand how it all works:

• The OGC Web Feature Service Implementation Specification.
• The Geography Markup Language Implementation Specification.
• MapServer OGC Web Services Workshop package.

Working knowledge of MapServer is of course also required.

1.2   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.

1.3   Version 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:

• GML2 request output
• GML3 request output

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

2.1   Example WFS Server Mapfile

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

NAME WFS_server
STATUS ON
SIZE 400 300
SYMBOLSET ../etc/symbols.sym
EXTENT -2200000 -712631 3072800 3840000
UNITS METERS
SHAPEPATH "../data"
IMAGECOLOR 255 255 255
FONTSET ../etc/fonts.txt

WEB
  IMAGEPATH "/ms4w/tmp/ms_tmp/" 
  IMAGEURL "/ms_tmp/"
  METADATA
    "wfs_title"            "GMap WFS Demo Server"  ## REQUIRED
    "wfs_onlineresource"   "http://127.0.0.1/cgi-bin/mapserv.exe?"  ## Recommended
    "wfs_srs"               "EPSG:42304 EPSG:42101 EPSG:4269 EPSG:4326"  ## Recommended
    "ows_schemas_location" "http://ogc.dmsolutions.ca"  ## Optional
  END
END

PROJECTION
  "init=epsg:42304"
END

LAYER
  NAME province
  METADATA
    "wfs_title"    "Provinces" ## REQUIRED
    "gml_featureid" "ID" ## REQUIRED
    "gml_include_items" "all"  ## Optional (serves all attributes for layer)
  END
  TYPE POLYGON
  STATUS ON
  DATA province
  PROJECTION
    "init=epsg:42304"
  END
  DUMP TRUE           ## REQUIRED
  CLASS
    NAME "Canada"
    STYLE
      COLOR 200 255 0
      OUTLINECOLOR 120 120 120
    END
    TEMPLATE "ttt_query.html"
  END
END # Layer

END # Map File

2.2   Rules for Handling SRS in MapServer WFS

Contrary to WMS, the OGC WFS 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 in the OGC WFS spec. However, it is possible to have every layer in a WFS server advertised in a different 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's set.
• If there is no top-level map SRS defined* then each layer is advertised in its own SRS in the capabilities.
• By "SRS is defined", we mean either the presence of a PROJECTION object defined using an EPSG code, or of a "wfs_srs" metadata at this level.

Note that at the map top-level the "wfs_srs" metadata value takes precedence over the contents of the PROJECTION block.

At the layer level, if both the wfs_srs metadata and the PROJECTION object are set to different values, then the wfs_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 metadata before being served to WFS clients.

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

2.3   Test Your WFS Server

3.1   Web Object Metadata

ows_updatesequence

• Description: (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.

ows_schemas_location

• Description: (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.opengeospatial.net. See http://ogc.dmsolutions.ca for an example of a valid schema tree.

wfs_abstract

• WFS TAG Name: Abstract (WFS 1.0.0, sect. 12.3.3)
• Description: (Optional) Descriptive narrative for more information about the server.

wfs_accessconstraints

• WFS TAG Name: Accessconstraints (WFS 1.0.0, sect. 12.3.3)
• Description: (Optional) Text describing any access constraints imposed by the service provider on the WFS or data retrieved from this service.

wfs_encoding

• Description: (Optional) XML encoding for all XML documents returned by the server. The default is ISO-8859-1.

wfs_fees

• WFS TAG Name: Fees (WFS 1.0.0, sect. 12.3.3)
• Description: (Optional) Any fees imposed by the service provider for usage of this service or for data retrieved from the WFS.

wfs_keywordlist

• WFS TAG Name: Keyword (WFS 1.0.0, sect. 12.3.3)
• Description: (Optional) List of words to aid catalog searching.

wfs_maxfeatures

• Description: (Optional) The number of elements to be returned by the WFS server. This has priority over the 'wfs_maxfeatures' parameter passed by the user. If the not set the current behaviour is not changed.

wfs_namespace_prefix

• Description: (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

• Description: (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

• WFS TAG Name: Onlineresource (WFS 1.0.0, sect. 12.3.3)
• Description: (Recommended) The URL prefix for HTTP GET requests.

wfs_service_onlineresource

• Description: (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_title

• WFS TAG Name: Title (WFS 1.0.0, sect. 12.3.3)
• Description: (Required) Human readable title to identify server.

wfs_srs

• Description: (Recommended) The SRS to use for all layers in this server. (e.g. EPSG:4326) See the notes below about the SRS rules in the WFS.

wfs_feature_collection

• Description: Replaces the default name of the feature-containing element (<msFeatureCollection>) with a user-defined value.

3.2   Layer Object

gml_exclude_items

• Description: (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

• Description: (Required for MapServer 4.10) Field to be used for the ID of the feature in the output GML. wfs_featureid or ows_feature_id can be specified instead.

gml_groups

• Description: (Optional) A comma delimited list of group names for the layer.

gml_[group name]_group

• Description: (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

• Description: (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

• Description: (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]_type

• Description: (Optional) Specifies the type of the attribute. Valid values are Integer|Real|Character|Date|Boolean.

gml_xml_items

• Description: (Optional) A comma delimited list of items that should not be XML-encoded.

gml_geometries

• Description: 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_[name]_type

• Description: 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_[name]_type, where [name] is the string value specified for gml_geometries, and a value which is one of:

  • point
  • multipoint
  • line
  • multiline
  • polygon
  • multipolygon

gml_[name]_occurances

• Description: 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_[name]_occurances layer metadata item, where again [name] is the string value specified for gml_geometries, and the value is a comma-delimited pair containing the respective lower and upper bounds.

wfs_abstract

• Same as wfs_abstract in the Web Object.

wfs_extent

• Description: (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

• Description: (Required for MapServer 4.10) Field to be used for the ID of the feature in the output GML. gml_featureid or ows_feature_id can be specified instead.

wfs_keywordlist

• Same as wfs_keywordlist in the Web Object.

wfs_metadataurl_format

• Description: (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

• Description: (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

• Description: (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

• Description: 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 below about the SRS rules in the WFS.

wfs_title

• Same as wfs_title in the Web Object.

5.1   Copyright Information

Copyright (c) 2005, Jean-François Doyon, Jeff McKenna.

This documentation is covered by the same Open Source license as the MapServer software itself. See MapServer's License and Credits page for the complete text.

5.2   Disclaimer

No liability for the contents of this document can be accepted. Use the concepts, examples and other content at your own risk. As this is a new edition of this document, there may be errors and inaccuracies that may be damaging to your system. Although this is highly unlikely, the author(s) do not take any responsibility for that: proceed with caution.