[Community] Fw: open-services.net

[Martin Nally]

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

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://open-services.net/pipermail/community_open-services.net/attachments/20081203/21ab8bf1/attachment-0003.html>