A perl module for validating xml
XML::Checker::Parser - an XML::Parser that validates at parse time
XML::DOM::ValParser - an XML::DOM::Parser that validates at parse time
(Some of the package names may change! This is only an alpha release...)
XML::Checker can be used in different ways to validate \s-1XML\s0. See the manual pages of XML::Checker::Parser and XML::DOM::ValParser for more information.
This document only describes common topics like error handling and the XML::Checker class itself.
\s-1WARNING:\s0 Not all errors are currently checked. Almost everything is subject to change. Some reported errors may not be real errors. For production code, it is recommended that you use XML::LibXML or \s-1XML::GDOME\s0 instead of XML::Checker. Both modules share the same \s-1DTD\s0 validation code with libxml2 and XML::LibXML is easier to install.
Whenever XML::Checker (or one of the packages that uses XML::Checker) detects a potential error, the 'fail handler' is called. It is currently also called to report information, like how many times an Entity was referenced. (The whole error handling mechanism is subject to change, I'm afraid...)
The default fail handler is XML::Checker::print_error(), which prints an error message to \s-1STDERR\s0. It does not stop the XML::Checker, so it will continue looking for other errors. The error message is created with XML::Checker::error_string().
You can define your own fail handler in two ways, locally and globally. Use a local variable to temporarily override the fail handler. This way the default fail handler is restored when the local variable goes out of scope, esp. when exceptions are thrown e.g.
# Using a local variable to temporarily override the fail handler (preferred)
{ # new block - start of local scope
local $XML::Checker::FAIL = \&my_fail;
... your code here ...
} # end of block - the previous fail handler is restored
You can also set the error handler globally, risking that your code may not be reusable or may clash with other modules that use XML::Checker.
# Globally setting the fail handler (not recommended) $XML::Checker::FAIL = \&my_fail; ... rest of your code ...
The fail handler is called with the following parameters ($code, $msg, @context), where $code is the error code, $msg is the error description and @context contains information on where the error occurred. The @context is a (ordered) list of (key,value) pairs and can easily be turned into a hash. It contains the following information:
Element - tag name of Element node (if applicable) Attr - attribute name (if applicable) ChildElementIndex - if applicable (see error 157) line - only when parsing column - only when parsing byte - only when parsing (-1 means: end of file)
Some examples of fail handlers:
# Don't print info messages sub my_fail { my $code = shift; print STDERR XML::Checker::error_message ($code, @_) if $code < 300; }
# Die when the first error is encountered - this will stop # the parsing process. Ignore information messages. sub my_fail { my $code = shift; die XML::Checker::error_message ($code, @_) if $code < 300; }
# Count the number of undefined NOTATION references # and print the error as usual sub my_fail { my $code = shift; $count_undef_notations++ if $code == 100; XML::Checker::print_error ($code, @_); }
# Die when an error is encountered. # Don't die if a warning or info message is encountered, just print a message. sub my_fail { my $code = shift; die XML::Checker::error_string ($code, @_) if $code < 200; XML::Checker::print_error ($code, @_); }
XML::Checker keeps track of whether whitespace found in character data is significant or not. It is considered insignicant if it is found inside an element that has a \s-1ELEMENT\s0 rule that is not of type Mixed or of type \s-1ANY\s0. (A Mixed \s-1ELEMENT\s0 rule does contains the #PCDATA keyword. An \s-1ANY\s0 rule contains the \s-1ANY\s0 keyword. See the \s-1XML\s0 spec for more info.)
XML::Checker can not determine whether whitespace is insignificant in those two cases, because they both allow regular character data to appear within \s-1XML\s0 elements and XML::Checker can therefore not deduce whether whitespace is part of the actual data or was just added for readability of the \s-1XML\s0 file.
XML::Checker::Parser and XML::DOM::ValParser both have the option to skip insignificant whitespace when setting SkipInsignifWS to 1 in their constructor. If set, they will not call the Char handler when insignificant whitespace is encountered. This means that in XML::DOM::ValParser no Text nodes are created for insignificant whitespace.
Regardless of whether the SkipInsignifWS options is set, XML::Checker always keeps track of whether whitespace is insignificant. After making a call to XML::Checker's Char handler, you can find out if it was insignificant whitespace by calling the isInsignifWS method.
When using multiple (nested) XML::Checker instances or when using XML::Checker without using XML::Checker::Parser or XML::DOM::ValParser (which hardly anybody probably will), make sure to set a local variable in the scope of your checking code, e.g.
{ # new block - start of local scope local $XML::Checker::INSIGNIF_WS = 0; ... insert your code here ... } # end of scope
There are 3 categories, errors, warnings and info messages. (The codes are still subject to change, as well the error descriptions.)
Most errors have a link to the appropriate Validaty Constraint (\s-1VC\s0) or other section in the \s-1XML\s0 specification.
100 - undefined \s-1NOTATION\s0 [$notation] in \s-1ATTLIST\s0 The \s-1ATTLIST\s0 contained a Notation reference that was not defined in a \s-1NOTATION\s0 definition. \s-1VC:\s0 Notation Attributes <http://www.w3.org/TR/REC-xml#notatn>
101 - undefined \s-1ELEMENT\s0 [$tagName] The specified Element was never defined in an \s-1ELEMENT\s0 definition. This is not an error according to the \s-1XML\s0 spec. See Element Type Declarations <http://www.w3.org/TR/REC-xml#elemdecls>
102 - undefined unparsed \s-1ENTITY\s0 [$entity] The attribute value referenced an undefined unparsed entity. \s-1VC:\s0 Entity Name <http://www.w3.org/TR/REC-xml#entname>
103 - undefined attribute [$attrName] The specified attribute was not defined in an \s-1ATTLIST\s0 for that Element. \s-1VC:\s0 Attribute Value Type <http://www.w3.org/TR/REC-xml#ValueType>
110 - attribute [$attrName] of element [$tagName] already defined The specified attribute was already defined in this \s-1ATTLIST\s0 definition or in a previous one. This is not an error according to the \s-1XML\s0 spec. See Attribute-List Declarations <http://www.w3.org/TR/REC-xml#attdecls>
111 - \s-1ID\s0 [$value] already defined An \s-1ID\s0 with the specified value was already defined in an attribute within the same document. \s-1VC:\s0 \s-1ID\s0 <http://www.w3.org/TR/REC-xml#id>
112 - unparsed \s-1ENTITY\s0 [$entity] already defined This is not an error according to the \s-1XML\s0 spec. See Entity Declarations <http://www.w3.org/TR/REC-xml#sec-entity-decl>
113 - \s-1NOTATION\s0 [$notation] already defined
114 - \s-1ENTITY\s0 [$entity] already defined This is not an error according to the \s-1XML\s0 spec. See Entity Declarations <http://www.w3.org/TR/REC-xml#sec-entity-decl>
115 - \s-1ELEMENT\s0 [$name] already defined \s-1VC:\s0 Unique Element Type Declaration <http://www.w3.org/TR/REC-xml#EDUnique>
120 - invalid default \s-1ENTITY\s0 [$default] (Or \s-1IDREF\s0 or \s-1NMTOKEN\s0 instead of \s-1ENTITY\s0.) The \s-1ENTITY\s0, \s-1IDREF\s0 or \s-1NMTOKEN\s0 reference in the default attribute value for an attribute with types \s-1ENTITY\s0, \s-1IDREF\s0 or \s-1NMTOKEN\s0 was not valid. \s-1VC:\s0 Attribute Default Legal <http://www.w3.org/TR/REC-xml#defattrvalid>
121 - invalid default [$token] in \s-1ENTITIES\s0 [$default] (Or \s-1IDREFS\s0 or \s-1NMTOKENS\s0 instead of \s-1ENTITIES\s0) One of the \s-1ENTITY\s0, \s-1IDREF\s0 or \s-1NMTOKEN\s0 references in the default attribute value for an attribute with types \s-1ENTITIES\s0, \s-1IDREFS\s0 or \s-1NMTOKENS\s0 was not valid. \s-1VC:\s0 Attribute Default Legal <http://www.w3.org/TR/REC-xml#defattrvalid>
122 - invalid default attribute value [$default] The specified default attribute value is not a valid attribute value. \s-1VC:\s0 Attribute Default Legal <http://www.w3.org/TR/REC-xml#defattrvalid>
123 - invalid default \s-1ID\s0 [$default], must be #REQUIRED or #IMPLIED The default attribute value for an attribute of type \s-1ID\s0 has to be #REQUIRED or #IMPLIED. \s-1VC:\s0 \s-1ID\s0 Attribute Default <http://www.w3.org/TR/REC-xml#id-default>
124 - bad model [$model] for \s-1ELEMENT\s0 [$name] The model in the \s-1ELEMENT\s0 definition did not conform to the \s-1XML\s0 syntax for Mixed models. See Mixed Content <http://www.w3.org/TR/REC-xml#sec-mixed-content>
130 - invalid \s-1NMTOKEN\s0 [$attrValue] The attribute value is not a valid NmToken token. \s-1VC:\s0 Enumeration <http://www.w3.org/TR/REC-xml#enum>
131 - invalid \s-1ID\s0 [$attrValue] The specified attribute value is not a valid Name token. \s-1VC:\s0 \s-1ID\s0 <http://www.w3.org/TR/REC-xml#id>
132 - invalid \s-1IDREF\s0 [$value] The specified attribute value is not a valid Name token. \s-1VC:\s0 \s-1IDREF\s0 <http://www.w3.org/TR/REC-xml#idref>
133 - invalid \s-1ENTITY\s0 name [$name] The specified attribute value is not a valid Name token. \s-1VC:\s0 Entity Name <http://www.w3.org/TR/REC-xml#entname>
134 - invalid Enumeration value [$value] in \s-1ATTLIST\s0 The specified value is not a valid NmToken (see \s-1XML\s0 spec for def.) See definition of NmToken <http://www.w3.org/TR/REC-xml#NT-Nmtoken>
135 - empty \s-1NOTATION\s0 list in \s-1ATTLIST\s0 The \s-1NOTATION\s0 list of the \s-1ATTLIST\s0 definition did not contain any \s-1NOTATION\s0 references. See definition of NotationType <http://www.w3.org/TR/REC-xml#NT-NotationType>
136 - empty Enumeration list in \s-1ATTLIST\s0 The \s-1ATTLIST\s0 definition of the attribute of type Enumeration did not contain any values. See definition of Enumeration <http://www.w3.org/TR/REC-xml#NT-Enumeration>
137 - invalid \s-1ATTLIST\s0 type [$type] The attribute type has to be one of: \s-1ID\s0, \s-1IDREF\s0, \s-1IDREFS\s0, \s-1ENTITY\s0, \s-1ENTITIES\s0, \s-1NMTOKEN\s0, \s-1NMTOKENS\s0, \s-1CDATA\s0, \s-1NOTATION\s0 or an Enumeration. See definition of AttType <http://www.w3.org/TR/REC-xml#NT-AttType>
149 - invalid text content [$value] A text was found in an element that should only include sub-elements The text is not made of non-significant whitespace. 150 - bad #FIXED attribute value [$value], it should be [$default] The specified attribute was defined as #FIXED in the \s-1ATTLIST\s0 definition and the found attribute $value differs from the specified $default value. \s-1VC:\s0 Fixed Attribute Default <http://www.w3.org/TR/REC-xml#FixedAttr>
151 - only one \s-1ID\s0 allowed in \s-1ATTLIST\s0 per element first=[$attrName] The \s-1ATTLIST\s0 definitions for an Element may contain only one attribute with the type \s-1ID\s0. The specified $attrName is the one that was found first. \s-1VC:\s0 One \s-1ID\s0 per Element Type <http://www.w3.org/TR/REC-xml#one-id-per-el>
152 - Element should be \s-1EMPTY\s0, found Element [$tagName] The \s-1ELEMENT\s0 definition for the specified Element said it should be \s-1EMPTY\s0, but a child Element was found. \s-1VC:\s0 Element Valid (sub1) <http://www.w3.org/TR/REC-xml#elementvalid>
153 - Element should be \s-1EMPTY\s0, found text [$text] The \s-1ELEMENT\s0 definition for the specified Element said it should be \s-1EMPTY\s0, but text was found. Currently, whitespace is not allowed between the open and close tag. (This may be wrong, please give feedback.) To allow whitespace (subject to change), set: $XML::Checker::Context::EMPTY::ALLOW_WHITE_SPACE = 1; \s-1VC:\s0 Element Valid (sub1) <http://www.w3.org/TR/REC-xml#elementvalid>
154 - bad order of Elements Found=[$found] RE=[$re] The child elements of the specified Element did not match the regular expression found in the \s-1ELEMENT\s0 definition. $found contains a comma separated list of all the child element tag names that were found. $re contains the (decoded) regular expression that was used internally. \s-1VC:\s0 Element Valid <http://www.w3.org/TR/REC-xml#elementvalid>
155 - more than one root Element [$tags] An \s-1XML\s0 Document may only contain one Element. $tags is a comma separated list of element tag names encountered sofar. XML::Parser (expat) throws 'no element found' exception. See two_roots.xml for an example. See definition of document <http://www.w3.org/TR/REC-xml#dt-root>
156 - unexpected root Element [$tagName], expected [$rootTagName] The tag name of the root Element of the \s-1XML\s0 Document differs from the name specified in the \s-1DOCTYPE\s0 section. XML::Parser (expat) throws 'not well-formed' exception. See bad_root.xml for an example. \s-1VC:\s0 Root Element Type <http://www.w3.org/TR/REC-xml#vc-roottype>
157 - unexpected Element [$tagName] The \s-1ELEMENT\s0 definition for the specified Element does not allow child Elements with the specified $tagName. \s-1VC:\s0 Element Valid <http://www.w3.org/TR/REC-xml#elementvalid> The error context contains ChildElementIndex which is the index within its parent Element (counting only Element nodes.)
158 - unspecified value for #IMPLIED attribute [$attrName] The \s-1ATTLIST\s0 for the specified attribute said the attribute was #IMPLIED, which means the user application should supply a value, but the attribute value was not specified. (User applications should pass a value and set $specified to 1 in the Attr handler.)
159 - unspecified value for #REQUIRED attribute [$attrName] The \s-1ATTLIST\s0 for the specified attribute said the attribute was #REQUIRED, which means that a value should have been specified. \s-1VC:\s0 Required Attribute <http://www.w3.org/TR/REC-xml#RequiredAttr>
160 - invalid Enumeration value [$attrValue] The specified attribute value does not match one of the Enumeration values in the \s-1ATTLIST\s0. \s-1VC:\s0 Enumeration <http://www.w3.org/TR/REC-xml#enum>
161 - invalid \s-1NOTATION\s0 value [$attrValue] The specified attribute value was not found in the list of possible \s-1NOTATION\s0 references as found in the \s-1ATTLIST\s0 definition. \s-1VC:\s0 Notation Attributes <http://www.w3.org/TR/REC-xml#notatn>
162 - undefined \s-1NOTATION\s0 [$attrValue] The \s-1NOTATION\s0 referenced by the specified attribute value was not defined. \s-1VC:\s0 Notation Attributes <http://www.w3.org/TR/REC-xml#notatn>
200 - undefined \s-1ID\s0 [$id] was referenced [$n] times The specified \s-1ID\s0 was referenced $n times, but never defined in an attribute value with type \s-1ID\s0. \s-1VC:\s0 \s-1IDREF\s0 <http://www.w3.org/TR/REC-xml#idref>
300 - [$n] references to \s-1ID\s0 [$id] The specified \s-1ID\s0 was referenced $n times.
The following errors are already checked by XML::Parser (expat) and are currently not checked by XML::Checker:
(?? \s-1TODO\s0 - add more info)
XML::Parser (expat) throws 'no element found' exception. See no_root.xml for an example.
XML::Checker can be easily plugged into your application. It uses mostly the same style of event handlers (or callbacks) as XML::Parser. See XML::Parser manual page for descriptions of most handlers.
It also implements PerlSAX style event handlers. See \*(L"PerlSAX interface\*(R".
Currently, the XML::Checker object is a blessed hash with the following (potentially useful) entries:
$checker->{RootElement} - root element name as found in the DOCTYPE $checker->{NOTATION}->{$notation} - is 1 if the NOTATION was defined $checker->{ENTITY}->{$name} - contains the (first) ENTITY value if defined $checker->{Unparsed}->{$entity} - is 1 if the unparsed ENTITY was defined $checker->{ID}->{$id} - is 1 if the ID was defined $checker->{IDREF}->{$id} - number of times the ID was referenced
# Less useful: $checker->{ERule}->{$tag} - the ELEMENT rules by Element tag name $checker->{ARule}->{$tag} - the ATTLIST rules by Element tag name $checker->{Context} - context stack used internally $checker->{CurrARule} - current ATTLIST rule for the current Element
This section is only interesting when using XML::Checker directly. XML::Checker supports most event handlers that XML::Parser supports with minor differences. Note that the XML::Checker event handler methods are instance methods and not static, so don't forget to call them like this, without passing $expat (as in the XML::Parser) handlers:
$checker->Start($tagName);
$checker = new XML::Checker; $checker = new XML::Checker (%user_args); User data may be stored by client applications. Only $checker->{User} is guaranteed not to clash with internal hash keys.
$tagName = $checker->getRootElement; Returns the root element name as found in the \s-1DOCTYPE\s0
XML::Checker supports what I call the Expat interface, which is the collection of methods you normally specify as the callback handlers when using XML::Parser.
Only the following XML::Parser handlers are currently supported: Init, Final, Char, Start, End, Element, Attlist, Doctype, Unparsed, Entity, Notation.
I don't know how to correctly support the Default handler for all XML::Parser releases. The Start handler works a little different (see below) and I added Attr, InitDomElem, FinalDomElem, \s-1CDATA\s0 and EntityRef handlers. See XML::Parser for a description of the handlers that are not listed below.
Note that this interface may disappear, when the PerlSAX interface stabilizes.
$checker->Start($tag); Call this when an Element with the specified $tag name is encountered. Different from the Start handler in XML::Parser, in that no attributes are passed in (use the Attr handler for those.) $checker->Attr($tag,$attrName,$attrValue,$spec); Checks an attribute with the specified $attrName and $attrValue against the \s-1ATTLIST\s0 definition of the element with the specified $tag name. $isSpecified means whether the attribute was specified (1) or defaulted (0).
$checker->EndAttr; This should be called after all attributes are passed with Attr(). It will check which of the #REQUIRED attributes were not specified and generate the appropriate error (159) for each one that is missing.
$checker->CDATA($text); This should be called whenever CDATASections are encountered. Similar to Char handler (but might perform different checks later...) $checker->EntityRef($entity,$isParameterEntity); Checks the \s-1ENTITY\s0 reference. Set $isParameterEntity to 1 for entity references that start with '%'.
Used by XML::DOM::Element::check() to initialize (and cleanup) the context stack when checking a single element.
XML::Checker now also supports the PerlSAX interface, so you can use XML::Checker wherever you use PerlSAX handlers.
XML::Checker implements the following methods: start_document, end_document, start_element, end_element, characters, processing_instruction, comment, start_cdata, end_cdata, entity_reference, notation_decl, unparsed_entity_decl, entity_decl, element_decl, attlist_decl, doctype_decl, xml_decl
Not implemented: set_document_locator, ignorable_whitespace
See PerlSAX.pod for details. (It is called lib/PerlSAX.pod in the libxml-perl distribution which can be found at \s-1CPAN\s0.)
This is an alpha release. It is not actively maintained, patches are accepted and incoporated in new releases, but that's about it. If you are interested in taking over maintimance of the module, email [email protected].
For a much faster, and correct \s-1DTD\s0 validator, see XML::LibXML. It uses the libxml2 library to validate \s-1DTD\s0.
Enno Derksen is the original author.
Send patches to T.J. Mather at <[email protected]>.
XML::LibXML provides validating parsers against a \s-1DTD\s0 and is recommended over XML::Checker since it uses the libxml2 library which is fast and well-tested.
The \s-1XML\s0 spec (Extensible Markup Language 1.0) at http://www.w3.org/TR/REC-xml <http://www.w3.org/TR/REC-xml>
The XML::Parser and XML::Parser::Expat manual pages.
The other packages that come with XML::Checker: XML::Checker::Parser, XML::DOM::ValParser
The \s-1DOM\s0 Level 1 specification at http://www.w3.org/TR/REC-DOM-Level-1 <http://www.w3.org/TR/REC-DOM-Level-1>
The PerlSAX specification. It is currently in lib/PerlSAX.pod in the libxml-perl distribution by Ken MacLeod.
The original \s-1SAX\s0 specification (Simple \s-1API\s0 for \s-1XML\s0) can be found at <http://www.megginson.com/SAX> and <http://www.megginson.com/SAX/SAX2>