Difference between revisions of "Validation Module"

From BaseX Documentation
Jump to navigation Jump to search
Line 6: Line 6:
 
All errors are assigned to the <code><nowiki>http://basex.org/errors</nowiki></code> namespace, which is statically bound to the {{Code|bxerr}} prefix.
 
All errors are assigned to the <code><nowiki>http://basex.org/errors</nowiki></code> namespace, which is statically bound to the {{Code|bxerr}} prefix.
  
−
=Functions=
+
=DTD Validation=
  
−
==DTD==
+
Checks whether an XML document validates against a DTD. The input document can be specified as:
  
−
===validate:dtd===
+
* an {{Code|xs:string}}, containing the path to the resource,
 +
* an {{Code|xs:string}}, containing the resource in its string representation, or
 +
* a {{Code|node()}}, containing 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==
  
 
{| width='100%'
 
{| width='100%'
 
|-
 
|-
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
−
|{{Func|validate:dtd|$input as item()|empty-sequence()}}<br />{{Func|validate:dtd|$input as item(), $schema as xs:string|empty-sequence()}}
+
|{{Func|validate:dtd|$input as item()|empty-sequence()}}<br />{{Func|validate:dtd|$input as item(), $schema as xs:string?|empty-sequence()}}
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
−
|Validates the document specified by {{Code|$input}}. {{Code|$input}} can be specified as:
+
|Validates the XML {{Code|$input}} document against a {{Code|$schema}} and returns an empty sequence or an error.
−
* an {{Code|xs:string}}, containing the path to the resource,
 
−
* an {{Code|xs:string}}, containing the resource in its string representation, or
 
−
* a {{Code|node()}}, containing the resource itself.
 
−
{{Code|$schema}} can be used to specify the DTD for validation. If no DTD is given, {{Code|$input}} is required to contain a DTD doctype declaration.<br />
 
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
−
|{{Error|BXVA0001|#Errors}} the validation fails.<br/>{{Error|BXVA0002|#Errors}} the validation process cannot be started.<br/>{{Error|BXVA0003|#Errors}} no DTD Schema validator is available.
+
|{{Error|BXVA0001|#Errors}} the validation fails.<br/>{{Error|BXVA0002|#Errors}} the validation process cannot be started.<br/>{{Error|BXVA0003|#Errors}} no DTD validator is available.
 
|-
 
|-
 
| '''Examples'''
 
| '''Examples'''
Line 42: Line 44:
 
|}
 
|}
  
−
===validate:dtd-info===
+
==validate:dtd-info==
  
 
{| width='100%'
 
{| width='100%'
Line 50: Line 52:
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
−
|Validates a document and returns warnings, errors and fatal errors in a string sequence. See [[#validate:dtd|validate:dtd]] for more details on the function arguments.
+
|Validates the XML {{Code|$input}} document against a {{Code|$schema}} and returns warnings, errors and fatal errors in a string sequence.
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
−
|{{Error|BXVA0002|#Errors}} the validation process cannot be started.<br/>{{Error|BXVA0003|#Errors}} no DTD Schema validator is available.
+
|{{Error|BXVA0002|#Errors}} the validation process cannot be started.<br/>{{Error|BXVA0003|#Errors}} no DTD validator is available.
 
|-
 
|-
 
| '''Examples'''
 
| '''Examples'''
Line 60: Line 62:
 
|}
 
|}
  
−
===validate:dtd-report===
+
==validate:dtd-report==
  
 
{{Mark|Introduced with Version 8.3}}:
 
{{Mark|Introduced with Version 8.3}}:
Line 70: Line 72:
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
−
|Validates a document and returns warnings, errors and fatal errors as XML. See [[#validate:dtd|validate:dtd]] for more details on the function arguments.
+
|Validates the XML {{Code|$input}} document against a {{Code|$schema}} and returns warnings, errors and fatal errors as XML.
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
−
|{{Error|BXVA0002|#Errors}} the validation process cannot be started.<br/>{{Error|BXVA0003|#Errors}} no DTD Schema validator is available.
+
|{{Error|BXVA0002|#Errors}} the validation process cannot be started.<br/>{{Error|BXVA0003|#Errors}} no DTD validator is available.
 
|-
 
|-
 
| '''Examples'''
 
| '''Examples'''
Line 86: Line 88:
 
|}
 
|}
  
−
==XML Schema==
+
=XML Schema Validation=
 +
 
 +
{{Mark|Updated with Version 8.3}}:
 +
 
 +
Checks whether an XML document validates against an XML Schema. The input document and the schema can be specified as:
 +
 
 +
* {{Code|xs:string}}, containing the path to the resource,
 +
* {{Code|xs:string}}, containing the resource in its string representation, or
 +
* {{Code|node()}}, containing the resource itself.
 +
 
 +
If no schema is given, the input is expected to contain an {{Code|xsi:(noNamespace)schemaLocation}} attribute, as defined in [http://www.w3.org/TR/xmlschema-1/#xsi_schemaLocation W3C XML Schema].
 +
 
 +
Different XML Schema implementations can be applied for validation:
 +
 
 +
* Java includes a default implementation of XML Schema (which is an older version of Apache Xerces)
 +
* If [https://xerces.apache.org/xerces2-j Xerces2] exists in the classpath, it will be used instead. If you want to manually add Xerces2, you should download the [http://xerces.apache.org/mirrors.cgi#binary Xerces2 Java ..... (XML Schema 1.1) (Beta)] archive and copy at least four libraries ({{Code|cupv10k-runtime.jar}}, {{Code|org.eclipse.wst.xml.xpath2.processor_1.1.0.jar}}, {{Code|xercesImpl.jar}}, {{Code|xml-apis.jar}}) to the {{Code|lib}} directory of the full distribution of BaseX.
 +
* The [http://www.saxonica.com/ Saxon] Enterprise Edition (saxon9ee.jar) is detected as well.
 +
 
 +
With {{Version|8.3}}, the XML Schema version can be specified as well:
  
−
The [http://www.saxonica.com/ Saxon XSLT Processor] – {{Code|SaxonHE.jar}}, {{Code|SaxonPE.jar}}, or {{Code|SaxonEE.jar}} – is used if it is added to the classpath.
+
* The version must be {{Code|1.0}} or {{Code|1.1}}.
 +
* Version 1.1 is only available if Saxon EE or Xerces2 (beta version with XML Schema 1.1 support) is available.
 +
* If Xerces2 is manually added to the classpath,
  
−
===validate:xsd===
+
==validate:xsd==
  
 
{| width='100%'
 
{| width='100%'
 
|-
 
|-
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
−
|{{Func|validate:xsd|$input as item()|empty-sequence()}}<br />{{Func|validate:xsd|$input as item(), $schema as item()|empty-sequence()}}
+
|{{Func|validate:xsd|$input as item()|empty-sequence()}}<br />{{Func|validate:xsd|$input as item(), $schema as item()?|empty-sequence()}}<br />{{Func|validate:xsd|$input as item(), $schema as item()?, $version as xs:string|empty-sequence()}}
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
−
|Validates the document specified by {{Code|$input}}. Both {{Code|$input}} and {{Code|$schema}} can be specified as:
+
|Validates the XML {{Code|$input}} document against a {{Code|$schema}}.
−
* {{Code|xs:string}}, containing the path to the resource,
 
−
* {{Code|xs:string}}, containing the resource in its string representation, or
 
−
* {{Code|node()}}, containing the resource itself.
 
−
{{Code|$schema}} can be used to specify the schema for validation. If no schema is given, {{Code|$input}} is required to contain an {{Code|xsi:(noNamespace)schemaLocation}} attribute as defined in [http://www.w3.org/TR/xmlschema-1/#xsi_schemaLocation W3C XML Schema].<br />
 
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
Line 121: Line 139:
 
|}
 
|}
  
−
===validate:xsd-info===
+
==validate:xsd-info==
  
 
{| width='100%'
 
{| width='100%'
Line 135: Line 153:
 
|}
 
|}
  
−
===validate:xsd-report===
+
==validate:xsd-report==
  
 
{{Mark|Introduced with Version 8.3}}:
 
{{Mark|Introduced with Version 8.3}}:
Line 151: Line 169:
 
|}
 
|}
  
−
==RelaxNG==
+
=RelaxNG=
 +
 
 +
Checks whether an XML document validates against a RelaxNG schema. The input document and the schema an be specified as:
 +
 
 +
* {{Code|xs:string}}, containing the path to the resource,
 +
* {{Code|xs:string}}, containing the resource in its string representation, or
 +
* {{Code|node()}}, containing the resource itself.
  
 
RelaxNG validation will be available if [http://www.thaiopensource.com/relaxng/jing.html Jing] exists in the classpath. The latest version, {{Code|jing-20091111.jar}}, is included in the full distributions of BaseX.
 
RelaxNG validation will be available if [http://www.thaiopensource.com/relaxng/jing.html Jing] exists in the classpath. The latest version, {{Code|jing-20091111.jar}}, is included in the full distributions of BaseX.
  
−
===validate:rng===
+
==validate:rng==
  
 
{{Mark|Introduced with Version 8.3}}:
 
{{Mark|Introduced with Version 8.3}}:
Line 165: Line 189:
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
−
|Validates the document specified by {{Code|$input}}. The validation schema is specified by {{Code|$schema}}, and {{Code|$compact}} indicates if the schema uses the compact RelaxNG notation. Both {{Code|$input}} and {{Code|$schema}} can be specified as:
+
|Validates the XML {{Code|$input}} document against a {{Code|$schema}}, using the XML or {{Code|$compact}} notation.
−
* {{Code|xs:string}}, containing the path to the resource,
 
−
* {{Code|xs:string}}, containing the resource in its string representation, or
 
−
* {{Code|node()}}, containing the resource itself.
 
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
−
|{{Error|BXVA0001|#Errors}} the validation fails.<br/>{{Error|BXVA0002|#Errors}} the validation process cannot be started.<br/>{{Error|BXVA0003|#Errors}} the RelaxNG validator is not available.
+
|{{Error|BXVA0001|#Errors}} the validation fails.<br/>{{Error|BXVA0002|#Errors}} the validation process cannot be started.<br/>{{Error|BXVA0003|#Errors}} the RelaxNG validator is not available.<br/>{{Error|BXVA0004|#Errors}} no validator is found for the specified version.
 
|-
 
|-
 
| '''Examples'''
 
| '''Examples'''
Line 178: Line 199:
 
|}
 
|}
  
−
===validate:rng-info===
+
==validate:rng-info==
  
 
{{Mark|Introduced with Version 8.3}}:
 
{{Mark|Introduced with Version 8.3}}:
Line 188: Line 209:
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
−
|Validates a document and returns warnings, errors and fatal errors in a string sequence. See [[#validate:rng|validate:rng]] for more details on the function arguments.
+
|Validates the XML {{Code|$input}} document against a {{Code|$schema}}, using the XML or {{Code|$compact}} notation, and returns warnings, errors and fatal errors in a string sequence.
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
−
|{{Error|BXVA0002|#Errors}} the validation process cannot be started.<br/>{{Error|BXVA0003|#Errors}} the RelaxNG validator is not available.
+
|{{Error|BXVA0002|#Errors}} the validation process cannot be started.<br/>{{Error|BXVA0003|#Errors}} the RelaxNG validator is not available.<br/>{{Error|BXVA0004|#Errors}} no validator is found for the specified version.
 
|}
 
|}
  
−
===validate:rng-report===
+
==validate:rng-report==
  
 
{{Mark|Introduced with Version 8.3}}:
 
{{Mark|Introduced with Version 8.3}}:
Line 204: Line 225:
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
−
|Validates a document and returns warnings, errors and fatal errors as XML. See [[#validate:rng|validate:rng]] for more details on the function arguments.
+
|Validates the XML {{Code|$input}} document against a {{Code|$schema}}, using the XML or {{Code|$compact}} notation, and returns warnings, errors and fatal errors as XML.
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
−
|{{Error|BXVA0002|#Errors}} the validation process cannot be started.<br/>{{Error|BXVA0003|#Errors}} The RelaxNG validator is not available.
+
|{{Error|BXVA0002|#Errors}} the validation process cannot be started.<br/>{{Error|BXVA0003|#Errors}} The RelaxNG validator is not available.<br/>{{Error|BXVA0004|#Errors}} no validator is found for the specified version.
 
|}
 
|}
  
Line 224: Line 245:
 
|{{Code|BXVA0003}}
 
|{{Code|BXVA0003}}
 
|No validator is available.
 
|No validator is available.
 +
|-
 +
|{{Code|BXVA0004}}
 +
|No validator is found for the specified version.
 
|}
 
|}
  

Revision as of 12:37, 17 September 2015

This XQuery Module contains functions to perform validations against DTDs, XML Schema and (since Version 8.3) RelaxNG. For Schematron validation, check out Vincent Lizzi’s Schematron XQuery Module.

Conventions

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

DTD Validation

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

  • an xs:string, containing the path to the resource,
  • an xs:string, containing the resource in its string representation, or
  • a node(), containing 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

Signatures validate:dtd($input as item()) as empty-sequence()
validate:dtd($input as item(), $schema as xs:string?) as empty-sequence()
Summary Validates the XML $input document against a $schema and returns an empty sequence or an error.
Errors BXVA0001: the validation fails.
BXVA0002: the validation process cannot be started.
BXVA0003: no DTD validator is available.
Examples
  • validate:dtd('doc.xml', 'doc.dtd') validates the document doc.xml against the specified DTD file doc.dtd.
  • The following example validates an invalid document against a DTD, which is specified as string:
try {
  let $doc := <invalid/>
  let $schema := '<!ELEMENT root (#PCDATA)>'
  return validate:dtd($doc, $schema)
} catch bxerr:BXVA0001 {
  'DTD Validation failed.'
}

validate:dtd-info

Signatures validate:dtd-info($input as item()) as xs:string*
validate:dtd-info($input as item(), $schema as xs:string) as xs:string*
Summary Validates the XML $input document against a $schema and returns warnings, errors and fatal errors in a string sequence.
Errors BXVA0002: the validation process cannot be started.
BXVA0003: no DTD validator is available.
Examples
  • validate:dtd-info(<invalid/>, '<!ELEMENT root (#PCDATA)>') returns:
    2:11: Element type "invalid" must be declared..

validate:dtd-report

Template:Mark:

Signatures validate:dtd-report($input as item()) as element(report)
validate:dtd-report($input as item(), $schema as xs:string) as element(report)
Summary Validates the XML $input document against a $schema and returns warnings, errors and fatal errors as XML.
Errors BXVA0002: the validation process cannot be started.
BXVA0003: no DTD validator is available.
Examples
  • validate:dtd-report(<invalid/>, '<!ELEMENT root (#PCDATA)>') returns:
<report>
  <status>invalid</status>
  <message level="Error" line="2" column="11">Element type "invalid" must be declared.</message>
</report>

XML Schema Validation

Template:Mark:

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 implementations can be applied for validation:

  • Java includes a default implementation of XML Schema (which is an older version of Apache Xerces)
  • If Xerces2 exists in the classpath, it will be used instead. If you want to manually add Xerces2, you should download the Xerces2 Java ..... (XML Schema 1.1) (Beta) archive and copy at least four libraries (cupv10k-runtime.jar, org.eclipse.wst.xml.xpath2.processor_1.1.0.jar, xercesImpl.jar, xml-apis.jar) to the lib directory of the full distribution of BaseX.
  • The Saxon Enterprise Edition (saxon9ee.jar) is detected as well.

With Version 8.3, the XML Schema version can be specified as well:

  • The version must be 1.0 or 1.1.
  • Version 1.1 is only available if Saxon EE or Xerces2 (beta version with XML Schema 1.1 support) is available.
  • If Xerces2 is manually added to the classpath,

validate:xsd

Signatures validate:xsd($input as item()) as empty-sequence()
validate:xsd($input as item(), $schema as item()?) as empty-sequence()
validate:xsd($input as item(), $schema as item()?, $version as xs:string) as empty-sequence()
Summary Validates the XML $input document against a $schema.
Errors BXVA0001: the validation fails.
BXVA0002: the validation process cannot be started.
BXVA0003: no XML Schema validator is available.
Examples
  • validate:xsd('doc.xml', 'doc.xsd') validates the document doc.xml against the specified schema doc.xsd.
  • The following example demonstrates how a document can be validated against a schema without resorting to local or remote URIs:
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)

validate:xsd-info

Signatures validate:xsd-info($input as item()) as xs:string*
validate:xsd-info($input as item(), $schema as item()) as xs:string*
Summary Validates a document and returns warnings, errors and fatal errors in a string sequence. See validate:xsd for more details on the function arguments.
Errors BXVA0002: the validation process cannot be started.
BXVA0003: no XML Schema validator is available.

validate:xsd-report

Template:Mark:

Signatures validate:xsd-report($input as item()) as element(report)
validate:xsd-report($input as item(), $schema as xs:string) as element(report)
Summary Validates a document and returns warnings, errors and fatal errors as XML. See validate:xsd for more details on the function arguments.
Errors BXVA0002: the validation process cannot be started.
BXVA0003: no XML Schema validator is available.

RelaxNG

Checks whether an XML document validates against a RelaxNG schema. The input document and the schema an 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.

RelaxNG validation will be available if Jing exists in the classpath. The latest version, jing-20091111.jar, is included in the full distributions of BaseX.

validate:rng

Template:Mark:

Signatures validate:rng($input as item(), $schema as item()) as empty-sequence()
validate:rng($input as item(), $schema as item(), $compact as xs:boolean) as empty-sequence()
Summary Validates the XML $input document against a $schema, using the XML or $compact notation.
Errors BXVA0001: the validation fails.
BXVA0002: the validation process cannot be started.
BXVA0003: the RelaxNG validator is not available.
BXVA0004: no validator is found for the specified version.
Examples
  • validate:rng('doc.xml', 'doc.rng') validates the document doc.xml against the specified schema doc.rng.

validate:rng-info

Template:Mark:

Signatures validate:rng-info($input as item(), $schema as item()) as xs:string*
validate:rng-info($input as item(), $schema as item(), $compact as xs:boolean) as xs:string*
Summary 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 BXVA0002: the validation process cannot be started.
BXVA0003: the RelaxNG validator is not available.
BXVA0004: no validator is found for the specified version.

validate:rng-report

Template:Mark:

Signatures validate:rng-report($input as item(), $schema as xs:string) as element(report)
validate:rng-report($input as item(), $schema as xs:string, $compact as xs:boolean) as element(report)
Summary Validates the XML $input document against a $schema, using the XML or $compact notation, and returns warnings, errors and fatal errors as XML.
Errors BXVA0002: the validation process cannot be started.
BXVA0003: The RelaxNG validator is not available.
BXVA0004: no validator is found for the specified version.

Errors

Code Description
BXVA0001 The document cannot be validated against the specified DTD or XML Schema.
BXVA0002 The validation cannot be started.
BXVA0003 No validator is available.
BXVA0004 No validator is found for the specified version.

Changelog

Version 8.3
Version 7.6

The module was introduced with Version 7.3.

Retrieved from "http://docs.basex.org/index.php?title=Validation_Module&oldid=11983"