---
name: basex-validate
description: Validate XML files using BaseX. Supports DTD, XSD, RNG, RNC. Information about Schematron validation.
metadata:
  author: BaseX
  version: "12.2"
  homepage: https://docs.basex.org/main/Validation_Functions
  allowed-tools: Read
---
# XML Validation Functions

This module contains functions to perform validations against DTDs, XML Schema and Relax NG. The documentation further describes how to use Schematron validation with BaseX.
## Conventions

All functions and errors in this module are assigned to the http://basex.org/modules/validate namespace, which is statically bound to the `validate` prefix.

## DTD Validation

Checks whether an XML document validates against a DTD. The input document can be specified as:

*  xs:string, representing a URI (relative URIs will always be resolved against the static base URI of the query),
*  xs:string, representing the resource in its string representation, or
* node(), representing the resource itself.

If no DTD is supplied in a function, the XML document is expected to contain an embedded DTD doctype declaration.
### validate:dtd
	

```xquery
validate:dtd(
  $input  as item(),
  $dtd    as xs:string?  := ()
) as empty-sequence()
```

Validates the XML `$input` document against a `$dtd` and returns an empty sequence or an error.
Errors	
* error	The document cannot be validated against the specified schema.
* init	The validation cannot be started.
not-found	No validator is available.
Examples	

`validate:dtd('doc.xml', 'doc.dtd')`

Validates the document
doc.xml against the specified DTD file doc.dtd.

```xquery
try {
  let $doc := <invalid/>
  let $dtd := '<!ELEMENT root (#PCDATA)>'
  return validate:dtd($doc, $dtd)
} catch validate:error {
  'DTD Validation failed.'
}
```
Validates an invalid document against a DTD, which is specified as string.
## validate:dtd-info

```xquery
validate:dtd-info(
  $input  as item(),
  $dtd    as xs:string?  := ()
) as xs:string*
```

Validates the XML $input document against a $dtd and returns warnings, errors and fatal errors in a string sequence.
Errors	
init	The validation cannot be started.
not-found	No validator is available.
Examples	
```
validate:dtd-info(<invalid/>, '<!ELEMENT root (#PCDATA)>')
```
Returns:
2:11: Element type "invalid" must be declared.

## validate:dtd-report

```xquery
validate:dtd-report(
  $input  as item(),
  $dtd    as xs:string?  := ()
) as element(report)
```
Validates the XML $input document against a $dtd and returns warnings, errors and fatal errors as XML.
Errors	
init	The validation cannot be started.
not-found	No validator is available.
Examples	
```
validate:dtd-report(<invalid/>, '<!ELEMENT root (#PCDATA)>')
```
The result:
```
<report>
  <status>invalid</status>
  <message level="Error" line="2" column="11">
    Element type "invalid" must be declared.</message

</report>
```
# XML Schema Validation

Checks whether an XML document validates against an XML Schema. The input document and the schema can be specified as:

    xs:string, containing the path to the resource,
    xs:string, containing the resource in its string representation, or
    node(), containing the resource itself.

If no schema is given, the input is expected to contain an xsi:(noNamespace)schemaLocation attribute, as defined in W3C XML Schema.

Different XML Schema processors are supported:

    By default, the Java implementation of XML Schema 1.0 is used (it is based on an old version of Apache Xerces).
    The latest version of Xerces2 provides implementations of XML Schema 1.0 and 1.1. The processor will be applied if you download one of the binary distributions and copy the following libraries to the lib/custom directory of the full distribution of BaseX:
        org.eclipse.wst.xml.xpath2.processor_1.2.0.jar
        cupv10k-runtime.jar
        xercesImpl.jar
        xml-apis.jar
    Saxon Enterprise Edition will be used if you download the ZIP release and if you copy saxon9ee.jar and a valid license key to the classpath.

### validate:xsd

```xquery
validate:xsd(
  $input    as item(),
  $schema   as item()?  := (),
  $options  as map(*)?  := {}
) as empty-sequence()
```
Validates the XML $input document against a $schema. The following $options are available:
* option	default	description
* cache	false()	Generated schemas are cached and reused.
* *other*	–	Handled as features and passed on to the validator.
* 
Errors	
* error	The document cannot be validated against the specified schema.
* init	The validation cannot be started.
* not-found	No validator is available.

Examples	
```xquery
let $doc := <simple:root xmlns:simple='http://basex.org/simple'/>
let $schema :=
  <xs:schema xmlns:xs='http://www.w3.org/2001/XMLSchema'
      targetNamespace='http://basex.org/simple'>
    <xs:element name='root'/>
  </xs:schema>
return validate:xsd($doc, $schema)
```
Pass on document and schema as nodes.
```xquery
for $city in db:get('cities')
return validate:xsd($city, 'city.xsd',
  { 'http://javax.xml.XMLConstants/feature/secure-processing': true() }
)
```
Validate all documents of a database against the specified schema, using the supplied feature.

### validate:xsd-info

```xquery
validate:xsd-info(
  $input    as item(),
  $schema   as item()?  := (),
  $options  as map(*)?  := {}
) as xs:string*
```
Validates the XML $input document against a $schema and returns warnings, errors and fatal errors in a string sequence. See validate:xsd for more information of the $options parameter.
Errors	
* init	The validation cannot be started.
* not-found	No validator is available.
### validate:xsd-report
```xquery
validate:xsd-report(
  $input    as item(),
  $schema   as item()?  := (),
  $options  as map(*)?  := {}
) as element(report)
```
Validates the XML $input document against a $schema and returns warnings, errors and fatal errors as XML. See validate:xsd for more information of the $options parameter.
Errors	
* init	The validation cannot be started.
* not-found	No validator is available.
### validate:xsd-init
```xquery
validate:xsd-init() as empty-sequence()
```
Discards the cached XSD schemas.
### validate:xsd-processor	
```xquery
validate:xsd-processor() as xs:string
```
Returns the name of the applied XSD processor.

### validate:xsd-version
```
validate:xsd-version() as xs:string
```

Returns the supported version of XSD Schema.
## Relax NG Validation

Checks whether an XML document validates against a RelaxNG schema. The input document and the schema can be specified as:

*    xs:string, containing the path to the resource,
*    xs:string, containing the resource in its string representation, or
*    node(), containing the resource itself.

Relax NG validation will be available if Jing exists in the classpath. The latest version, jing-20091111.jar, is included in the full distributions of BaseX. As Jing additionally supports NVDL validation, you can also use the functions to validate the input against NVDL schemas.
### validate:rng
```xuery
validate:rng(
  $input    as item(),
  $schema   as item(),
  $compact  as xs:boolean?  := false()
) as empty-sequence()
```
Validates the XML $input document against a $schema, using the XML or $compact notation.

Errors	
* error	The document cannot be validated against the specified schema.
* init	The validation cannot be started.
* not-found	No validator is available.

Examples	
```
validate:rng('doc.xml', 'doc.rng')
```
Validates the document
doc.xml against the specified schema doc.rng.
### validate:rng-info
```xquery
validate:rng-info(
  $input    as item(),
  $schema   as item(),
  $compact  as xs:boolean?  := false()
) as xs:string*
```
Validates the XML $input document against a $schema, using the XML or $compact notation, and returns warnings, errors and fatal errors in a string sequence.

Errors	
* init	The validation cannot be started.
* not-found	No validator is available.
  
### validate:rng-report
```xquery
validate:rng-report(
  $input    as item(),
  $schema   as xs:string,
  $compact  as xs:boolean?  := false()
) as element(report)
```
Validates the XML $input document against a $schema, using the XML or $compact notation, and returns warnings, errors and fatal errors as XML.
Errors	
* init	The validation cannot be started.
* not-found	No validator is available.

## Schematron Validation

If you want to use Schematron for validating documents, install Vincent Lizzi’s excellent Schematron XQuery Module for BaseX:

repo:install(
  'https://github.com/Schematron/schematron-basex/raw/master/dist/schematron-basex-1.2.xar'
)

The following query illustrates how documents are validated. It is directly taken from the GitHub project:
```xquery
import module namespace sch = "http://github.com/Schematron/schematron-basex";

let $sch := sch:compile(doc('rules.sch'))
let $svrl := sch:validate(doc('document.xml'), $sch)
return (
  sch:is-valid($svrl),
  for $message in sch:messages($svrl)
  return sch:message-level($message) || ': ' || sch:message-description($message)
)
```

Errors
* error	The document cannot be validated against the specified schema.
* init	The validation cannot be started.
* not-found	No validator is available.

## Changelog
Version 11.0

    Added: validate:xsd-init to discard cached XSD schemas.
    Updated: validate:xsd, validate:xsd-info, validate:xsd-report: caching feature added

Version 9.2

    Added: validate:xsd-processor, validate:xsd-version
    Updated: validate:xsd, validate:xsd-info, validate:xsd-report: version argument was dropped (the latest version will always be used)

Version 9.0

    Updated: error codes updated; errors now use the module namespace