schema-markdown 1.1.5 → 1.2.1

package/README.md

@@ -3,91 +3,105 @@
 [![npm](https://img.shields.io/npm/v/schema-markdown)](https://www.npmjs.com/package/schema-markdown)
 [![GitHub](https://img.shields.io/github/license/craigahobbs/schema-markdown-js)](https://github.com/craigahobbs/schema-markdown-js/blob/main/LICENSE)
 
-**Schema Markdown** is a human-friendly schema definition language and schema validator. Here are
-its features at a glance:
-
-- Schema-validate JSON objects
-- Human-friendly schema definition
-- Validates member value and length contraints
-- Validation *type-massages* string member values
-- Pure JavaScript
+**schema-markdown** is a schema definition and validation library.
 
 
 ## Links
 
-- [Schema Markdown Language Reference](https://craigahobbs.github.io/schema-markdown/schema-markdown.html)
-- [Documentation on GitHub Pages](https://craigahobbs.github.io/schema-markdown-js/)
-- [Package on npm](https://www.npmjs.com/package/schema-markdown)
-- [Source code on GitHub](https://github.com/craigahobbs/schema-markdown-js)
+- [The Schema Markdown Language](https://craigahobbs.github.io/schema-markdown-js/language/)
+- [API Documentation](https://craigahobbs.github.io/schema-markdown-js/)
+- [Source code](https://github.com/craigahobbs/schema-markdown-js)
 
 
-## Usage
+## Define a Schema
 
-To schema-validate an object, first parse its *Schema Markdown* using the
-[SchemaMarkdownParser](https://craigahobbs.github.io/schema-markdown-js/module-lib_parser.SchemaMarkdownParser.html)
-class:
+Schemas are defined using the
+[Schema Markdown](https://craigahobbs.github.io/schema-markdown-js/language/)
+language which is parsed by the
+[parseSchemaMarkdown](https://craigahobbs.github.io/schema-markdown-js/module-lib_parser.html#.parseSchemaMarkdown)
+function. For example:
 
 ``` javascript
-import {SchemaMarkdownParser} from 'schema-markdown/parser.js';
-import {validateType} from 'schema-markdown/schema.js';
-
-const parser = new SchemaMarkdownParser(`\
-# An aggregation function
-enum Aggregation
-    Average
-    Sum
+import {parseSchemaMarkdown} from 'schema-markdown/parser.js';
 
+export const modelTypes = parseSchemaMarkdown(`\
 # An aggregate numerical operation
-struct Operation
+struct Aggregation
+
     # The aggregation function - default is "Sum"
-    optional Aggregation aggregation
+    optional AggregationFunction aggregation
 
-    # The numbers to operate on
+    # The numbers to aggregate on
     int[len > 0] numbers
+
+# An aggregation function
+enum AggregationFunction
+    Average
+    Sum
 `);
 ```
 
-Then, validate an object using the
+
+## Validate using a Schema
+
+To validate an object using the schema, use the
 [validateType](https://craigahobbs.github.io/schema-markdown-js/module-lib_schema.html#.validateType)
-function:
+function. For example:
 
 ``` javascript
-const obj = validateType(parser.types, 'Operation', {
-    'numbers': [1, 2, '3', 4]
-});
+import {validateType} from 'schema-markdown/schema.js';
+
+const obj = validateType(modelTypes, 'Aggregation', {'numbers': [1, 2, '3', 4]});
 console.assert(obj.numbers[2] === 3);
 ```
 
 Notice that the numerical input '3' above is *type-massaged* to the integer 3 by validation.
+
 Validation fails if the object does not match the schema:
 
 ``` javascript
 try {
-    validateType(parser.types, 'Operation', {
-        'numbers': [1, 2, 'asdf', 4]
-    });
+    validateType(modelTypes, 'Aggregation', {'numbers': [1, 2, 'asdf', 4]});
 } catch ({message}) {
     console.assert(message === "Invalid value \"asdf\" (type 'string') for member 'numbers.2', expected type 'int'", message);
 }
 ```
 
-Validation also fails if a member contraint is violated:
+Validation also fails if a member constraint is violated:
 
 ``` javascript
 try {
-    validateType(parser.types, 'Operation', {
-        'numbers': []
-    });
+    validateType(modelTypes, 'Aggregation', {'numbers': []});
 } catch ({message}) {
     console.assert(message === "Invalid value [] (type 'object') for member 'numbers', expected type 'array' [len > 0]", message);
 }
 ```
 
 
+## Document a Schema
+
+To document the schema, download the
+[documentation application](https://github.com/craigahobbs/schema-markdown-doc#the-schema-markdown-documentation-viewer)
+stub and save the type model as JSON:
+
+~~~
+curl -O https://craigahobbs.github.io/schema-markdown-doc/extra/index.html
+node --input-type=module \
+    -e 'import {modelTypes} from "model.js"; console.log(JSON.stringify(modelTypes))' \
+    > model.json
+~~~
+
+To host locally, start a local static web server:
+
+```
+python3 -m http.server
+```
+
+
 ## Development
 
-schema-markdown is developed using [javascript-build](https://github.com/craigahobbs/javascript-build#readme)
-and it was started using [javascript-template](https://github.com/craigahobbs/javascript-template#readme):
+This package is developed using [javascript-build](https://github.com/craigahobbs/javascript-build#readme).
+It was started using [javascript-template](https://github.com/craigahobbs/javascript-template#readme) as follows:
 
 ```
 template-specialize javascript-template/template/ schema-markdown-js/ -k package schema-markdown -k name 'Craig A. Hobbs' -k email 'craigahobbs@gmail.com' -k github 'craigahobbs' -k noapp 1