From cb4db59b1db66f5107a834b236ad461e04e3e6cb Mon Sep 17 00:00:00 2001 From: Alex Korzhikov Date: Mon, 9 Oct 2017 17:54:48 +0200 Subject: [PATCH] docs(site): Add index documentation page #48 --- README.md | 124 ++++++++++++++---------------------------- docs/index.md | 18 ++++++ docs/release-notes.md | 63 +++++++++++++++++++++ docs/todo.md | 64 ++++++++++++++++++++++ 4 files changed, 186 insertions(+), 83 deletions(-) create mode 100644 docs/index.md create mode 100644 docs/release-notes.md create mode 100644 docs/todo.md diff --git a/README.md b/README.md index 154c63b..e3fc320 100644 --- a/README.md +++ b/README.md @@ -3,26 +3,18 @@ # djv -Dynamic JSON Schema Validator +Dynamic JSON-Schema Validator -Current package supports **JSON Schema v6 and v4**. It contains utils to validate objects against schemas. +Current package supports **JSON-Schema v6 and v4**. It contains utils to validate objects against schemas. This is a part of **djv** packages aimed to work with json-schema. - [djv](https://github.com/korzio/djv) validate object against schemas - [djvi](https://github.com/korzio/djvi) instantiate objects by schema definition - [jvu](https://github.com/korzio/jvu) utilities for declarative, FP usage +- [@djv/draft-04](https://github.com/korzio/@djv/draft-04) TODO -Any contributions are welcome. Check [contribution guide](./CONTRIBUTING.md). - -**New!!!** - -Since version *1.2.0* `djv` package supports `draft-06`. -The default version is still *draft-04* for the backward compatibility and due to the semantic versioning. -For `draft-06` use a *version* option in [constructor](#constructor) arguments. - -```javascript -const env = new djv({ version: 'draft-06' }); -``` +Any contributions are welcome. Check the [contribution guide](./CONTRIBUTING.md). +Since version **1.2.0** *djv* package supports `draft-06`. Version **2.0.0** makes `draft-06` the default schema version. To use other versions check the [environment section](#environment). ## Table of contents @@ -33,7 +25,6 @@ const env = new djv({ version: 'draft-06' }); * [API](#api) * [Environment](#environment) * [addSchema](#addSchema) - * [addSchema](#addSchema) * [validate](#validate) * [removeSchema](#removeSchema) * [resolve](#resolve) @@ -41,6 +32,7 @@ const env = new djv({ version: 'draft-06' }); * [import](#import) * [addFormat](#addFormat) * [setErrorHandler](#errorHandler) + * [useVersion](#useVersion) * [Tests](#tests) * [References](#references) @@ -78,7 +70,7 @@ const jsonSchema = { } }; -// Use `addSchema` to add json schema +// Use `addSchema` to add json-schema env.addSchema('test', jsonSchema); env.validate('test#/common', { type: 'common' }); // => undefined @@ -91,17 +83,24 @@ env.validate('test#/common', { type: 'custom' }); ### Environment -To instantiate `djv` environment +To instantiate *djv* environment ```javascript const djv = require('djv'); const env = djv({ - version: 'draft-06', // use json-schema draft-06 + version: 'draft-04', // use json-schema draft-06 formats: { /*...*/ }, // custom formats @see #addFormat errorHandler: () => { /*...*/ }, // custom error handler, @see #setErrorHandler }); ``` +To use a previous version of JSON-Schema draft, use a [`draft-04` plugin](https://www.npmjs.com/package/@korzio/djv-draft-04), specified in [*optionalDependencies*](https://docs.npmjs.com/files/package.json#optionaldependencies) of *djv* package. + +```javascript +const env = new djv({ version: 'draft-04' }); +``` + + ### addSchema(name: string, schema: object?) -> resolved: object Add a schema to a current djv environment, @@ -208,79 +207,38 @@ djv({ When a custom error handler is used, the template body function adds a `error` variable inside a generated validator, which can be used to put error information. `errorType` is always passed to error handler function. Some validate utilities put extra argument, like f.e. currently processed property value. Inside the handler context is a templater instance, which contains `this.schema`, `this.data` paths arrays to identify validator position. @see test/index/setErrorHandler for more examples +### useVersion(version: string, configure: function) -## Tests +To customize environment provide a `configure` function which will update configuration for *djv* instance. +```javascript +env.useVersion('draft-04') +// or +env.useVersion('custom', configure) ``` -npm test -``` - -## References - -* [JSON-Schema Specification](http://json-schema.org/) -* [JSON Schema Benchmark](https://github.com/ebdrup/json-schema-benchmark) - - +* [JSON-Schema Specification](http://json-schema.org/) +* [JSON-Schema Benchmark](https://github.com/ebdrup/json-schema-benchmark) diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..44f239b --- /dev/null +++ b/docs/index.md @@ -0,0 +1,18 @@ +# DJV Documents + +Dynamic JSON-Schema Validator documents. + +This document contains links to documentation pages. + +## General Information + +* [Readme](/README.md) - How to use DJV +* [Release Notes](/docs/release-notes.md) - Manually created release notes +* [Changelog](/CHANGELOG.md) - An auto-generated changelog from commits messages +* [Contributing](/CONTRIBUTING.md) - Welcome +* [License](/LICENSE) - MIT + +## Technical Documentation + +* [State](/docs/state.md) - The document describes how the state is implemented in *djv* library, explains how schemas are resolved. +* [Const](/docs/const.md) - A small note on how `const` keyword was implemented. diff --git a/docs/release-notes.md b/docs/release-notes.md new file mode 100644 index 0000000..1fe18e6 --- /dev/null +++ b/docs/release-notes.md @@ -0,0 +1,63 @@ +# Release Notes + +This document contains all notes about the past djv releases. +Announcements are also sent to [the gitter channel](https://gitter.im/korzio/djv). + +[![Join the chat at https://gitter.im/korzio/djv](https://badges.gitter.im/korzio/djv.svg)] + +## Table of contents + +* [Release Notes](#title) +* [Table of contents](#content) +* [2.0.0](#2.0.0) +* [1.2.0](#1.2.0) - 2017-09-27 +* [1.2.0](#1.1.1) - 2017-07-20 +* [1.0.0](#1.0.0) - 2017-06-17 + +## 2.0.0 + +Supports **draft-06** by default. + +All *draft-04* specific code is removed from the codebase. Within the release a separate library [is published](https://www.npmjs.com/package/@korzio/djv-draft-04) to support *draft-04*. It is installed by default as an [optional dependency](https://docs.npmjs.com/files/package.json#optionaldependencies) for *djv* package. + +To specify *draft-04* usage instantiate + +```javascript +const env = djv({ + version: 'draft-04', +}); +// or +djv.useVersion('draft-04') +``` + +**!Important** Applying the *draft-04* configuration will affect all *djv* instances in an application. Check the [documentation](/README.md#useVersion). + +## 1.2.0 (2017-09-27) + +A [MR](https://github.com/korzio/djv/pull/50) which replaces the previous one and contains 2 big features: +1. State refactoring - now tests are passing, the algorithm is redesigned (however there are still things to do in future) +2. Draft-06 implemented + +Supports *draft-04* by default and can be configured to validate instances against *draft-06* specification. + +## 1.1.1 + +[The release story](https://github.com/korzio/djv/issues/35) +[The changelog](https://github.com/korzio/djv/blob/master/CHANGELOG.md#111-2017-07-20) + +In short - this release was about fixing [the major part of bugs](https://github.com/korzio/djv/issues/35#issuecomment-316698036) of updated json schema benchmark. +The most of the work was done related to state management. I've tried to refactor that functionality. However the most tests regarding references are passing , there are still a few (5) of them failing. Next release will be about v5/v6 support, and the one after will be state refactoring again - I hope to rewrite it in a "wise" way, with algorithm description, tests analytics, etc. +The other part was in updating the documentation, so I've created a [document](https://github.com/korzio/djv/blob/master/CONTRIBUTING.md) with a few guides how-to debug and release the package. It will be updated in future. + +Great thanks for all comments and participation. + +## 1.1.0 + +The release contains +- 2 features of a custom error format and adding formatters into environment +- a big refactoring of utils and cleaning the structure +- a few bug fixes (with a huge improvement of pending internals schemas) + +Here is the log for release - https://github.com/korzio/djv/issues/26 +Changelog - https://github.com/korzio/djv/blob/master/CHANGELOG.md +Great thanks for all comments and participants. \ No newline at end of file diff --git a/docs/todo.md b/docs/todo.md new file mode 100644 index 0000000..4c66216 --- /dev/null +++ b/docs/todo.md @@ -0,0 +1,64 @@ + \ No newline at end of file