.\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.05) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .ie \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .el \{\ . de IX .. .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Schema 3pm" .TH Schema 3pm "2008-01-31" "perl v5.10.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" XML::Validator::Schema \- validate XML against a subset of W3C XML Schema .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& use XML::SAX::ParserFactory; \& use XML::Validator::Schema; \& \& # \& # create a new validator object, using foo.xsd \& # \& $validator = XML::Validator::Schema\->new(file => \*(Aqfoo.xsd\*(Aq); \& \& # \& # create a SAX parser and assign the validator as a Handler \& # \& $parser = XML::SAX::ParserFactory\->parser(Handler => $validator); \& \& # \& # validate foo.xml against foo.xsd \& # \& eval { $parser\->parse_uri(\*(Aqfoo.xml\*(Aq) }; \& die "File failed validation: $@" if $@; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module allows you to validate \s-1XML\s0 documents against a W3C \s-1XML\s0 Schema. This module does not implement the full W3C \s-1XML\s0 Schema recommendation (http://www.w3.org/XML/Schema), but a useful subset. See the \s-1SCHEMA\s0 \s-1SUPPORT\s0 section below. .PP \&\fB\s-1IMPORTANT\s0 \s-1NOTE\s0\fR: To get line and column numbers in the error messages generated by this module you must install XML::Filter::ExceptionLocator and use XML::SAX::ExpatXS as your \s-1SAX\s0 parser. This module is much more useful if you can tell where your errors are, so using these modules is highly recommeded! .SH "INTERFACE" .IX Header "INTERFACE" .IP "\(bu" 4 \&\f(CW\*(C`XML::Validator::Schema\->new(file => \*(Aqfile.xsd\*(Aq, cache => 1)\*(C'\fR .Sp Call this method to create a new XML::Validator:Schema object. The only required option is \f(CW\*(C`file\*(C'\fR which must provide a path to an \s-1XML\s0 Schema document. .Sp Setting the optional \f(CW\*(C`cache\*(C'\fR parameter to 1 causes XML::Validator::Schema to keep a copy of the schema parse tree in memory. The tree will be reused on subsequent calls with the same \&\f(CW\*(C`file\*(C'\fR parameter, as long as the mtime on the schema file hasn't changed. This can save a lot of time if you're validating many documents against a single schema. .Sp Since XML::Validator::Schema is a \s-1SAX\s0 filter you will normally pass this object to a \s-1SAX\s0 parser: .Sp .Vb 2 \& $validator = XML::Validator::Schema\->new(file => \*(Aqfoo.xsd\*(Aq); \& $parser = XML::SAX::ParserFactory\->parser(Handler => $validator); .Ve .Sp Then you can proceed to validate files using the parser: .Sp .Vb 2 \& eval { $parser\->parse_uri(\*(Aqfoo.xml\*(Aq) }; \& die "File failed validation: $@" if $@; .Ve .Sp Setting the optional \f(CW\*(C`debug\*(C'\fR parameter to 1 causes XML::Validator::Schema to output elements and associated attributes while parsing and validating the \s-1XML\s0 document. This provides useful information on the position where the validation failed (although not at useful as the line and column numbers included when XML::Filter::ExceptiionLocator and XML::SAX::ExpatXS are used). .SH "RATIONALE" .IX Header "RATIONALE" I'm writing a piece of software which uses Xerces/\*(C+ ( http://xml.apache.org/xerces\-c/ ) to validate documents against \s-1XML\s0 Schema schemas. This works very well, but I'd like to release my project to the world. Requiring users to install Xerces is simply too onerous a requirement; few will have it already and the Xerces installation system leaves much to be desired. .PP On \s-1CPAN\s0, the only available \s-1XML\s0 Schema validator is XML::Schema. Unfortunately, this module isn't ready for use as it lacks the ability to actually parse the \s-1XML\s0 Schema document format! I looked into enhancing XML::Schema but I must admit that I'm not smart enough to understand the code... One day, when XML::Schema is completed I will replace this module with a wrapper around it. .PP This module represents my attempt to support enough \s-1XML\s0 Schema syntax to be useful without attempting to tackle the full standard. I'm sure this will mean that it can't be used in all situations, but hopefully that won't prevent it from being used at all. .SH "SCHEMA SUPPORT" .IX Header "SCHEMA SUPPORT" .SS "Supported Elements" .IX Subsection "Supported Elements" The following elements are supported by the \s-1XML\s0 Schema parser. If you don't see an element or an attribute here then you definitely can't use it in a schema document. .PP You can expect that the schema document parser will produce an error if you include elements which are not supported. However, unsupported attributes \fImay\fR be silently ignored. This should not be misconstrued as a feature and will eventually be fixed. .PP All of these elements must be in the http://www.w3.org/2001/XMLSchema namespace, either using a default namespace or a prefix. .PP .Vb 1 \& \& \& Supported attributes: targetNamespace, elementFormDefault, \& attributeFormDefault \& \& Notes: the only supported values for elementFormDefault and \& attributeFormDefault are "unqualified." As such, targetNamespace \& is essentially ignored. \& \& \& \& Supported attributes: name, type, minOccurs, maxOccurs, ref \& \& \& \& Supported attributes: name, type, use, ref \& \& \& \& Supported attributes: minOccurs, maxOccurs \& \& \& \& Supported attributes: minOccurs, maxOccurs \& \& \& \& Supported attributes: minOccurs, maxOccurs \& \& \& \& Supported attributes: name \& \& \& \& The only supported sub\-element is . \& \& \& \& Supported attributes: base \& \& Notes: only allowed inside \& \& \& \& Supported attributes: name \& \& \& \& Supported attributes: base \& \& Notes: only allowed inside \& \& \& \& Supported attributes: value \& \& \& \& Supported attributes: value \& \& \& \& Supported attributes: value \& \& \& \& Supported attributes: value \& \& \& \& Supported attributes: value \& \& \& \& Supported attributes: value \& \& \& \& Supported attributes: value \& \& \& \& Supported attributes: value \& \& \& \& Supported attributes: value \& \& \& \& Supported attributes: value \& \& \& \& Supported attributes: value \& \& \& \& Supported attributes: value \& \& \& \& \& \& Supported attributes: name \& \& \& Supported attributes: MemberTypes .Ve .SS "Simple Type Support" .IX Subsection "Simple Type Support" Supported built-in types are: .PP .Vb 1 \& string \& \& normalizedString \& \& token \& \& NMTOKEN \& \& Notes: the spec says NMTOKEN should only be used for attributes, \& but this rule is not enforced. \& \& boolean \& \& decimal \& \& Notes: the enumeration facet is not supported on decimal or any \& types derived from decimal. \& \& integer \& \& int \& \& short \& \& byte \& \& unsignedInt \& \& unsignedShort \& \& unsignedByte \& \& positiveInteger \& \& negativeInteger \& \& nonPositiveInteger \& \& nonNegativeInteger \& \& dateTime \& \& Notes: Although dateTime correctly validates the lexical format it does not \& offer comparison facets (min*, max*, enumeration). \& \& double \& \& Notes: Although double correctly validates the lexical format it \& does not offer comparison facets (min*, max*, enumeration). Also, \& minimum and maximum constraints as described in the spec are not \& checked. \& \& float \& \& Notes: The restrictions on double support apply to float as well. \& \& duration \& \& time \& \& date \& \& gYearMonth \& \& gYear \& \& gMonthDay \& \& gDay \& \& gMonth \& \& hexBinary \& \& base64Binary \& \& anyURI \& \& QName \& \& NOTATION .Ve .SS "Miscellaneous Details" .IX Subsection "Miscellaneous Details" Other known devations from the specification: .IP "\(bu" 4 Patterns specified in pattern simpleType restrictions are Perl regexes with none of the \s-1XML\s0 Schema extensions available. .IP "\(bu" 4 No effort is made to prevent the declaration of facets which \*(L"loosen\*(R" the restrictions on a type. This is a bug and will be fixed in a future release. Until then types which attempt to loosen restrictions on their base class will behave unpredictably. .IP "\(bu" 4 No attempt has been made to exclude content models which are ambiguous, as the spec demands. In fact, I don't see any compelling reason to do so, aside from strict compliance to the spec. The content model implementaton uses regular expressions which should be able to handle loads of ambiguity without significant performance problems. .IP "\(bu" 4 Marking a facet \*(L"fixed\*(R" has no effect. .IP "\(bu" 4 SimpleTypes must come after their base types in the schema body. For example, this is ok: .Sp .Vb 10 \& \& \& \& \& \& \& \& \& \& .Ve .Sp But this is not: .Sp .Vb 10 \& \& \& \& \& \& \& \& \& \& .Ve .SH "CAVEATS" .IX Header "CAVEATS" Here are a few gotchas that you should know about: .IP "\(bu" 4 No Unicode testing has been performed, although it seems possible that the module will handle Unicode data correctly. .IP "\(bu" 4 Namespace processing is almost entirely missing from the module. .IP "\(bu" 4 Little work has been done to ensure that invalid schemas fail gracefully. Until that is done you may want to develop your schemas using a more mature validator (like Xerces or \s-1XML\s0 Spy) before using them with this module. .SH "BUGS" .IX Header "BUGS" Please use \f(CW\*(C`rt.cpan.org\*(C'\fR to report bugs in this module: .PP .Vb 1 \& http://rt.cpan.org .Ve .PP Please note that I will delete bugs which merely point out the lack of support for a particular feature of \s-1XML\s0 Schema. Those are feature requests, and believe me, I know we've got a long way to go. .SH "SUPPORT" .IX Header "SUPPORT" This module is supported on the perl-xml mailing-list. Please join the list if you have questions, suggestions or patches: .PP .Vb 1 \& http://listserv.activestate.com/mailman/listinfo/perl\-xml .Ve .SH "CVS" .IX Header "CVS" If you'd like to help develop XML::Validator::Schema you'll want to check out a copy of the \s-1CVS\s0 tree: .PP .Vb 1 \& http://sourceforge.net/cvs/?group_id=89764 .Ve .SH "CREDITS" .IX Header "CREDITS" The following people have contributed bug reports, test cases and/or code: .PP .Vb 9 \& Russell B Cecala (aka Plankton) \& David Wheeler \& Toby Long\-Leather \& Mathieu \& h.bridge@fasol.fujitsu.com \& michael.jacob@schering.de \& josef@clubphoto.com \& adamk@ali.as \& Jean Flouret .Ve .SH "AUTHOR" .IX Header "AUTHOR" Sam Tregar .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" Copyright (C) 2002\-2003 Sam Tregar .PP This program is free software; you can redistribute it and/or modify it under the same terms as Perl 5 itself. .SH "A NOTE ON DEVELOPMENT METHODOLOGY" .IX Header "A NOTE ON DEVELOPMENT METHODOLOGY" This module isn't just an \s-1XML\s0 Schema validator, it's also a test of the Test Driven Development methodology. I've been writing tests while I develop code for a while now, but \s-1TDD\s0 goes further by requiring tests to be written \fIbefore\fR code. One consequence of this is that the module code may seem naive; it really is \fIjust enough\fR code to pass the current test suite. If I'm doing it right then there shouldn't be a single line of code that isn't directly related to passing a test. As I add functionality (by way of writing tests) I'll refactor the code a great deal, but I won't add code only to support future development. .PP For more information I recommend \*(L"Test Driven Development: By Example\*(R" by Kent Beck. .SH "SEE ALSO" .IX Header "SEE ALSO" XML::Schema .PP http://www.w3.org/XML/Schema .PP http://xml.apache.org/xerces\-c/