[Requests] Rewrite all requirements and tests in the ESRI proposed map request handling service (12-056)
ac at pocz.org
Mon Jul 23 13:01:55 EDT 2012
ac at pocz.org
GeoServices REST API - Part 3: Map Service (12-056r1)
General - All requirements and tests, with surrounding text.
2. Implementation Specification Section number:
4. Comments/justifications for changes:
The proposed specification needs an enormous amount of work in order to
become a clear definition of a service furnishing cartographic images
over the Internet for which multiple, interoperable instances could be
developed. As written, the specification is exceedingly hard to
understand, the tests unclear, and the actually specified functionality
unknown. The result of adopting the standard as currently written will
be a mess, with different implementations each working in their own way
leaving clients to pick up the pieces and learn to address the quirks of
each deployed endpoint separately.
The OGC membership should reject this standard until the hard work has
been done of actually defining the service behavior, of codifying that
behavior into clear requirements, and of further developing those
requirements into clear, targeted testing procedures.
As the document currently stands, it is unsuitable for publication.
The proposed specification does not develop clear requirements matched
to direct, logical tests, which is one of the requirements of "The
Specification Model" standard designed to improve the specifications at
As an example, start with the first requirement:
Req 1 The Map Service Root resource SHALL accept requests that
conform to the URI template in Table and use any HTTP method
identified in the same table.
which requires some conceptual gymnastics to figure out what it might be
saying (ignoring the broken link). The "Map Service Root" is not a
standardization target type, indeed conceiving of resources being things
that receive requests requires some gratuitous abstraction for seemingly
no gain. The actual requirement would benefit from being reformulated
into some injunction on an instance of a 'web service.' I take the
requirement to mean that the 'web service' is expected to accept a
request sent in an HTTP message with a Request-Target which starts with
the path of the 'web service root URI' and, presumably, is sent over a
TCP/IP connection made to the host:port combination of the 'map service
root URI'. Of course, according to the rules of TCP, the web service has
to accept all requests, so presumably this requirement actually is
trying to say something different. I might take the requirement to mean
that the web service instance is expected to respond with an HTTP
message with a code in the 200 series like "200 OK" and the requested
content, i.e. furnish a functional response. Probably, the requirement
should say that the web service shall respond to a request in the given
pattern with a specificaly formulated response. As it stands, as an
implementor, I would simply ignore this requirement as ill founded,
confused, or ridiculous; it is not worth my time to find out which.
One purpose of having a test suite is to disambiguate poorly written
requirements of this kind. The test should tell me exactly how the
requirement will be assessed which should help explain the requirement.
However, where is the test? I might guess that the test of the first
requirement would be the first test in the test suite. This test gives
as its purpose: "Verify that the Map Service Root resource supports the
request and response requirements." which pretty quickly lets us know
that we have some kind of vague, hand waving test which is not going to
help us figure out the requirement. I am expecting a test that is trying
to cause a web service to 'refuse to accept a request'. However, the
test seems to be testing the response and it looks like I could simply
send back the same error message the whole time and pass the test.
"Inspect the responses and validate them against the JSON
Schema http://schemas.opengis.net/gsr-ms/1.0/root.json or for
In other words, the authors of the proposed document have just
constructed a generic, catch all "test the service" test that does not
help us implement the requirements of the document. This is a waste of
implementor's time, of the CITE testing folks' time, and of the document
Beyond the poorly written requirements and tests, the specification does
not undertake the most minimal explanatory effort to explain what
behaviour is expected of the service. Take the 'dpi' parameter of the
map request which presumably has some impact on the response. The ENTIRE
discussion of this parameter comes in the one sentence definition:
"The device resolution of the exported image (dots per inch)."
which is, of course, non-sensical since images do not have devices. The
document completely lacks any explanation of what this parameter is
supposed to change in the response and the document does not clarify
that with a test that might explain the requirement more clearly. Again
it seems the web service must only accept the parameter in the request,
it may then simply ignore it completely.
In other words, the document has not undertaken the most minimal effort
of explaining the functionality of one of the elements proposed for the
proposed web service. Presumably, the web service 'should work like
ESRI's implementation' but that is not interoperability.
This analysis could go on for a while. The authors have done heroic work
writing this extended series of documents. Unfortunately, because the
specification is merely providing window dressing for the one reference
implementation, the authors did not do the hard work of defining the
behaviour, developing well formulated requirements to enforce that
behaviour, and conceiving of effective tests to ensure that behaviour is
respected. The result is a document which leaves all the work of
standardization to the CITE test developers and the implementors, a
recipe for non-interoperable results.
It is not worth this submitter's time to comment more extensively on
this specification because the authors have made clear they do not
intend to fix any of the substantive issues encountered. However, a
simple look at the form of the document reveals that it is unsuited for
publication absent some major, extensive editorial work.
More information about the Requests