In the attached version, I tried to address the things we agreed upon, and changed the service types/names table as proposed. Could you give it another pass, please? I left the Constructors untouched for now, until we agreed on something, ok?
Also, there is a question from me at the bottom of page 5:
"Note: Why not TimeOut, AuthorizationFailed, etc??"
For the discoverer constructor, I guess the Authentication exception can be thrown if you don't pass in a session or if you pass in what used to be a valid session that has since expired. How would you class that one? Unfortunately quite a lot of the allocation of exceptions is implementation dependent. It would be better to be able to just throw a Security exception - but that is not an option as it is not in the core spec. If you need to get authenticated this could result in a timeout if contact with some remote server is required. In our current implementation, list-services does most of the work and so can throw timeouts and could throw security errors except that we happen to connect to a non-secured information service. However the subsequent calls (such as get_data) can throw the same exceptions as they could choose to go back to the information service to pick up information that was not originally needed when making the selection. If we don't allow the possibility to throw these exceptions the implementation is needlessly restricted. This is why I like the NoSuccess everywhere. In other words I would use NoSuccess for those conditions which are implementation dependent - which in this case is quite a lot. For example you have added DoesNotExist for the constructor - implying that the API would contact the underyling information service. However there is no reason why it should do so at this stage.
Nothing is ever easy.
I am inclined to agree Steve