This chapter describes the format and structure of service capabilities reported by a HEEP server in response to a GetCap request. The purpose of a capabilities reporting facility is threefold:
Scalability: It is anticipated that the HEEP protocol will continue to evolve over time, gaining enhancements and usabilty as it develops. The ability for HEEP services to report their capabilities allows beter interaciton and negitioation between clients and servers running differing versions of the HEEP protocol, and removes many of the obstructions on the developers' side that traditionally accompany the requirement of backwards compatibility.
Compatibility: a service's ability to report its capabilities better ensures the development of 'informed' clients: applications that request only what is available from the service, in a supported format.
Customisation: The HEEP has been designed to facilitate, rather than restrict, the querying and exchange of heritage data. The stucture of the Capabilities XML and Request XML allow the inclusion of vendor-specific functions within the HEEP itself.
HEEP Capabilities in FISHXML_Capabilities format are produced in response to a GetCap (Get Capabilitities) query from a HEEP client. The XML schema itself dictates the structure of the Capabilities document (Section A.3, “Capabilities Schema”, but notes are provided here for guidance. We have also provided an example FISHXML_Capabilities in Section B.3, “Capabilitites Example”, and which is available for download at http://oxarchdigital.com/fish/hep/0.1/examples/example_capabilities.xml
The HEEP client shall be responsible for forming valid requests. If any element of the request is invalid, the server shall issue an exception.
This section describes the format of the FISH_Capabilities XML used to present the capabilities of an HEEP service. Users should refer to the schema for the formal document structure.
The root node.
Attributes:
This section presents a summary of the service provided by the HEEP server. Required.
Attributes: (none)
Server-generated identifier provided in response to a successful authentication request.
Attributes: (none)
Human readable title for the service descriptor, i.e., "UCL's UK Archaeology HEEP Server". Required.
Attributes: (none)
This section contains information which may restrict access
Attributes: (none)
Explination of any access constraints; note that, outside of basic authentication, the HEEP does not enforce access constraints.
Attributes: (none)
Records the maximum number of records that will be retruned as the result of a single query to a HEEP service. This is provided to notify clients if the quantity of data transferred per transaction is limted by the server.
Attributes: (none)
Identifies the URL of service provider (not the URL of the service itself); this will most likely be the home page of the provider.
Attributes: use the xmlns and xlink namespaces for URL references for all onlineResource elements.
This node encompasses contact information for the particular service. It is self-evident and not documented in detail here; the contact information element can be repeated multiple times.
Attributes: (none)
This element tree provides information about the data structre returned by default. When a request is made without using a resultset a HEEP service shall return the defaults it advertises in its capabilities.
Attributes: (none)
The object of the query in XPATH node representation. Equivalent to a "field" in SQL parlance.
Attributes:
Which nodes ("fields" in SQL parlance) the result set will be sorted on. Equivalent to SQL "ORDER BY".
Attributes: (none)
This section describes the one or more datasets that are available to the HEEP service.
Attributes: (none)
This section describes what data provided by the service. A 'dataset' is purely a conceptual entity and need have no formal concordance with the underlying database(s) or data structure. For example, a HEEP service may be connected to a single database of listed buildings: this database can represented by the HEEP service as multiple datasets broken down or pre-filtered by certain criteria, for example: "Medieval Listed Buildings" and "Post-medieval listed buildings". In the same way, a HEEP service can amalgamate multiple datasets into one conceptiual entity if necessary. Required.
Attributes: (none)
Access constraints of the dataset; this and its child nodes are described. The seperation of service and dataset metadata was intended to facilitate the construction of cascading HEEP services.
Attributes: (none)
Contains the URL for human-readable information about the dataset; contains the onlineResource child element in standard format.
Attributes: (none)
Contains information about the logo or graphic label used to identify the dataset. Child elements include onlineResource; the others child elements are self-explanitory.
Attributes: (none)
Contact information as above; like the Service, each dataset can have multiple contacts.
Attributes: (none)
This section describes the available spatial data and how it is stored or represented. This entire element tree is not required.
Attributes:
Indicates the extent of the spatial coverage. As in the OGIS WMS standard, a spatial coverage may be represented in multiple spatial reference systems, allowing, for example, a UK dataset to be represented in both Ordnance Survey Grid coordinates and Longitude/Latitude. The format of the element is identical to that in the OGIS WMS standard.
Attributes:
How are the spatial entities stored and delivered. Consists of two child elements: "point", "line" or "polygon".
Attributes: (none)
The spatial entity type: "point", "line" or "polygon". List all available types.
Attributes: (none)
Used to flag any restrictions on spatial data enfored by the surever, such as only returning 4 digit grid references. This is not used to indicate the accuracy of the data as stored, but ratehr used to indicate how the data provided may differ from what is recorded in the source dataset. Not required.
Attributes:
This element tree describes the resources and availability of each Operation. One child node exists for each Operation supported by the HEEP; many of the elements are self-explanitory, so only the problematic or otherwise difficult nodes are described here. Again, developers should always refer to the XML Schema for normative usage.
Attributes: (none)
The resource of each Operation is listed as a seperate child element tree.
Scope: all Operations
Attributes:
Lists the available MIME types for replies to the requested Operation. Valid values shall be limited to "text/xml" and "binary/gzip". See Section 7.8, “Compression” for more information. Required.
Scope: all Operations
Attributes: (none)
Lists the available character sets for replies to the requested Operation. Required.
Attributes: (none)