[Requests] Rewrite all requirements and tests in the ESRI proposed map request handling service (12-056)

Adrian Custer ac at pocz.org
Mon Jul 23 13:01:55 EDT 2012

Change Request


1. Evaluator:
     Adrian Custer
     ac at pocz.org

2. Submission:
     GeoServices REST API - Part 3: Map Service (12-056r1)


1. Requirement:
     General - All requirements and tests, with surrounding text.

2. Implementation Specification Section number:

3. Criticality:

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 
the OGC.

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
	exceptions against
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 
author's time.

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.

   Adrian Custer

More information about the Requests mailing list