Steve, I think the new pages you created at open-services.net look much better. I'm impressed at how quickly you turned that around. Nice job.
I have a technical comment to pass along. The text says: >> Update the referenced change request resource with the request's body. The content can be either application/xml or text/json . [my bold] The bold text is actually making a very strong architectural statement. What is says is that the true information model of the resource is neither the XML or the JSON, but some third thing (unexplained). To see this, imagine creating a request with XML, retrieving it with JSON, updating it with JSON (don't make any change, just send back the JSON you got), and then retrieve it with XML. You will not get back exactly the same XML, although the XML you get may be "equivalent" by some definition of equivalence we haven't written down. Things you will lose include XML white-space, XML comments, XML element ordering, XML namespace definition details (actually dealing with namespaces in JSON will be a whole technical topic), XML encoding information (utf8, utf16, ..) and possibly other stuff depending on the details of the XML involved. This might be the right approach for OSLC, I'm not sure. The alternative is to say that you can only PUT XML, and the XML is in fact the definition of the state of the resource, not just a representation of it. For things like defects, many systems will be holding the state in one or more relational tables, so for them, the XML and JSON are both just representations. For Jazz implementations, I think the XML will in fact be the real data going forward, and we will have to translate to and from JSON - with resulting loss of "XML detail" if we allow update through JSON. For resources whose text formats are standardized - programming language source, WSDL, BPEL, HTML, ODF, OOXML, many others - nobody is going to think it is acceptable to GET and PUT a different representation of those and lose the original text "detail". If we go with the design you proposed, we will have two kinds of resources - those that have a single "master" representation through which you must do updates (e.g. my list above), and those that have no "master" representation and that can be updated through several representations (e.g. defects), but "representation detail" of any paticular representation will be lost. This presumably puts a significant burden on the resource definer to define what parts of the representations are "essential" and what parts are "detail". Best regards, Martin Martin Nally, IBM Fellow CTO, IBM Rational tel: (949)544-4691
