Catmandu::XSD(3pm)

📦
version 0.05 · 5 versions
, in debian bookworm, ubuntu noble

Catmandu::XSD 💖

okay bestie, so this is the manual page for Catmandu::XSD — and it lives in the User Contributed Perl Documentation section, aka section 3pm, aka the place where all the good stuff hides. It's modules for handling XML data with XSD compilation. yes. XML. the final boss. but we're gonna slay it together, i promise. 🎀

✨ NAME ✨

Catmandu::XSD — Modules for handling XML data with XSD compilation. that's the whole vibe. XML in, XML out, but with rules this time. 💅

🌸 SYNOPSIS 🌸

okay so here's the whole group chat of usage patterns. read it like a recipe, because it basically is one.

Converting XML to YAML/JSON/CSV/etc

## Converting XML to YAML/JSON/CSV/etc

# Compile an XSD schema file and parse one shiporder.xml file
catmandu convert XSD --root '{}shiporder'
                     --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 '{}shiporder'
                     --schemas demo/order/*.xsd
                     --files 'data/*.xml'
                     to YAML

# Same as above but all array of records are in a XML container file
catmandu convert XSD --root '{}shiporder'
                     --schemas demo/order/*.xsd
                     --xpath '/Container/List//Record/Payload/*'
                     to YAML < data/container.xml

Convert an YAML/JSON/CSV into XML validated against an XSD schemas

## Convert an YAML/JSON/CSV into XML validated against an XSD schemas

# Convert one shiporder YAML to XML
catmandu convert YAML to XSD --root '{}shiporder'
                             --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 '{}shiporder'
                             --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 'xml' key which can be retrieved in the
# template by [% xml %])
catmandu convert YAML to XSD --root '{}shiporder'
                             --schemas demo/order/*.xsd
                             --template_before t/xml_header.tt
                             --template t/xml_record.tt
                             --template t/xml_footer.tt
                             < shiporder.YAML

Example documents

 ## 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

💜 DESCRIPTION 💜

Catmandu::XSD contains modules for handling XML data within the Catmandu framework. Parsing and serializing is based on XML::Compile. no cap. 🔥

There are two modules available for handling XML data in the Catmandu framework: Catmandu::XML and Catmandu::XSD. The former one — that's Catmandu::XML, bestie — can be used when no XML schema is available for the data. It provides a simple interface to read in XML data and transform it to other formats. But here's the thing: because Catmandu::XML doesn't depend on an XSD schema, it literally can't know which fields in the input XML files are sequences or single value elements. 😭 Each record is parsed on its own. (main character energy but make it lonely.)

So a record with content:

<foo>
  <bar>test</bar>
</foo>

will be parsed into a YAML output like:

catmandu XML to YAML < test.xml
--
bar: test

And a record with content:

<foo>
  <bar>test</bar>
  <bar>test</bar>
</foo>

will be parsed into a YAML output like:

catmandu XML to YAML < test2.xml
--
bar:
  - test
  - test

In the first case 'bar' will contain a string, in the second case an array. And that might not be what you want in some programming projects. 👀 E.g. when you need the 'bar' field to be always an array of values, then an XSD schema file is required, containing the exact structure of the XML document:

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>

And now the test.xml and test2.xml can be parsed with help of Catmandu::XSD:

catmandu XSD --root '{}foo' --schemas test.xsd to YAML < test.xml
--
bar:
  - test

catmandu XSD --root '{}foo' --schemas test.xsd to YAML < test2.xml
--
bar:
  - test
  - test

see? consistent. iconic. both of them are arrays now. we love a schema. ✨

🦋 WILDCARDS 🦋

Some XSD Schema allow for "any" or "anyAttribute" specifications in the schema. And in these cases the Catmandu::XSD modules can't guess what the schema implementation is. 🫠 These nodes will be parsed as XML::LibXML::Nodes in the resulting documents. And Catmandu output formats such as Catmandu::Exporter::JSON can't handle these XML::LibXML::Node nodes. so you have to implement yourself a Catmandu::Fix to translate these values into plain string, array or hash elements. no shortcuts, bestie. 😭

But in general a round trip should be problematic:
catmandu XSD --root ... --schema wildcard.xsd to XSD  --root ... --schema wildcard.xsd < data.xml

🎀 MIXED ELEMENTS 🎀

ComplexType and ComplexContent in the XSD schema can be declared with the <mixed="true"> attribute. This means that in the XML documents simple text and XML elements can be mixed, like:

      Hello, I'm <name>John</name> how can I <bold>help</bold> you?

In these cases it is not known if the elements are required as a hash or should be ignored. 🙈 By default Catmandu::XSD will parse these elements as XML::LibXML::Nodes documents. This behaviour can be changed by setting the 'mixed' flag:

# 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'm <name>John</name> how can I <bold>help</bold> you?
#
#  =>  Hello, I'm 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'm <name>John</name> how can I <bold>help</bold> you?
#
#  =>  { name => 'John' , bold => 'help' }
catmandu XSD --root ... --schema mixed.xsd --mixed STRUCTURAL < data.xml

# The mixed elements will be a plain XML fragment string
#
#  Hello, I'm <name>John</name> how can I <bold>help</bold> you?
#
#  =>  $r = 'Hello, I'm <name>John</name> how can I <bold>help</bold> you?'
catmandu XSD --root ... --schema mixed.xsd --mixed XML_STRING < data.xml

so: TEXTUAL keeps the words, STRUCTURAL keeps the tags, XML_STRING keeps literally everything as a string. pick your fighter. 💅

💅 MODULES 💅

  • Catmandu::Importer::XSD — Parse and validate XML data using an XSD file for structural data. 📥
  • Catmandu::Exporter::XSD — Serialize and validate XML data using an XSD file for structural data. 📤
  • Catmandu::Fix::xpath_map — Map XML from XSD-any elements into data fields using XPath expressions. 🗺️

three little modules, all doing their part. 🫶

🙋 BUGS, QUESTIONS, HELP 🙋

Use the github issue tracker for any bug reports or questions on this module: https://github.com/LibreCat/Catmandu-XSD/issues

(they're nice, i promise. go ask. it's giving community.) 💖

🌈 DISCLAIMER 🌈

This module is based on XML::Compile and the Catmandu framework.

XML::Compile is the workhorse that forms the core of this module to compile XSD file into parser and serializers. 🐎

Catmandu is used to transform parsed XML into any format you like. Catmandu contains a simple DSL language called Catmandu::Fix to create small scripts to manipulate data. The Catmandu toolkit is used by many university libraries to process metadata collections. 👑 (yes, actual libraries. actual metadata. actual heroes.)

For more information on Catmandu visit: http://librecat.org/Catmandu/ or follow the blog posts at: https://librecatproject.wordpress.com/

⭐ AUTHOR ⭐

Patrick Hochstenbach , "patrick.hochstenbach at ugent.be"

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.

👑 SEE ALSO 👑

  • XML::Compile
  • Catmandu
  • Template
  • Catmandu::XML

okay bestie that's the whole page, start to finish, nothing skipped, periodt. 💅

and for the cute sign-off: this whole thing ships with perl v5.36.0 and was last touched on 2022-11-29, filed under Catmandu::XSD(3pm). go forth and validate your XML. 🦋✨🎀

📦 where this page comes from