JSON schemas and query parameters

[Max Loeb]

A few weeks back I decided to convert the APIs I use on my website to a schema-based format. I knew I wanted to use a rich JSON structure, but was this before I knew anything about the existence of JSON schema--all I knew was that I wanted to throw out my current crude approach and do something more similar to what ebay does (http://developer.ebay.com/DevZone/finding/CallRef/findItemsAdvanced.html), only without XML. On Friday I discovered JSON schema, fell in love, and have been madly coding since. 

I've been having a ball with it, and everything is fitting together wonderfully on back end calls and ajax calls, but there's one thing that puzzles me: how do query parameters factor into this?

I'll give you an example of what I mean. In my main schema I have a "sort" object:

"sort":{

    "type":"object",

    "description":"Specify a sort and a direction",

    "properties":{

        "type":{

            "enum":[

                "alpha",

                "productId",

                "releaseDate"

            ],

            "description":"The property to sort on",

            "default":"alpha"

        },

        "direction":{

            "enum":[

                "ascending",

                "descending"

            ],

            "description":"Choose a direction to sort",

            "default":"ascending"

        }

    }

}

I have the usual little sort widget on my site, and in my old model, whenever it changes, I would add its value (appending ".d" for a descending direction) to the query params and refresh the page (try it yourself: http://www.shmax.com/products/1?sort=release_date.d). 

Unless I change what I'm doing with my sort query parameter, I now have to write glue code to sort of convert what appears in the query parameters into a valid sort schema for my new schema-based API call on the back end. Is this what you guys generally do?

Or do you actually encode schema snippets into your query strings? Like:

http://www.shmax.com/products/1?sort=%7B%20%20%20%20type%3A%22releaseDate%22%2C%20%20%20%20direction%3A%22ascending%22%20%7D

Looks sort of ugly, but it does lessen the need for glue code.

Just wondering if you guys have any suggestions or insights from your own experience with something similar. Thanks much!

[Geraint]

Glad to hear you're so excited about JSON Schema!

The behaviour you describe is not a single document, but a set of variants on a particular document.  Are you using hyper-schemas to define a link to your "search" endpoint, and that "sort" schema is part of that link definition?  Or are you treating the submitted query as a document in its own right, with links defined using templates?

Query parameters have a defined format: application/x-www-form-urlencoded.  Sticking JSON data in a query parameter (as in your example) is not actually encoding the query as JSON - it's encoding an object as JSON and then encoding that JSON again as application/x-www-form-urlencoded, which I would only do if desperate.

When it comes to extracting the query parameters into something that a JSON Schema can deal with - most server-side languages can/will decode that query string into an object for you.  It will probably cast all your values to strings, but aside from that you should be able to deal with that object the same way you would decoded JSON data.

Geraint

[Max Loeb]

Thanks for the reply. I'm afraid I don't understand most of your questions, or what it is you're suggesting. I think you're asking how I construct my full query; the full query is constructed and executed on the back end, but I just want to sneak a few dynamic elements in here and there from the query params, such as sort info,  or num items per page. Are you suggesting that I DO encode bits of schema into the query parameters, only with a different method?  Can you point me at any examples? What is a hyper-schema?

[Geraint Luff]

OK, so you have some query parameters from the URL.  Based on that you search your datastore (using some kind of query object) - and you're asking if there's a way to automatically insert info from the URL query parameters into your datastore query object?

If so - that's more of a "transform" operation.  JSON Schema describes data, but it doesn't describe how to convert between data types.

Geraint

--
You received this message because you are subscribed to a topic in the Google Groups "JSON Schema" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/json-schema/ARNRztLeg_w/unsubscribe.
To unsubscribe from this group and all its topics, send an email to json-schema...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.