node-libxml-xsd

XSD validation for node.js using libxml

This fork adds support for passing libxml parser options to parse() and parseFile().

Installation

npm install libxml-xsd

On windows there are several prerequisites that need to be met before an install will work. Windows-Build-Tools is a great helper module for this task.

npm install --global --production windows-build-tools
npm install libxml-xsd

Basic usage

var xsd = require('libxml-xsd');

xsd.parseFile(schemaPath, function(err, schema){
  schema.validate(documentString, function(err, validationErrors){
    // err contains any technical error
    // validationError is an array, null if the validation is ok
  });
});

Libxmljs integration

Node-libxml-xsd depends on libxmljs that bundles libxml.

The libxmljs module required by node-libxml-xsd is exposed as require('libxml-xsd').libxmljs. This prevents depending on libxmljs twice which is not optimal and source of weird bugs.

It is possible to work with libxmljs documents instead of strings as inputs to the parse() and validate() functions.

Imports and includes

XSD includes are supported. By default, paths are relative to the XSD file when using parseFile() and the execution directory when using parse(). You can change where paths are relative to by setting the baseUrl option.

Includes are resolved when parsing the schema. Therefore the parsing task becomes IO bound, which is why you should not use synchronous parsing when you expect some includes.

Sync or async

The same parse() and validate() functions can be used in synchronous mode simply by removing the callback parameter. In this case if a technical error occurs it will be thrown and validation errors will be returned.

var xsd = require('libxml-xsd');

var schema = xsd.parse(schemaString);

var validationErrors = schema.validate(documentString);

The asynchronous functions use the libuv work queue to provide parallelized computation in node.js worker threads. This makes it non-blocking for the main event loop of node.js.

Note that libxmljs parsing doesn't use the work queue, so only a part of the process is actually parallelized.

The tasks being mostly CPU bound and very fast it is not a big problem to use synchronous mode. But remember that if you use some includes the parsing task becomes IO bound.

Environment compatibility

For now 64bits linux and 32bits windows are confirmed. Other environments are probably ok, but not checked. Please report an issue if you encounter some difficulties.

Node-libxml-xsd depends on node-gyp, you will need to meet its requirements. This can be a bit painful mostly for windows users. The node-gyp version bundled in your npm will have to be greater than 0.13.0, so you might have to follow these instructions to upgrade. There is no system dependancy otherwise as libxml is bundled by libxmljs.

API Reference

libxml-xsd

Node.js bindings for XSD validation from libxml

• libxml-xsd
  • static
    • .libxmljs
    • .parse(source, [options], [callback]) ⇒ Schema
    • .parseFile(sourcePath, [options], callback)
  • inner
    • ~Schema
      • new Schema(schemaDoc, schemaObj)
      • .validate(source, [callback]) ⇒ string | Document
      • .validateFile(sourcePath, callback)
    • ~parseCallback : function
    • ~parseFileCallback : function

libxml-xsd.libxmljs

The libxmljs module. Prevents the need for a user's code to require it a second time. Also prevent weird bugs.

Kind: static property of libxml-xsd

libxml-xsd.parse(source, [options], [callback]) ⇒ Schema

Parse a XSD schema

If no callback is given the function will run synchronously and return the result or throw an error.

Kind: static method of libxml-xsd
Returns: Schema - Only if no callback is given.

| Param | Type | Description | | --- | --- | --- | | source | string | Document | The content of the schema as a string or a libxmljs document | | [options] | ParserOptions | libxmljs parser options | | [callback] | parseCallback | The callback that handles the response. Expects err and Schema object. |

libxml-xsd.parseFile(sourcePath, [options], callback)

Parse a XSD schema

Kind: static method of libxml-xsd

| Param | Type | Description | | --- | --- | --- | | sourcePath | stringPath | The path of the file | | [options] | ParserOptions | libxmljs parser options | | callback | parseFileCallback | The callback that handles the response. Expects err and Schema object. |

libxml-xsd~Schema

Kind: inner class of libxml-xsd

• ~Schema
  • new Schema(schemaDoc, schemaObj)
  • .validate(source, [callback]) ⇒ string | Document
  • .validateFile(sourcePath, callback)

new Schema(schemaDoc, schemaObj)

A compiled schema. Do not call this constructor, instead use parse or parseFile.

store both the source document and the parsed schema if we don't store the schema doc it will be deleted by garbage collector and it will result in segfaults.

| Param | Type | Description | | --- | --- | --- | | schemaDoc | Document | XML document source of the schema | | schemaObj | Document | Simple wrapper of a XSD schema |

schema.validate(source, [callback]) ⇒ string | Document

Validate a XML document over a schema

If no callback is given the function will run synchronously and return the result or throw an error.

Kind: instance method of Schema
Returns: string | Document - Only if no callback is given. An array of validation errors, null if none.

| Param | Type | Description | | --- | --- | --- | | source | string | Document | The XML content to validate with the schema, to be given as a string or a libxmljs document | | [callback] | validateCallback | The callback that handles the response. Expects err and an array of validation errors, null if none. |

schema.validateFile(sourcePath, callback)

Apply a schema to a XML file

Kind: instance method of Schema

| Param | Type | Description | | --- | --- | --- | | sourcePath | string | The path of the file to read | | callback | validateFileCallback | The callback that handles the response. Expects err and an array of validation errors null if none. |

libxml-xsd~parseCallback : function

Callback to the parse function

Kind: inner typedef of libxml-xsd

| Param | Type | | --- | --- | | [err] | error | | [schema] | Schema |

libxml-xsd~parseFileCallback : function

Callback to the parseFile function

Kind: inner typedef of libxml-xsd

| Param | Type | | --- | --- | | [err] | error | | [schema] | Schema |

documented by jsdoc-to-markdown.