I've dealt with WSDL and other representations. Coming from a mostly perl world, I really don't care for anything that I've seen. I just read the JSON-WSP service description you listed. It is a little better than WSDL, but only just a little. Most of the service description protocols seem to want to be able to wrap any function taking any type of arguments and returning any type of data. You can see this with various warts such as the doc_lines and def_order constructs of the JSON-WSP description. Those aren't really important details for what the method does - but represents an almost too literal representation of the underlying python library. I can see right off that it would make reordering the subroutine at a later date very problematic.

I've built well over a dozen protocols for various services. Over the years they have all migrated towards JSON over HTTP. I've gotten to the point where I don't really care about being able to wrap any subroutine signature under the sun. I've given myself a very simple layout.

1. I require a method name - I typically like to pass this along in the path info so that my access logs are more meaningful.
2. My arguments coming in are always a hashref.
3. My response is always a hashref.
4. If there is an error situation, there will be a key in the response called "error."

That is it. Those are all the rules. Exposing methods is always easy. Writing AJAX request/response handlers is always easy. Writing clients is always easy.

Since I have an easy format to follow, my meta description service is easy to write to as well. If I exposed a method called "foo," I would also write an accompanying sub called "foo_meta" which returns a very simple descriptive data structure. Here is one that I wrote within the past month or two:

sub __profile_meta {
    return {
        desc => 'Return an existing domain site profile',
        args => {
            domain => {
                desc     => 'Domain for which to fetch the profile',
                required => 1,
                type     => 'domain',
            },
            file => {
                desc     => 'Optional - The file location'
                            .' where this profile is installed.'
                            .' Defaults to profile.html",
                required => 0,
            },
        },
        result => {
            file             => 'The file that this profile'
                               .' will be installed at",
            body_logo        => "Logo for the page",
            body_sections    => [{
                type => 'Type of content',
                html => 'The content itself',
            }],
            body_slogan      => "Slogan for the page",
            contacts         => [{
                name    => "Name for this contact",
                email   => "Email for the contact",
            }],
            meta_description => 'Meta tag description',
            meta_keywords    => ['List of keywords'],
        },
    };
}
[download]

I've found that I can fit pretty much anything I need to into this scheme. Of course YMMV.