Permalink
Browse files

continued readme.

fixed sync test.
  • Loading branch information...
1 parent 1a75a98 commit ecce0de6cbe4ce367b13fa3bf811710246231962 @oferei committed Oct 15, 2012
Showing with 132 additions and 13 deletions.
  1. +22 −0 .gitattributes
  2. +93 −7 README.md
  3. +17 −6 test/sync-test.js
View
@@ -0,0 +1,22 @@
+# Auto detect text files and perform LF normalization
+* text=auto
+
+# Custom for Visual Studio
+*.cs diff=csharp
+*.sln merge=union
+*.csproj merge=union
+*.vbproj merge=union
+*.fsproj merge=union
+*.dbproj merge=union
+
+# Standard to msysgit
+*.doc diff=astextplain
+*.DOC diff=astextplain
+*.docx diff=astextplain
+*.DOCX diff=astextplain
+*.dot diff=astextplain
+*.DOT diff=astextplain
+*.pdf diff=astextplain
+*.PDF diff=astextplain
+*.rtf diff=astextplain
+*.RTF diff=astextplain
View
100 README.md
@@ -1,16 +1,24 @@
-# What's jsonly?
+# jsonly
_jsonly_ validates JSON objects against a JSON schema.
In other words, it makes sure an object conforms to the type and structure that your code expects.
+
For example, a server can use it to ensure input from a client conforms to the API.
-The JSON schema can also help with documentation and collaboration. Copy it to the API document and everybody will understand exactly what is expected.
+The JSON schema can also help with documentation and collaboration. Copy it to your API document and everybody should understand exactly what is expected.
+
+_jsonly_ is extremely easy to use:
+* A single function call
+* Both synchronous and asynchronous modes
+* Conforms to standard - no surprises
+* Well documented, in case you don't feel like digging into the IETF specifications
-# What is a JSON schema?
+# What's a JSON schema?
[JSON Schema](http://json-schema.org/) is a proposed Internet draft defining a JSON media type (application/schema+json) with the following goals:
* Validation - You can use JSON Schema to validate your JSON data.
* Documentation - You can extract documentation information from a JSON Schema, match this documentation to your data, and use that information for user interaction.
* Hyperlinking - You can pair your JSON data with the defining JSON Schema to build hyperlinks into parts of that JSON data.
+
_jsonly_ supports most of [JSON Schema Draft 3](http://tools.ietf.org/html/draft-zyp-json-schema-03), without the hyperlinking part.
## Example
@@ -20,7 +28,6 @@ _jsonly_ supports most of [JSON Schema Draft 3](http://tools.ietf.org/html/draft
properties: {
query: {
type: 'string',
- description: 'Query string',
maxLength: 32,
required: true
},
@@ -32,15 +39,94 @@ _jsonly_ supports most of [JSON Schema Draft 3](http://tools.ietf.org/html/draft
}
};
- output = jsonly(input, schema);
- if (output instanceof Error) {
- return res.send(400, output.message); // 400 Bad Request
+ try {
+ input = jsonly(input, schema);
+ } catch(err) {
+ return res.send(400, err.message); // 400 Bad Request
}
## Installation
$ npm install jsonly
+## Usage
+
+_jsonly_ receives an object and a schema.
+Its output is either the (possibly modified) object, or the first encountered error.
+
+### Errors
+
+The error message is user-friendly and detailed.
+For example, 'Property 'user.password' length is 3 when it should be at least 6'.
+Ready to be wrapped in a 400 Bad Request response!
+
+_jsonly_ throws the following errors:
+* _TypeError_ if object/property is missing or is the wrong type
+* _RangeError_ if object value is outside of its valid range
+* _SyntaxError_ if schema syntax is invalid
+
+### Synchronous/Asynchronous
+
+_jsonly_ may be called synchronously, as in the example above, with two parameters.
+It then returns the object or throws an error.
+
+_jsonly_ may also be called asynchronously by providing a 3rd parameter - a callback function.
+The callback function gets two arguments: error and result.
+
+## Hello schema
+
+A _schema_ is defined as a JavaScript object containing various _attributes_.
+
+Let's start by analyzing the schema given in the example above.
+* The top type is an object (as opposed to an array)
+* It should have a property named _query_, which should be a string of up to 32 characters
+* It may optionaly have a property named _maxResults_, which should be an integer with a maximum value of 20
+* If _maxResults_ is missing, it will be generated with the value 10
+
+## Attributes
+
+Below are all the supported attributes.
+
+### type
+
+Defines the expected type of the object or property. Simple types: string, number, integer, boolean, object, array, null, any.
+
+The default is 'any'.
+The top level type must be either 'object' or 'array'.
+
+The _type_ may alternatively be an array of simple types or schemas. In this case the object should be one of the types in the array.
+For example, if _type_ is ['string', 'null'] then the object may be either a string or null.
+
+### required
+
+(array)
+items
+minItems
+maxItems
+uniqueItems
+
+(object)
+properties
+patternProperties
+additionalProperties
+dependencies
+
+(number)
+minimum
+exclusiveMinimum
+maximum
+exclusiveMaximum
+divisibleBy
+(string)
+minLength
+maxLength
+pattern
+(item)
+format
+default
+(any)
+enum
+disallow
View
@@ -28,24 +28,34 @@ var schemaInappropriateType = {
vows.describe('Sync-Async').addBatch({
'when calling synchronously and expecting no error': {
topic: function () {
+ try {
+ var result = jsonly(emptyObject, schemaEmptyObject);
+ this.callback(null, result);
+ } catch(err) {
+ this.callback(err);
+ }
var result = jsonly(emptyObject, schemaEmptyObject);
- this.callback(null, result);
},
'we get back the object': function (err, result) {
+ should.not.exist(err);
should.exist(result);
- result.should.not.be.an.instanceof(Error);
result.should.eql(emptyObject);
}
}
}).addBatch({
'when calling synchronously and expecting an error': {
topic: function () {
- var result = jsonly(emptyObject, schemaInvalidType);
- this.callback(null, result);
+ try {
+ var result = jsonly(emptyObject, schemaInvalidType);
+ this.callback(null, result);
+ } catch(err) {
+ this.callback(err);
+ }
},
'we get the error': function (err, result) {
- should.exist(result);
- result.should.be.an.instanceof(SyntaxError);
+ should.exist(err);
+ should.not.exist(result);
+ err.should.be.an.instanceof(SyntaxError);
}
}
}).addBatch({
@@ -67,6 +77,7 @@ vows.describe('Sync-Async').addBatch({
'we get the error': function (err, result) {
should.exist(err);
should.not.exist(result);
+ err.should.be.an.instanceof(SyntaxError);
}
}
}).export(module);

0 comments on commit ecce0de

Please sign in to comment.