Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Schema(3)	      User Contributed Perl Documentation	     Schema(3)

NAME
       XML::Validator::Schema -	validate XML against a subset of W3C XML
       Schema

SYNOPSIS
	 use XML::SAX::ParserFactory;
	 use XML::Validator::Schema;

	 #
	 # create a new	validator object, using	foo.xsd
	 #
	 $validator = XML::Validator::Schema->new(file => 'foo.xsd');

	 #
	 # 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('foo.xml') };
	 die "File failed validation: $@" if $@;

DESCRIPTION
       This module allows you to validate XML documents	against	a W3C XML
       Schema.	This module does not implement the full	W3C XML	Schema
       recommendation (http://www.w3.org/XML/Schema), but a useful subset.
       See the SCHEMA SUPPORT section below.

       IMPORTANT NOTE: 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 SAX parser.  This module is much more
       useful if you can tell where your errors	are, so	using these modules is
       highly recommeded!

INTERFACE
       o   "XML::Validator::Schema->new(file =>	'file.xsd', cache => 1)"

	   Call	this method to create a	new XML::Validator:Schema object.  The
	   only	required option	is "file" which	must provide a path to an XML
	   Schema document.

	   Setting the optional	"cache"	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
	   "file" 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.

	   Since XML::Validator::Schema	is a SAX filter	you will normally pass
	   this	object to a SAX	parser:

	     $validator	= XML::Validator::Schema->new(file => 'foo.xsd');
	     $parser = XML::SAX::ParserFactory->parser(Handler => $validator);

	   Then	you can	proceed	to validate files using	the parser:

	     eval { $parser->parse_uri('foo.xml') };
	     die "File failed validation: $@" if $@;

	   Setting the optional	"debug"	parameter to 1 causes
	   XML::Validator::Schema to output elements and associated attributes
	   while parsing and validating	the XML	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).

RATIONALE
       I'm writing a piece of software which uses Xerces/C++ (
       http://xml.apache.org/xerces-c/ ) to validate documents against XML
       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.

       On CPAN,	the only available XML Schema validator	is XML::Schema.
       Unfortunately, this module isn't	ready for use as it lacks the ability
       to actually parse the XML 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.

       This module represents my attempt to support enough XML 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.

SCHEMA SUPPORT
   Supported Elements
       The following elements are supported by the XML Schema parser.  If you
       don't see an element or an attribute here then you definitely can't use
       it in a schema document.

       You can expect that the schema document parser will produce an error if
       you include elements which are not supported.  However, unsupported
       attributes may be silently ignored.  This should	not be misconstrued as
       a feature and will eventually be	fixed.

       All of these elements must be in	the http://www.w3.org/2001/XMLSchema
       namespace, either using a default namespace or a	prefix.

	 <schema>

	    Supported attributes: targetNamespace, elementFormDefault,
	    attributeFormDefault

	    Notes: the only supported values for elementFormDefault and
	    attributeFormDefault are "unqualified."  As	such, targetNamespace
	    is essentially ignored.

	 <element name="foo">

	    Supported attributes: name,	type, minOccurs, maxOccurs, ref

	 <attribute>

	    Supported attributes: name,	type, use, ref

	 <sequence>

	    Supported attributes: minOccurs, maxOccurs

	 <choice>

	    Supported attributes: minOccurs, maxOccurs

	 <all>

	    Supported attributes: minOccurs, maxOccurs

	 <complexType>

	   Supported attributes: name

	 <simpleContent>

	   The only supported sub-element is <extension>.

	 <extension>

	   Supported attributes: base

	   Notes: only allowed inside <simpleContent>

	 <simpleType>

	   Supported attributes: name

	 <restriction>

	   Supported attributes: base

	   Notes: only allowed inside <simpleType>

	 <whiteSpace>

	   Supported attributes: value

	 <pattern>

	   Supported attributes: value

	 <enumeration>

	   Supported attributes: value

	 <length>

	   Supported attributes: value

	 <minLength>

	   Supported attributes: value

	 <maxLength>

	   Supported attributes: value

	 <minInclusive>

	   Supported attributes: value

	 <minExclusive>

	   Supported attributes: value

	 <maxInclusive>

	   Supported attributes: value

	 <maxExclusive>

	   Supported attributes: value

	 <totalDigits>

	   Supported attributes: value

	 <fractionDigits>

	   Supported attributes: value

	 <annotation>

	 <documentation>

	   Supported attributes: name

	 <union>
	   Supported attributes: MemberTypes

   Simple Type Support
       Supported built-in types	are:

	 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

   Miscellaneous Details
       Other known devations from the specification:

       o   Patterns specified in pattern simpleType restrictions are Perl
	   regexes with	none of	the XML	Schema extensions available.

       o   No effort is	made to	prevent	the declaration	of facets which
	   "loosen" 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.

       o   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.

       o   Marking a facet "fixed" has no effect.

       o   SimpleTypes must come after their base types	in the schema body.
	   For example,	this is	ok:

	       <xs:simpleType name="foo">
		   <xs:restriction base="xs:string">
		       <xs:minLength value="10"/>
		   </xs:restriction>
	       </xs:simpleType>
	       <xs:simpleType name="foo_bar">
		   <xs:restriction base="foo">
		       <xs:length value="10"/>
		   </xs:restriction>
	       </xs:simpleType>

	   But this is not:

	       <xs:simpleType name="foo_bar">
		   <xs:restriction base="foo">
		       <xs:length value="10"/>
		   </xs:restriction>
	       </xs:simpleType>
	       <xs:simpleType name="foo">
		   <xs:restriction base="xs:string">
		       <xs:minLength value="10"/>
		   </xs:restriction>
	       </xs:simpleType>

CAVEATS
       Here are	a few gotchas that you should know about:

       o   No Unicode testing has been performed, although it seems possible
	   that	the module will	handle Unicode data correctly.

       o   Namespace processing	is almost entirely missing from	the module.

       o   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 XML Spy)
	   before using	them with this module.

BUGS
       Please use "rt.cpan.org"	to report bugs in this module:

	 http://rt.cpan.org

       Please note that	I will delete bugs which merely	point out the lack of
       support for a particular	feature	of XML Schema.	Those are feature
       requests, and believe me, I know	we've got a long way to	go.

SUPPORT
       This module is supported	on the perl-xml	mailing-list.  Please join the
       list if you have	questions, suggestions or patches:

	 http://listserv.activestate.com/mailman/listinfo/perl-xml

CVS
       If you'd	like to	help develop XML::Validator::Schema you'll want	to
       check out a copy	of the CVS tree:

	 http://sourceforge.net/cvs/?group_id=89764

CREDITS
       The following people have contributed bug reports, test cases and/or
       code:

	 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

AUTHOR
       Sam Tregar <sam@tregar.com>

COPYRIGHT AND LICENSE
       Copyright (C) 2002-2003 Sam Tregar

       This program is free software; you can redistribute it and/or modify it
       under the same terms as Perl 5 itself.

A NOTE ON DEVELOPMENT METHODOLOGY
       This module isn't just an XML 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 TDD goes further by requiring tests
       to be written before code.  One consequence of this is that the module
       code may	seem naive; it really is just enough 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.

       For more	information I recommend	"Test Driven Development: By Example"
       by Kent Beck.

SEE ALSO
       XML::Schema

       http://www.w3.org/XML/Schema

       http://xml.apache.org/xerces-c/

perl v5.24.1			  2008-01-31			     Schema(3)

NAME | SYNOPSIS | DESCRIPTION | INTERFACE | RATIONALE | SCHEMA SUPPORT | CAVEATS | BUGS | SUPPORT | CVS | CREDITS | AUTHOR | COPYRIGHT AND LICENSE | A NOTE ON DEVELOPMENT METHODOLOGY | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=XML::Validator::Schema&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help