Types::XSD - type constraints based on XML schema datatypes
package Person; use Moo; use Types::XSD::Lite qw( PositiveInteger String ); has name => (is => "ro", isa => String[ minLength => 1 ]); has age => (is => "ro", isa => PositiveInteger);
Types::XSD is a type constraint library inspired by XML Schema, and built with Type::Library. It can be used as a type constraint library for Moo, Mouse or Moose, or used completely independently of any OO framework.
This module is an extension of Types::XSD::Lite which has fewer type constraints, but fewer dependencies. For completeness, the type constraints and other features inherited from Types::XSD::Lite are documented below too.
This module defines the following type constraints based on the data types defined in XML Schema. (The names of the type constraints are the same as the XML Schema data types, but capitalization often differs.)
I've added some quick explainations of what each type is, but for details, see the XML Schema specification.
AnyType
As per Any from Types::Standard.
Any
AnySimpleType
As per Value from Types::Standard.
Value
String
As per Str from Types::Standard.
Str
NormalizedString
A string containing no line breaks, carriage returns or tabs.
Token
Like NormalizedString, but also no leading or trailing space, and no doubled spaces (i.e. not /\s{2,}/).
/\s{2,}/
Language
An RFC 3066 language code.
Name
Something that could be a valid XML element or attribute name. These roughly correspond to Perl identifiers but may also contain colons, hyphens and stops. (Digits, hyphens and stops are not allowed as the first character.)
NmToken
Slightly looser version of Name; allows digits, hyphens and stops in the first character.
NmTokens
Space-separated list of NmToken.
NCName
Slightly tighter vesion of Name; disallows colons.
Id
Effectively the same as NCName.
IdRef
IdRefs
Space-separated list of IdRef.
Entity
Entities
Space-separated list of Entity.
Boolean
Allows "true", "false", "1" and "0" (case-insensitively).
"true"
"false"
"1"
"0"
Gotcha: The string "false" evaluates to true in Perl. You probably want to use Bool from Types::Standard instead.
Bool
Base64Binary
Strings which are valid Base64 data. Allows whitespace.
Gotcha: If you parameterize this with length, maxLength or minLength, it is the length of the decoded string which will be checked.
length
maxLength
minLength
HexBinary
Strings which are valid hexadecimal data. Disallows whitespace; disallows leading 0x.
0x
Float
As per Num from Types::Standard.
Num
Double
AnyURI
Any absolute or relative URI. Effectively, any string at all!
QName
An XML QName; something that could be used as a valid element name in a namespaced XML document.
Gotcha: while length, maxLength and minLength are allowed facets for parameterization, they are silently ignored, as per the specification!
Notation
Effectively the same as QName. According to XML Schema, this is always supposed to be parameterized with an enumeration. But we don't enforce that.
Decimal
Numbers possibly including a decimal point, but not allowing exponential notation (e.g. "3.14e-3").
"3.14e-3"
Integer
As per Int from Types::Standard.
Int
NonPositiveInteger
An Integer 0 or below.
NegativeInteger
An Integer -1 or below.
Long
An Integer between -9223372036854775808 and 9223372036854775807 (inclusive).
An Integer between -2147483648 and 2147483647 (inclusive).
Short
An Integer between -32768 and 32767 (inclusive).
Byte
An Integer between -128 and 127 (inclusive).
NonNegativeInteger
An Integer 0 or above.
PositiveInteger
An Integer 1 or above.
UnsignedLong
A NonNegativeInteger between 0 and 18446744073709551615 (inclusive).
UnsignedInt
A NonNegativeInteger between 0 and 4294967295 (inclusive).
UnsignedShort
A NonNegativeInteger between 0 and 65535 (inclusive).
UnsignedByte
A NonNegativeInteger between 0 and 255 (inclusive).
Duration
An ISO 8601 duration.
YearMonthDuration
An ISO 8601 duration restricted to cover only years and months.
DayTimeDuration
An ISO 8601 duration restricted to cover only days, hours, minutes and seconds. (Note that this still permits durations of many years, as the days component is an arbitrary non-negative integer.)
DateTime
An ISO 8601 datetime with optional timezone.
DateTimeStamp
An ISO 8601 datetime with required timezone.
Time
An ISO 8601 time with optional timezone.
Date
An ISO 8601 date with optional timezone.
GYearMonth
An year-month pair with optional timezone.
GYear
An year with optional timezone.
GMonthDay
An month-day pair with optional timezone.
GDay
An day with optional timezone.
GMonth
An month with optional timezone.
Datatypes can be parameterized using the facets defined by XML Schema. For example:
use Types::XSD::Lite qw( String Decimal PositiveInteger Token ); my @sizes = qw( XS S M L XL XXL ); has name => (is => "ro", isa => String[ minLength => 1 ]); has price => (is => "ro", isa => Decimal[ fractionDigits => 2 ]); has rating => (is => "ro", isa => PositiveInteger[ maxInclusive => 5 ]); has size => (is => "ro", isa => Token[ enumeration => \@sizes ]);
The following facets exist, but not all facets are supported for all datatypes. (The module will croak if you try to use an unsupported facet.)
enumeration
An arrayref of allowable values. You should probably use Type::Tiny::Enum instead.
pattern
A regular expression that the value is expected to conform to. Use a normal Perl quoted regexp:
Token[ pattern => qr{^[a-z]+$} ]
whiteSpace
The whiteSpace facet is ignored as I'm not entirely sure what it should do. It perhaps makes sense for coercions, but this module doesn't define any coercions.
assertions
An arrayref of arbitrary additional restrictions, expressed as strings of Perl code or coderefs operating on $_.
$_
For example:
Integer[ assertions => [ '$_ % 3 == 0', # multiple of three, and... sub { is_nice($_) }, # is nice (whatever that means) ], ],
Strings of Perl code will result in faster-running type constraints.
Restrict the length of a value. For example Integer[length=>2] allows 10, 99 and -1, but not 100, 9 or -10.
Integer[length=>2]
10
99
-1
100
9
-10
Types::XSD won't prevent you from making ridiculous constraints such as String[ maxLength => 1, minLength => 2 ].
String[ maxLength => 1, minLength => 2 ]
Note that on HexBinary and Base64Binary types, the lengths apply to the decoded string. Length restrictions are silently ignored for QName and Notation because the W3C doesn't think you should care what length these datatypes are.
maxInclusive
minInclusive
maxExclusive
minExclusive
Supported for numeric types and datetime/duration-related types.
Note that to be super-correct, the {max,min}{Inclusive,Exclusive} facets for numeric types are performed by passing the numbers through Math::BigInt or Math::BigFloat, so may be a little slow.
{max,min}{Inclusive,Exclusive}
totalDigits
For a decimal (or type derived from decimals) specifies that the total number of digits for the value must be at most this number. Given Decimal[ totalDigits => 3 ], 1.23, 12.3, 123, 1.2 and 1 are all allowable; 1.234 is not. 1.230 is also not, but this may change in a future version.
Decimal[ totalDigits => 3 ]
1.23
12.3
123
1.2
1
1.234
1.230
fractionDigits
Like totalDigits but ignores digits before the decimal point.
explicitTimezone
May be "optional", "prohibited" or "required". For example:
"optional"
"prohibited"
"required"
Time[ explicitTimezone => "prohibited" ]
This module also exports some convenience functions:
dur_parse($str)
Parse an xsd:duration string, returning a DateTime::Duration.
dur_cmp($a, $b)
Compare two strings conforming to the xsd:duration datatype to indicate which is the longer duration.
Returns -1 if $a is shorter. Returns 1 if $b is shorter. Returns 0 if the durations are identical. Returns undef if the comparison is indeterminate; for example, "P1Y" (one year) and "P365D" (365 days) are not necessarily identical - in leap years "P365D" is shorter.
dt_cmp($type, $a, $b)
Compare two datetime-like strings. For example, two gYearMonth strings can be compared using:
gYearMonth
dt_cmp(GYearMonth, "2009-02", "2010-10");
Both strings are expected to conform to the same datatype. It doesn't make much sense to compare them otherwise.
dt_parse($type, $str)
Parse a datetime-like string, returning a DateTime::Incomplete object. Note that DateTime::Incomplete objects are always returned, even if the datetime is potentially complete.
Please report any bugs to http://rt.cpan.org/Dist/Display.html?Queue=Types-XSD.
Type::Tiny, Types::XSD::Lite, Types::Standard.
http://www.w3.org/TR/xmlschema-2/ Datatypes in XML Schema 1.0
http://www.w3.org/TR/xmlschema11-2/ Datatypes in XML Schema 1.1
Toby Inkster <tobyink@cpan.org>.
This software is copyright (c) 2013 by Toby Inkster.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
To install Types::XSD, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Types::XSD
CPAN shell
perl -MCPAN -e shell install Types::XSD
For more information on module installation, please visit the detailed CPAN module installation guide.