Wednesday, April 15, 2009

JSON Schema, part 2

So the JSON Schema stuff worked out:

chromium.tabs.createTab = function(tab, callback) {
validate(arguments, arguments.callee.params);
sendRequest(CreateTab, tab, callback);
};
chromium.tabs.createTab.params = [
{
type: "object",
properties: {
windowId: chromium.types.optPInt,
url: chromium.types.optStr,
selected: chromium.types.optBool
},
additionalProperties: false
},
chromium.types.optFun
];

--http://codereview.chromium.org/66006/diff/1087/1101

I'm really happy with how this came out because it means that all our APIs will get great error messages for free; it's not something that we'll have to think about (and therefore get wrong) on a case-by-case basis.

I tend to obsess about errors messages because they are basically the first-run experience for any library. No matter how well designed, people are going to typically call your API wrong the first time, especially in a loosely-typed language like JavaScript. What happens in that case? Does the API stare blankly back at them, leaving them to wonder if their code is even running? Or does it helpfully tell them what they did wrong?

Chromium APIs will give errors. Specifically, they will retort something like:
Invalid value for parameter 0. Property windowId: expected integer, got string.

9 comments:

Patrick Mueller said...

Very cool. Wonder if you could take this one step beyond, and use it to generate documentation for your APIs as well.

boots said...

Patrick, we've definitely considered that and it's easy to see how to do it.

I expect we will use a hybrid model for the docs, generating some and then tweaking them. I think it's important to have that human-written feel for documentation. But not totally sure yet.

lloyd hilaiel said...

yo aaron,

beautiful man. What json schema implementation are you using? crafting your own? we do a TON of validation by hand and it absolutely sucks. have long wanted a clean json schema implementation in C/C++ to complement yajl (http://lloyd.github.com/yajl/)

lloyd

Unknown said...

Hi Lloyd!

I'm actually running this code in JavaScript. I thought about doing it in C++, bu we want to do as much validation as possible in the renderer process so that we can synchronously throw errors. Also, since we can still make programming errors implementing the schemas, in the browser side when we consume the JSON, we still can't blindly trust it. So I didn't see any win to doing it in C++ and it's easier to work with in JS.

I started with the reference JS implementation, but I ended up wanting to optimize for readability instead of size, and I wanted some different features, so I just rewrote it. You can find it here:

http://src.chromium.org/viewvc/chrome/trunk/src/chrome/renderer/resources/json_schema.js?view=markup

I also have a change outstanding to it: http://codereview.chromium.org/77020

I would be interested in a C++ implementation of JSON schema though. Let me know if you find or create one!

virken said...

Hi Aaron,

Any chance you could tell us how to use your DOM-DRAG script with iPhone so that you can drag a DOM element without scrolling the page?

There's a simple function e.preventDefault(); available to do this - but heck if I can make it work.

Thanks very much

汇率查询 said...

This is so cool!
Thanks for sharing.

Unknown said...

Hi,

Sorry but I contact U for another reason... Do you you know how can you manually install flash plugin for Chromium. Because, that's not the same plug-in directory path as Chrome.

Thank U and sorry once again ^_^

jdunck said...

virken, standard dragging doesn't work on iPhone because a touch doesn't fire normal mouse events.

If you're ambitious, here's an explanation of iphone-specific touch events:
http://www.sitepen.com/blog/2008/07/10/touching-and-gesturing-on-the-iphone/

jdunck said...

I came to comments to say-- that's some hot shit, Aaron.