{ "attachments": [], "comments_archived": true, "date": "2003-07-01T00:25:35.000Z", "layout": "post", "title": "Please fix the XML-RPC spec", "wordpress_id": 434, "wordpress_slug": "plz-fix-xmlrpc-spec", "wordpress_url": "http://www.decafbad.com/blog/?p=434", "year": "2003", "month": "06", "day": "30", "isDir": false, "slug": "plz-fix-xmlrpc-spec", "type": "entry", "postName": "2003-06-30-plz-fix-xmlrpc-spec", "html": "

I've written before that I love XML-RPC, and\nthat it has served me well in the past couple of years. I think it's the right tool for a broad\nrange of jobs. But, after having studied the spec, and after having implemented it in a handful\nof languages for a handful of well-used apps, I think the spec needs just a bit of fixing.

\n

In particular, the spec needs a tweak with regards to this \"ASCII limitation\". There is confusion\nabout this, period. I've had to hash this out with clients before, this \nwas an issue of note while\nworking out an XML-RPC based Wiki API,\nand it's obviously an issue in many other projects. This, of course, includes the current\nhubbub surrounding weblog APIs and whatnot.

\n

So, please fix the spec. It shouldn't take long to make this issue a non-issue by some simple\nclarification in the main XmlRpc to which everyone refers.

\n

Yes, I know there's a bit of clarification at the end of the spec, involving escaping (\nnot encoding) < and & along\nwith the statement that \"A string can be used to encode binary data.\"

\n

Well, yeah, I do that\nall the time with Base64. And, since\nthe spec earlier had called for \"ASCII\", I assume that's what encoding\nbinary data means in the context of this spec. To me, encoding implies a transformation \nfrom original form to some other form later requiring decoding.

\n

But, apparently, my interpretation and \nthe interpretation of others\nis wrong on that score. But still, I've been confused, and so have others. Consider this a bug report.

\n

I've been referred by Fredrik Lundh (via Dave Winer), \nto \"private conversations\",\n\"various public fora\", and \"early archives for the XML-RPC mailing list\". And, again by Fredrik Lundh,\nI'm told:

\n
But even if you don't know all this, it's not that hard to figure it out for\nyourself. Just make sure you read and digest the entire specification, apply some common sense\nto sort out the contradictions, and you'll find that it's pretty obvious that the intent is that\nyou can use any character allowed by XML.
\n\n\n\n\n\n

Well, let's see. I read the whole spec, more than once, and what I figured out for myself with my \n\"common sense\" is what I wrote above. I thought\nthe spec called for ASCII (as in: ASCII), and assumed that\nencoding binary data called for something like Base64. Yes, I realize that XmlRpc is XML, but\nwhen a spec calls for ASCII as a particular part, I assume that there's a reason for it\nsince that's what the specification specified.

\n

In my experience, specifications are not about common sense, figuring it out, and\nconnotation. Specifications are\nabout declaration, clarity, and \ndenotation.

\n

Yes, I understand that no\nspec is perfect, and that many are steaming piles meeting none of the criteria I just mentioned,\nbut that doesn't alter the goal. A spec can always be made better by revising \nwith these things in mind, given the input of consumers of the spec. This is what a process\nof communication is all about, and specifications are intended as a form of communication.

\n

So, instead of talking about intent and things that have been talked about somewhere\nat some time, with the implication that I should just go off and search for these things, can \nwe just get a clarifying fix to the XmlRpc spec? I don't want to send my clients off to \nmailing list and discussion archives, or present XmlRpc with any corrections or caveats. I\nwant to say, as I have been, \"Here, go to xmlrpc.com, read the spec, implement to the API\nI emailed you, and get back to me.\" Only, it'd be nice if the first question is about my API, \nnot about character encoding.

\n

I've been confused, and so have others. I consider myself a smart person, and I consider most\nof the others who have been confused as even smarter. I apologize if my \"common sense\" is of a\ndifferent sort, but that's what you have to deal with in the world of people. As young as I am,\neven I've discovered this already.

\n

So, can we just get a clarifying revision of the spec? And if not, why not?

\n

Update: Rock on. After catching up \non a bit of banter over at Sam's place, I see that\nthe same Fredrik Lundh I quoted before has already begun an\nXML-RPC errata page with the goal of clarification.\n(I just missed it in my daily reading thus far.) As \nMark comments, I fear bumps in the\nroad as any confused implementors find things weren't what they thought, but I'm happy to see\nthe clarification accepted.

\n

Update again: If you've stopped rocking, resume. Dave Winer \nupdated the XML-RPC spec.\nIt was a small change, could have been more, but had not been done at all until now. I\ndoubt that my asking please really had much to do with it, but I couldn't guess that it \nhurt. Thanks!

\n\n\n\n

shortname=plz_fix_xmlrpc_spec

\n

Archived Comments

\n\n\n\n
\n\n\n", "body": "I've written before that I love XML-RPC, and\r\nthat it has served me well in the past couple of years. I think it's the right tool for a broad\r\nrange of jobs. But, after having studied the spec, and after having implemented it in a handful\r\nof languages for a handful of well-used apps, I think the spec needs just a bit of fixing.\r\n

\r\nIn particular, the spec needs a tweak with regards to this \"ASCII limitation\". There is confusion\r\nabout this, period. I've had to hash this out with clients before, this \r\nwas an issue of note while\r\nworking out an XML-RPC based Wiki API,\r\nand it's obviously an issue in many other projects. This, of course, includes the current\r\nhubbub surrounding weblog APIs and whatnot.\r\n

\r\nSo, please fix the spec. It shouldn't take long to make this issue a non-issue by some simple\r\nclarification in the main XmlRpc to which everyone refers.\r\n

\r\nYes, I know there's a bit of clarification at the end of the spec, involving escaping (\r\nnot encoding) < and & along\r\nwith the statement that \"A string can be used to encode binary data.\" \r\n

\r\nWell, yeah, I do that\r\nall the time with Base64. And, since\r\nthe spec earlier had called for \"ASCII\", I assume that's what encoding\r\nbinary data means in the context of this spec. To me, encoding implies a transformation \r\nfrom original form to some other form later requiring decoding.\r\n

\r\nBut, apparently, my interpretation and \r\nthe interpretation of others\r\nis wrong on that score. But still, I've been confused, and so have others. Consider this a bug report.\r\n

\r\nI've been referred by Fredrik Lundh (via Dave Winer), \r\nto \"private conversations\",\r\n\"various public fora\", and \"early archives for the XML-RPC mailing list\". And, again by Fredrik Lundh,\r\nI'm told:\r\n
But even if you don't know all this, it's not that hard to figure it out for\r\nyourself. Just make sure you read and digest the entire specification, apply some common sense\r\nto sort out the contradictions, and you'll find that it's pretty obvious that the intent is that\r\nyou can use any character allowed by XML.
\r\n

\r\nWell, let's see. I read the whole spec, more than once, and what I figured out for myself with my \r\n\"common sense\" is what I wrote above. I thought\r\nthe spec called for ASCII (as in: ASCII), and assumed that\r\nencoding binary data called for something like Base64. Yes, I realize that XmlRpc is XML, but\r\nwhen a spec calls for ASCII as a particular part, I assume that there's a reason for it\r\nsince that's what the specification specified. \r\n

\r\nIn my experience, specifications are not about common sense, figuring it out, and\r\nconnotation. Specifications are\r\nabout declaration, clarity, and \r\ndenotation. \r\n

\r\nYes, I understand that no\r\nspec is perfect, and that many are steaming piles meeting none of the criteria I just mentioned,\r\nbut that doesn't alter the goal. A spec can always be made better by revising \r\nwith these things in mind, given the input of consumers of the spec. This is what a process\r\nof communication is all about, and specifications are intended as a form of communication.\r\n

\r\nSo, instead of talking about intent and things that have been talked about somewhere\r\nat some time, with the implication that I should just go off and search for these things, can \r\nwe just get a clarifying fix to the XmlRpc spec? I don't want to send my clients off to \r\nmailing list and discussion archives, or present XmlRpc with any corrections or caveats. I\r\nwant to say, as I have been, \"Here, go to xmlrpc.com, read the spec, implement to the API\r\nI emailed you, and get back to me.\" Only, it'd be nice if the first question is about my API, \r\nnot about character encoding.\r\n

\r\nI've been confused, and so have others. I consider myself a smart person, and I consider most\r\nof the others who have been confused as even smarter. I apologize if my \"common sense\" is of a\r\ndifferent sort, but that's what you have to deal with in the world of people. As young as I am,\r\neven I've discovered this already.\r\n

\r\nSo, can we just get a clarifying revision of the spec? And if not, why not?\r\n

\r\nUpdate: Rock on. After catching up \r\non a bit of banter over at Sam's place, I see that\r\nthe same Fredrik Lundh I quoted before has already begun an\r\nXML-RPC errata page with the goal of clarification.\r\n(I just missed it in my daily reading thus far.) As \r\nMark comments, I fear bumps in the\r\nroad as any confused implementors find things weren't what they thought, but I'm happy to see\r\nthe clarification accepted.\r\n

\r\nUpdate again: If you've stopped rocking, resume. Dave Winer \r\nupdated the XML-RPC spec.\r\nIt was a small change, could have been more, but had not been done at all until now. I\r\ndoubt that my asking please really had much to do with it, but I couldn't guess that it \r\nhurt. Thanks!\r\n\r\nshortname=plz_fix_xmlrpc_spec\r\n\r\n
\r\n

Archived Comments

\r\n \r\n \r\n \r\n
\r\n ", "parentPath": "./content/posts/archives/2003", "path": "2003/06/30/plz-fix-xmlrpc-spec", "summary": "I've written before that I love XML-RPC, and\nthat it has served me well in the past couple of years. I think it's the right tool for a broad\nrange of jobs. But, after having studied the spec, and after having implemented it in a handful\nof languages for a handful of well-used apps, I think the spec needs just a bit of fixing.\nIn particular, the spec needs a tweak with regards to this \"ASCII limitation\". There is confusion\nabout this, period. I've had to hash this out with clients before, this \nwas an issue of note while\nworking out an XML-RPC based Wiki API,\nand it's obviously an issue in many other projects. This, of course, includes the current\nhubbub surrounding weblog APIs and whatnot.\nSo, please fix the spec. It shouldn't take long to make this issue a non-issue by some simple\nclarification in the main XmlRpc to which everyone refers.\nYes, I know there's a bit of clarification at the end of the spec, involving escaping (\nnot encoding) < and & along\nwith the statement that \"A string can be used to encode binary data.\" \nWell, yeah, I do that\nall the time with Base64. And, since\nthe spec earlier had called for \"ASCII\", I assume that's what encoding\nbinary data means in the context of this spec. To me, encoding implies a transformation \nfrom original form to some other form later requiring decoding.\nBut, apparently, my interpretation and \nthe interpretation of others\nis wrong on that score. But still, I've been confused, and so have others. Consider this a bug report.\nI've been referred by Fredrik Lundh (via Dave Winer), \nto \"private conversations\",\n\"various public fora\", and \"early archives for the XML-RPC mailing list\". And, again by Fredrik Lundh,\nI'm told:\nBut even if you don't know all this, it's not that hard to figure it out for\nyourself. Just make sure you read and digest the entire specification, apply some common sense\nto sort out the contradictions, and you'll find that it's pretty obvious that the intent is that\nyou can use any character allowed by XML.\n\n\n\n\n\nWell, let's see. I read the whole spec, more than once, and what I figured out for myself with my \n\"common sense\" is what I wrote above. I thought\nthe spec called for ASCII (as in: ASCII), and assumed that\nencoding binary data called for something like Base64. Yes, I realize that XmlRpc is XML, but\nwhen a spec calls for ASCII as a particular part, I assume that there's a reason for it\nsince that's what the specification specified. \nIn my experience, specifications are not about common sense, figuring it out, and\nconnotation. Specifications are\nabout declaration, clarity, and \ndenotation. \nYes, I understand that no\nspec is perfect, and that many are steaming piles meeting none of the criteria I just mentioned,\nbut that doesn't alter the goal. A spec can always be made better by revising \nwith these things in mind, given the input of consumers of the spec. This is what a process\nof communication is all about, and specifications are intended as a form of communication.\nSo, instead of talking about intent and things that have been talked about somewhere\nat some time, with the implication that I should just go off and search for these things, can \nwe just get a clarifying fix to the XmlRpc spec? I don't want to send my clients off to \nmailing list and discussion archives, or present XmlRpc with any corrections or caveats. I\nwant to say, as I have been, \"Here, go to xmlrpc.com, read the spec, implement to the API\nI emailed you, and get back to me.\" Only, it'd be nice if the first question is about my API, \nnot about character encoding.\nI've been confused, and so have others. I consider myself a smart person, and I consider most\nof the others who have been confused as even smarter. I apologize if my \"common sense\" is of a\ndifferent sort, but that's what you have to deal with in the world of people. As young as I am,\neven I've discovered this already.\nSo, can we just get a clarifying revision of the spec? And if not, why not?\nUpdate: Rock on. After catching up \non a bit of banter over at Sam's place, I see that\nthe same Fredrik Lundh I quoted before has already begun an\nXML-RPC errata page with the goal of clarification.\n(I just missed it in my daily reading thus far.) As \nMark comments, I fear bumps in the\nroad as any confused implementors find things weren't what they thought, but I'm happy to see\nthe clarification accepted.\nUpdate again: If you've stopped rocking, resume. Dave Winer \nupdated the XML-RPC spec.\nIt was a small change, could have been more, but had not been done at all until now. I\ndoubt that my asking please really had much to do with it, but I couldn't guess that it \nhurt. Thanks!", "needsBuild": true, "prevPostPath": "2003/06/26/so-like-i-was-saying", "prevPostTitle": "Like I was saying about RSS...", "nextPostPath": "2003/07/02/syndicated-whuffie", "nextPostTitle": "Syndicating Whuffie" }