feat: 초기 프로젝트 설정 및 룰.md 파일 추가
This commit is contained in:
468
api.hyungi.net/node_modules/tv4/README.md
generated
vendored
Normal file
468
api.hyungi.net/node_modules/tv4/README.md
generated
vendored
Normal file
@@ -0,0 +1,468 @@
|
||||
# Tiny Validator (for v4 JSON Schema)
|
||||
|
||||
[](http://travis-ci.org/geraintluff/tv4) [](https://gemnasium.com/geraintluff/tv4) [](http://badge.fury.io/js/tv4)
|
||||
|
||||
Use [json-schema](http://json-schema.org/) [draft v4](http://json-schema.org/latest/json-schema-core.html) to validate simple values and complex objects using a rich [validation vocabulary](http://json-schema.org/latest/json-schema-validation.html) ([examples](http://json-schema.org/examples.html)).
|
||||
|
||||
There is support for `$ref` with JSON Pointer fragment paths (```other-schema.json#/properties/myKey```).
|
||||
|
||||
## Usage 1: Simple validation
|
||||
|
||||
```javascript
|
||||
var valid = tv4.validate(data, schema);
|
||||
```
|
||||
|
||||
If validation returns ```false```, then an explanation of why validation failed can be found in ```tv4.error```.
|
||||
|
||||
The error object will look something like:
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "Invalid type: string",
|
||||
"dataPath": "/intKey",
|
||||
"schemaPath": "/properties/intKey/type"
|
||||
}
|
||||
```
|
||||
|
||||
The `"code"` property will refer to one of the values in `tv4.errorCodes` - in this case, `tv4.errorCodes.INVALID_TYPE`.
|
||||
|
||||
To enable external schema to be referenced, you use:
|
||||
```javascript
|
||||
tv4.addSchema(url, schema);
|
||||
```
|
||||
|
||||
If schemas are referenced (```$ref```) but not known, then validation will return ```true``` and the missing schema(s) will be listed in ```tv4.missing```. For more info see the API documentation below.
|
||||
|
||||
## Usage 2: Multi-threaded validation
|
||||
|
||||
Storing the error and missing schemas does not work well in multi-threaded environments, so there is an alternative syntax:
|
||||
|
||||
```javascript
|
||||
var result = tv4.validateResult(data, schema);
|
||||
```
|
||||
|
||||
The result will look something like:
|
||||
```json
|
||||
{
|
||||
"valid": false,
|
||||
"error": {...},
|
||||
"missing": [...]
|
||||
}
|
||||
```
|
||||
|
||||
## Usage 3: Multiple errors
|
||||
|
||||
Normally, `tv4` stops when it encounters the first validation error. However, you can collect an array of validation errors using:
|
||||
|
||||
```javascript
|
||||
var result = tv4.validateMultiple(data, schema);
|
||||
```
|
||||
|
||||
The result will look something like:
|
||||
```json
|
||||
{
|
||||
"valid": false,
|
||||
"errors": [
|
||||
{...},
|
||||
...
|
||||
],
|
||||
"missing": [...]
|
||||
}
|
||||
```
|
||||
|
||||
## Asynchronous validation
|
||||
|
||||
Support for asynchronous validation (where missing schemas are fetched) can be added by including an extra JavaScript file. Currently, the only version requires jQuery (`tv4.async-jquery.js`), but the code is very short and should be fairly easy to modify for other libraries (such as MooTools).
|
||||
|
||||
Usage:
|
||||
|
||||
```javascript
|
||||
tv4.validate(data, schema, function (isValid, validationError) { ... });
|
||||
```
|
||||
|
||||
`validationError` is simply taken from `tv4.error`.
|
||||
|
||||
## Cyclical JavaScript objects
|
||||
|
||||
While they don't occur in proper JSON, JavaScript does support self-referencing objects. Any of the above calls support an optional third argument: `checkRecursive`. If true, tv4 will handle self-referencing objects properly - this slows down validation slightly, but that's better than a hanging script.
|
||||
|
||||
Consider this data, notice how both `a` and `b` refer to each other:
|
||||
|
||||
```javascript
|
||||
var a = {};
|
||||
var b = { a: a };
|
||||
a.b = b;
|
||||
var aSchema = { properties: { b: { $ref: 'bSchema' }}};
|
||||
var bSchema = { properties: { a: { $ref: 'aSchema' }}};
|
||||
tv4.addSchema('aSchema', aSchema);
|
||||
tv4.addSchema('bSchema', bSchema);
|
||||
```
|
||||
|
||||
If the `checkRecursive` argument were missing, this would throw a "too much recursion" error.
|
||||
|
||||
To enable support for this, pass `true` as additional argument to any of the regular validation methods:
|
||||
|
||||
```javascript
|
||||
tv4.validate(a, aSchema, true);
|
||||
tv4.validateResult(data, aSchema, true);
|
||||
tv4.validateMultiple(data, aSchema, true);
|
||||
```
|
||||
|
||||
## The `banUnknownProperties` flag
|
||||
|
||||
Sometimes, it is desirable to flag all unknown properties as an error. This is especially useful during development, to catch typos and the like, even when extra custom-defined properties are allowed.
|
||||
|
||||
As such, tv4 implements ["ban unknown properties" mode](https://github.com/json-schema/json-schema/wiki/ban-unknown-properties-mode-\(v5-proposal\)), enabled by a fourth-argument flag:
|
||||
|
||||
```javascript
|
||||
tv4.validate(data, schema, checkRecursive, true);
|
||||
tv4.validateResult(data, schema, checkRecursive, true);
|
||||
tv4.validateMultiple(data, schema, checkRecursive, true);
|
||||
```
|
||||
|
||||
## API
|
||||
|
||||
There are additional api commands available for more complex use-cases:
|
||||
|
||||
##### addSchema(uri, schema)
|
||||
Pre-register a schema for reference by other schema and synchronous validation.
|
||||
|
||||
````js
|
||||
tv4.addSchema('http://example.com/schema', { ... });
|
||||
````
|
||||
|
||||
* `uri` the uri to identify this schema.
|
||||
* `schema` the schema object.
|
||||
|
||||
Schemas that have their `id` property set can be added directly.
|
||||
|
||||
````js
|
||||
tv4.addSchema({ ... });
|
||||
````
|
||||
|
||||
##### getSchema(uri)
|
||||
|
||||
Return a schema from the cache.
|
||||
|
||||
* `uri` the uri of the schema (may contain a `#` fragment)
|
||||
|
||||
````js
|
||||
var schema = tv4.getSchema('http://example.com/schema');
|
||||
````
|
||||
|
||||
##### getSchemaMap()
|
||||
|
||||
Return a shallow copy of the schema cache, mapping schema document URIs to schema objects.
|
||||
|
||||
````
|
||||
var map = tv4.getSchemaMap();
|
||||
|
||||
var schema = map[uri];
|
||||
````
|
||||
|
||||
##### getSchemaUris(filter)
|
||||
|
||||
Return an Array with known schema document URIs.
|
||||
|
||||
* `filter` optional RegExp to filter URIs
|
||||
|
||||
````
|
||||
var arr = tv4.getSchemaUris();
|
||||
|
||||
// optional filter using a RegExp
|
||||
var arr = tv4.getSchemaUris(/^https?://example.com/);
|
||||
````
|
||||
|
||||
##### getMissingUris(filter)
|
||||
|
||||
Return an Array with schema document URIs that are used as `$ref` in known schemas but which currently have no associated schema data.
|
||||
|
||||
Use this in combination with `tv4.addSchema(uri, schema)` to preload the cache for complete synchronous validation with.
|
||||
|
||||
* `filter` optional RegExp to filter URIs
|
||||
|
||||
````
|
||||
var arr = tv4.getMissingUris();
|
||||
|
||||
// optional filter using a RegExp
|
||||
var arr = tv4.getMissingUris(/^https?://example.com/);
|
||||
````
|
||||
|
||||
##### dropSchemas()
|
||||
|
||||
Drop all known schema document URIs from the cache.
|
||||
|
||||
````
|
||||
tv4.dropSchemas();
|
||||
````
|
||||
|
||||
##### freshApi()
|
||||
|
||||
Return a new tv4 instance with no shared state.
|
||||
|
||||
````
|
||||
var otherTV4 = tv4.freshApi();
|
||||
````
|
||||
|
||||
##### reset()
|
||||
|
||||
Manually reset validation status from the simple `tv4.validate(data, schema)`. Although tv4 will self reset on each validation there are some implementation scenarios where this is useful.
|
||||
|
||||
````
|
||||
tv4.reset();
|
||||
````
|
||||
|
||||
##### setErrorReporter(reporter)
|
||||
|
||||
Sets a custom error reporter. This is a function that accepts three arguments, and returns an error message (string):
|
||||
|
||||
```
|
||||
tv4.setErrorReporter(function (error, data, schema) {
|
||||
return "Error code: " + error.code;
|
||||
});
|
||||
```
|
||||
|
||||
The `error` object already has everything aside from the `.message` property filled in (so you can use `error.params`, `error.dataPath`, `error.schemaPath` etc.).
|
||||
|
||||
If nothing is returned (or the empty string), then it falls back to the default error reporter. To remove a custom error reporter, call `tv4.setErrorReporter(null)`.
|
||||
|
||||
##### language(code)
|
||||
|
||||
Sets the language used by the default error reporter.
|
||||
|
||||
* `code` is a language code, like `'en'` or `'en-gb'`
|
||||
|
||||
````
|
||||
tv4.language('en-gb');
|
||||
````
|
||||
|
||||
If you specify a multi-level language code (e.g. `fr-CH`), then it will fall back to the generic version (`fr`) if needed.
|
||||
|
||||
##### addLanguage(code, map)
|
||||
|
||||
Add a new template-based language map for the default error reporter (used by `tv4.language(code)`)
|
||||
|
||||
* `code` is new language code
|
||||
* `map` is an object mapping error IDs or constant names (e.g. `103` or `"NUMBER_MAXIMUM"`) to language strings.
|
||||
|
||||
````
|
||||
tv4.addLanguage('fr', { ... });
|
||||
|
||||
// select for use
|
||||
tv4.language('fr')
|
||||
````
|
||||
|
||||
If you register a multi-level language code (e.g. `fr-FR`), then it will also be registered for plain `fr` if that does not already exist.
|
||||
|
||||
##### addFormat(format, validationFunction)
|
||||
|
||||
Add a custom format validator. (There are no built-in format validators. Several common ones can be found [here](https://github.com/ikr/tv4-formats) though)
|
||||
|
||||
* `format` is a string, corresponding to the `"format"` value in schemas.
|
||||
* `validationFunction` is a function that either returns:
|
||||
* `null` (meaning no error)
|
||||
* an error string (explaining the reason for failure)
|
||||
|
||||
````
|
||||
tv4.addFormat('decimal-digits', function (data, schema) {
|
||||
if (typeof data === 'string' && !/^[0-9]+$/.test(data)) {
|
||||
return null;
|
||||
}
|
||||
return "must be string of decimal digits";
|
||||
});
|
||||
````
|
||||
|
||||
Alternatively, multiple formats can be added at the same time using an object:
|
||||
````
|
||||
tv4.addFormat({
|
||||
'my-format': function () {...},
|
||||
'other-format': function () {...}
|
||||
});
|
||||
````
|
||||
|
||||
##### defineKeyword(keyword, validationFunction)
|
||||
|
||||
Add a custom keyword validator.
|
||||
|
||||
* `keyword` is a string, corresponding to a schema keyword
|
||||
* `validationFunction` is a function that either returns:
|
||||
* `null` (meaning no error)
|
||||
* an error string (explaining the reason for failure)
|
||||
* an error object (containing some of: `code`/`message`/`dataPath`/`schemaPath`)
|
||||
|
||||
````
|
||||
tv4.defineKeyword('my-custom-keyword', function (data, value, schema) {
|
||||
if (simpleFailure()) {
|
||||
return "Failure";
|
||||
} else if (detailedFailure()) {
|
||||
return {code: tv4.errorCodes.MY_CUSTOM_CODE, message: {param1: 'a', param2: 'b'}};
|
||||
} else {
|
||||
return null;
|
||||
}
|
||||
});
|
||||
````
|
||||
|
||||
`schema` is the schema upon which the keyword is defined. In the above example, `value === schema['my-custom-keyword']`.
|
||||
|
||||
If an object is returned from the custom validator, and its `message` is a string, then that is used as the message result. If `message` is an object, then that is used to populate the (localisable) error template.
|
||||
|
||||
##### defineError(codeName, codeNumber, defaultMessage)
|
||||
|
||||
Defines a custom error code.
|
||||
|
||||
* `codeName` is a string, all-caps underscore separated, e.g. `"MY_CUSTOM_ERROR"`
|
||||
* `codeNumber` is an integer > 10000, which will be stored in `tv4.errorCodes` (e.g. `tv4.errorCodes.MY_CUSTOM_ERROR`)
|
||||
* `defaultMessage` is an error message template to use (assuming translations have not been provided for this code)
|
||||
|
||||
An example of `defaultMessage` might be: `"Incorrect moon (expected {expected}, got {actual}"`). This is filled out if a custom keyword returns a object `message` (see above). Translations will be used, if associated with the correct code name/number.
|
||||
|
||||
## Demos
|
||||
|
||||
### Basic usage
|
||||
<div class="content inline-demo" markdown="1" data-demo="demo1">
|
||||
<pre class="code" id="demo1">
|
||||
var schema = {
|
||||
"items": {
|
||||
"type": "boolean"
|
||||
}
|
||||
};
|
||||
var data1 = [true, false];
|
||||
var data2 = [true, 123];
|
||||
|
||||
alert("data 1: " + tv4.validate(data1, schema)); // true
|
||||
alert("data 2: " + tv4.validate(data2, schema)); // false
|
||||
alert("data 2 error: " + JSON.stringify(tv4.error, null, 4));
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
### Use of <code>$ref</code>
|
||||
<div class="content inline-demo" markdown="1" data-demo="demo2">
|
||||
<pre class="code" id="demo2">
|
||||
var schema = {
|
||||
"type": "array",
|
||||
"items": {"$ref": "#"}
|
||||
};
|
||||
var data1 = [[], [[]]];
|
||||
var data2 = [[], [true, []]];
|
||||
|
||||
alert("data 1: " + tv4.validate(data1, schema)); // true
|
||||
alert("data 2: " + tv4.validate(data2, schema)); // false
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
### Missing schema
|
||||
<div class="content inline-demo" markdown="1" data-demo="demo3">
|
||||
<pre class="code" id="demo3">
|
||||
var schema = {
|
||||
"type": "array",
|
||||
"items": {"$ref": "http://example.com/schema" }
|
||||
};
|
||||
var data = [1, 2, 3];
|
||||
|
||||
alert("Valid: " + tv4.validate(data, schema)); // true
|
||||
alert("Missing schemas: " + JSON.stringify(tv4.missing));
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
### Referencing remote schema
|
||||
<div class="content inline-demo" markdown="1" data-demo="demo4">
|
||||
<pre class="code" id="demo4">
|
||||
tv4.addSchema("http://example.com/schema", {
|
||||
"definitions": {
|
||||
"arrayItem": {"type": "boolean"}
|
||||
}
|
||||
});
|
||||
var schema = {
|
||||
"type": "array",
|
||||
"items": {"$ref": "http://example.com/schema#/definitions/arrayItem" }
|
||||
};
|
||||
var data1 = [true, false, true];
|
||||
var data2 = [1, 2, 3];
|
||||
|
||||
alert("data 1: " + tv4.validate(data1, schema)); // true
|
||||
alert("data 2: " + tv4.validate(data2, schema)); // false
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
## Supported platforms
|
||||
|
||||
* Node.js
|
||||
* All modern browsers
|
||||
* IE >= 7
|
||||
|
||||
## Installation
|
||||
|
||||
You can manually download [`tv4.js`](https://raw.github.com/geraintluff/tv4/master/tv4.js) or the minified [`tv4.min.js`](https://raw.github.com/geraintluff/tv4/master/tv4.min.js) and include it in your html to create the global `tv4` variable.
|
||||
|
||||
Alternately use it as a CommonJS module:
|
||||
|
||||
````js
|
||||
var tv4 = require('tv4');
|
||||
````
|
||||
|
||||
or as an AMD module (e.g. with requirejs):
|
||||
|
||||
```js
|
||||
require('tv4', function(tv4){
|
||||
//use tv4 here
|
||||
});
|
||||
```
|
||||
|
||||
There is a command-line tool that wraps this library: [tv4-cmd](https://www.npmjs.com/package/tv4-cmd).
|
||||
|
||||
#### npm
|
||||
|
||||
````
|
||||
$ npm install tv4
|
||||
````
|
||||
|
||||
#### bower
|
||||
|
||||
````
|
||||
$ bower install tv4
|
||||
````
|
||||
|
||||
#### component.io
|
||||
|
||||
````
|
||||
$ component install geraintluff/tv4
|
||||
````
|
||||
|
||||
## Build and test
|
||||
|
||||
You can rebuild and run the node and browser tests using node.js and [grunt](http://http://gruntjs.com/):
|
||||
|
||||
Make sure you have the global grunt cli command:
|
||||
````
|
||||
$ npm install grunt-cli -g
|
||||
````
|
||||
|
||||
Clone the git repos, open a shell in the root folder and install the development dependencies:
|
||||
|
||||
````
|
||||
$ npm install
|
||||
````
|
||||
|
||||
Rebuild and run the tests:
|
||||
````
|
||||
$ grunt
|
||||
````
|
||||
|
||||
It will run a build and display one Spec-style report for the node.js and two Dot-style reports for both the plain and minified browser tests (via phantomJS). You can also use your own browser to manually run the suites by opening [`test/index.html`](http://geraintluff.github.io/tv4/test/index.html) and [`test/index-min.html`](http://geraintluff.github.io/tv4/test/index-min.html).
|
||||
|
||||
## Contributing
|
||||
|
||||
Pull-requests for fixes and expansions are welcome. Edit the partial files in `/source` and add your tests in a suitable suite or folder under `/test/tests` and run `grunt` to rebuild and run the test suite. Try to maintain an idiomatic coding style and add tests for any new features. It is recommend to discuss big changes in an Issue.
|
||||
|
||||
Do you speak another language? `tv4` needs internationalisation - please contribute language files to `/lang`!
|
||||
|
||||
## Packages using tv4
|
||||
|
||||
* [chai-json-schema](http://chaijs.com/plugins/chai-json-schema) is a [Chai Assertion Library](http://chaijs.com) plugin to assert values against json-schema.
|
||||
* [grunt-tv4](http://www.github.com/Bartvds/grunt-tv4) is a plugin for [Grunt](http://http://gruntjs.com/) that uses tv4 to bulk validate json files.
|
||||
|
||||
## License
|
||||
|
||||
The code is available as "public domain", meaning that it is completely free to use, without any restrictions at all. Read the full license [here](http://geraintluff.github.com/tv4/LICENSE.txt).
|
||||
|
||||
It's also available under an [MIT license](http://jsonary.com/LICENSE.txt).
|
||||
Reference in New Issue
Block a user