Validation Documentation is Massively Incorrect

rbutera commented 9 years ago

I really admire and appreciate the effort that is going into this (and the parent) project - it's really going to make my life as a dev easier. Thank you!

However, all the examples of errors (for example: http://www.js-data.io/v1.5.8/docs/js-data-schema) are incorrect / very misleading!

Advice:

the validate and validateSync sections should say something along the lines of: "validateSync and validate return an object with properties matching the schema name. If a rule fails, then the invalid attribute will have an errors property. The errors property is an array of objects returned from the failing rule function."
If you'd like, copy this?:

var schemator = new Schemator();

// example of a custom rule 
schemator.defineRule('isLol', function(value, parameter){ // value will be validated, an optional parameter can be passed
    if(!value || value !== 'lol'){ 
        // validation failed
        return {
            rule: 'isLol', // reference the name of the rule here
            actual: value, // the value that did not pass validation
            expected: 'lol' // the expected value
        };
    } else {
        // validation passed
        return null;
    }
});

schemator.defineSchema('ExampleSchema', {
    foo: { // name of the attribute
        type: 'string', 
        isLol: true
    }
});

var valid = schemator.validateSync('ExampleSchema', {foo: 'lol'});
var invalid = schemator.validateSync('ExampleSchema', {foo: 1234});

console.log(invalid);
// output: 
// {
//     foo: {
//         errors: [
//             {rule: 'string'},
//             {rule: 'isLol', actual: 1234, expected: 'lol'}
//         ]
//     }
// }

Hopefully it will save someone else the headache I went through :(

jmdobry commented 9 years ago

When you say "all the examples of errors" are you including these examples:

I agree the very top example on that page is incorrect. How about I close this issue, and you click the "Suggest Edits" button at the top right of that documentation page, make your changes, and submit. It will show me a diff and then I can merge your changes. That would be great, thanks!

rbutera commented 9 years ago

How about I close this issue, and you click the "Suggest Edits" button at the top right of that documentation page, make your changes, and submit. It will show me a diff and then I can merge your changes. That would be great, thanks!

@jmdobry I'm sorry, but clicking the "suggest edits" button does nothing but return me to the js-data repo

jmdobry commented 9 years ago

Just made the changes myself.

js-data / js-data-schema

Validation Documentation is Massively Incorrect #7