.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" 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" ''
.    ds C`
.    ds C'
'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 >0, 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.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" 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 "Catmandu::XSD 3pm"
.TH Catmandu::XSD 3pm "2020-04-02" "perl v5.30.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"
Catmandu::XSD \- Modules for handling XML data with XSD compilation
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    ## Converting XML to YAML/JSON/CSV/etc
\&
\&    # Compile an XSD schema file and parse one shiporder.xml file
\&    catmandu convert XSD \-\-root \*(Aq{}shiporder\*(Aq
\&                         \-\-schemas demo/order/*.xsd
\&                         to YAML < shiporder.xml
\&
\&    # Same as above but parse more than one file into an array of records
\&    catmandu convert XSD \-\-root \*(Aq{}shiporder\*(Aq
\&                         \-\-schemas demo/order/*.xsd
\&                         \-\-files \*(Aqdata/*.xml\*(Aq
\&                         to YAML
\&
\&    # Same as above but all array of records are in a XML container file
\&    catmandu convert XSD \-\-root \*(Aq{}shiporder\*(Aq
\&                         \-\-schemas demo/order/*.xsd
\&                         \-\-xpath \*(Aq/Container/List//Record/Payload/*\*(Aq
\&                         to YAML < data/container.xml
\&
\&    ## Convert an YAML/JSON/CSV into XML validated against an XSD schemas
\&
\&    # Convert one shiporder YAML to XML
\&    catmandu convert YAML to XSD \-\-root \*(Aq{}shiporder\*(Aq
\&                                 \-\-schemas demo/order/*.xsd < shiporder.YAML
\&
\&    # Same as above but store multiple shiporders in the YAML into a separate file
\&    catmandu convert YAML to XSD \-\-root \*(Aq{}shiporder\*(Aq
\&                                 \-\-schemas demo/order/*.xsd
\&                                 \-\-split 1
\&                                 < shiporder.YAML
\&
\&    # Same as above but use template toolkit to pack the XML into an container
\&    # (The xml record is stored in the \*(Aqxml\*(Aq key which can be retrieved in the
\&    # template by [% xml %])
\&    catmandu convert YAML to XSD \-\-root \*(Aq{}shiporder\*(Aq
\&                                 \-\-schemas demo/order/*.xsd
\&                                 \-\-template_before t/xml_header.tt
\&                                 \-\-template t/xml_record.tt
\&                                 \-\-template t/xml_footer.tt
\&                                 < shiporder.YAML
\&
\&     ## Example documents
\&
\&     # Show an example how a valid XML document needs to be structured for an
\&     # XSD scheme.
\&     catmandu convert XSD \-\-root {}shiporder
\&                          \-\-schemas "t/demo/order/*xsd"
\&                          \-\-example 1 to YAML
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Catmandu::XSD contains modules for handling \s-1XML\s0 data within the Catmandu
framework. Parsing and serializing is based on XML::Compile.
.PP
There are two modules available for handling \s-1XML\s0 data in the Catmandu framework:
Catmandu::XML and Catmandu::XSD. The former one can be used when no \s-1XML\s0 schema
is available for the data. It provides a simple interface to read in \s-1XML\s0 data and
transform it to other formats. Because Catmandu::XML doesn't depend on an
\&\s-1XSD\s0 schema, it can't know which fields in the input \s-1XML\s0 files are sequences or
single value elements. Each record is parsed on its own. A record with content:
.PP
.Vb 3
\&    <foo>
\&      <bar>test</bar>
\&    </foo>
.Ve
.PP
will be parsed into a \s-1YAML\s0 output like:
.PP
.Vb 3
\&    catmandu XML to YAML < test.xml
\&    \-\-
\&    bar: test
.Ve
.PP
A record with content:
.PP
.Vb 4
\&    <foo>
\&      <bar>test</bar>
\&      <bar>test</bar>
\&    </foo>
.Ve
.PP
will be parsed into a \s-1YAL\s0 output like:
.PP
.Vb 5
\&    catmandu XML to YAML < test2.xml
\&    \-\-
\&    bar:
\&      \- test
\&      \- test
.Ve
.PP
In the first case 'bar' will contain a string, in the second case an array. This
might no be what you want in some programming projects. E.g. when you need the 'bar'
field to be always an array of values, then you an \s-1XSD\s0 schema file is required
containing the exact structure of the \s-1XML\s0 document:
.PP
.Vb 11
\&    test.xsd:
\&    <?xml version="1.0" encoding="UTF\-8" ?>
\&    <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
\&        <xs:element name="foo">
\&         <xs:complexType>
\&          <xs:sequence>
\&            <xs:element name="bar" type="xs:string" maxOccurs="unbounded"/>
\&          </xs:sequence>
\&         </xs:complexType>
\&        </xs:element>
\&    </xs:schema>
.Ve
.PP
And now the test.xml and test2.xml can be parsed with help of Catmandu::XSD:
.PP
.Vb 4
\&    catmandu XSD \-\-root \*(Aq{}foo\*(Aq \-\-schemas test.xsd to YAML < test.xml
\&    \-\-
\&    bar:
\&      \- test
\&
\&    catmandu XSD \-\-root \*(Aq{}foo\*(Aq \-\-schemas test.xsd to YAML < test2.xml
\&    \-\-
\&    bar:
\&      \- test
\&      \- test
.Ve
.SH "WILDCARDS"
.IX Header "WILDCARDS"
Some \s-1XSD\s0 Schema allow for \f(CW\*(C`any\*(C'\fR or \f(CW\*(C`anyAttribute\*(C'\fR specifications in the schema.
The Catmandu::XSD modules can't guess in these cases what the schema implementation
is. These nodes will be parsed as XML::LibXML::Nodes in the
resulting documents. Catmandu output formats such as Catmandu::Exporter::JSON
can't handle these XML::LibXML::Node nodes. You have to implement yourself a
Catmandu::Fix to translate these values in to plain string, array or hash elements.
.PP
But in general a round trip should be problematic:
.PP
.Vb 1
\&    catmandu XSD \-\-root ... \-\-schema wildcard.xsd to XSD  \-\-root ... \-\-schema wildcard.xsd < data.xml
.Ve
.SH "MIXED ELEMENTS"
.IX Header "MIXED ELEMENTS"
ComplexType and ComplexContent in the \s-1XSD\s0 schema can be declared with the \f(CW\*(C`<mixed="true"\*(C'\fR> attribute.
This means that in the \s-1XML\s0 documents simple text and \s-1XML\s0 elements can be mixed as in:
.PP
.Vb 1
\&      Hello, I\*(Aqm <name>John</name> how can I <bold>help</bold> you?
.Ve
.PP
In these cases it is not know if the elements are required as an hash or should be ignored. By
defaults Catmandu::XSD will parse these elements as XML::LibXML::Nodes documents.
This behavious can be changed by setting the 'mixed' flag:
.PP
.Vb 2
\&    # All mixed elements will be XML::LibXML::Node\-s
\&    catmandu XSD \-\-root ... \-\-schema mixed.xsd  < data.xml
\&
\&    # The mixed elements will be ignored, only the text will survive
\&    #
\&    #  Hello, I\*(Aqm <name>John</name> how can I <bold>help</bold> you?
\&    #
\&    #  =>  Hello, I\*(Aqm John how can I help you?
\&    catmandu XSD \-\-root ... \-\-schema mixed.xsd \-\-mixed TEXTUAL < data.xml
\&
\&    # The mixed text will be ignored, only the elements will survive
\&    #
\&    #  Hello, I\*(Aqm <name>John</name> how can I <bold>help</bold> you?
\&    #
\&    #  =>  { name => \*(AqJohn\*(Aq , bold => \*(Aqhelp\*(Aq }
\&    catmandu XSD \-\-root ... \-\-schema mixed.xsd \-\-mixed STRUCTURAL < data.xml
\&
\&    # The mixed elements will be a plain XML fragment string
\&    #
\&    #  Hello, I\*(Aqm <name>John</name> how can I <bold>help</bold> you?
\&    #
\&    #  =>  $r = \*(AqHello, I\*(Aqm <name>John</name> how can I <bold>help</bold> you?\*(Aq
\&    catmandu XSD \-\-root ... \-\-schema mixed.xsd \-\-mixed XML_STRING < data.xml
.Ve
.SH "MODULES"
.IX Header "MODULES"
.IP "Catmandu::Importer::XSD" 4
.IX Item "Catmandu::Importer::XSD"
Parse and validate \s-1XML\s0 data using an \s-1XSD\s0 file for structural data.
.IP "Catmandu::Exporter::XSD" 4
.IX Item "Catmandu::Exporter::XSD"
Serialize and validate \s-1XML\s0 data using an \s-1XSD\s0 file for structural data.
.IP "Catmandu::Fix::xpath_map" 4
.IX Item "Catmandu::Fix::xpath_map"
Map \s-1XML\s0 from XSD-any elements into data fields using XPath expressions.
.SH "BUGS, QUESTIONS, HELP"
.IX Header "BUGS, QUESTIONS, HELP"
Use the github issue tracker for any bug reports or questions on this module:
https://github.com/LibreCat/Catmandu\-XSD/issues
.SH "DISCLAIMER"
.IX Header "DISCLAIMER"
This module is based on XML::Compile and the Catmandu framework.
.PP
XML::Compile is the workhorse that forms the core of this module to
compile \s-1XSD\s0 file into parser and serializers.
.PP
Catmandu is used to transform parsed \s-1XML\s0 into any format you like.
Catmandu contains a simple \s-1DSL\s0 languages called Catmandu::Fix to create
small scripts to manipulate data. The Catmandu toolkit is used by many
university libraries to process metadata collections.
.PP
For more information on Catmandu visit: http://librecat.org/Catmandu/
or follow the blog posts at: https://librecatproject.wordpress.com/
.SH "AUTHOR"
.IX Header "AUTHOR"
Patrick Hochstenbach , \f(CW\*(C`patrick.hochstenbach at ugent.be\*(C'\fR
.SH "LICENSE AND COPYRIGHT"
.IX Header "LICENSE AND COPYRIGHT"
This program is free software; you can redistribute it and/or modify it
under the terms of either: the \s-1GNU\s0 General Public License as published
by the Free Software Foundation; or the Artistic License.
.PP
See <http://dev.perl.org/licenses/> for more information.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
XML::Compile , Catmandu , Template , Catmandu::XML