XML::C...Schema(3pm)

📦

version 1.64 · 3 versions

1.64 · debian trixie, ubuntu resolute, ubuntu stonking (latest)
1.63 · ubuntu jammy
1.63 · debian bookworm, ubuntu noble

, in debian trixie, ubuntu resolute, ubuntu stonking

💅 NAME 💅

XML::Compile::Schema — bestie, it compiles a schema into CODE. That's it, that's the whole job. 🎀

🌸 INHERITANCE 🌸

okay so here's the family tree, keep up:

XML::Compile::Schema
  is a XML::Compile

XML::Compile::Schema is extended by
  XML::Compile::Cache

so it's a child of XML::Compile, and XML::Compile::Cache is its glow-up. ✨

🦋 SYNOPSIS 🦋

here's the vibe, all the ways you can use this thing:

# compile tree yourself
my $parser = XML::LibXML->new;
my $tree   = $parser->parse...(...);
my $schema = XML::Compile::Schema->new($tree);

# get schema from string
my $schema = XML::Compile::Schema->new($xml_string);

# get schema from file (most used)
my $schema = XML::Compile::Schema->new($filename);
my $schema = XML::Compile::Schema->new([glob "*.xsd"]);

# the "::Cache" extension has more power
my $schema = XML::Compile::Cache->new(\@xsdfiles);

# adding more schemas, from parsed XML
$schema->addSchemas($tree);

# adding more schemas from files
# three times the same: well-known url, filename in schemadir, url
# Just as example: usually not needed.
$schema->importDefinitions('http://www.w3.org/2001/XMLSchema');
$schema->importDefinitions('2001-XMLSchema.xsd');
$schema->importDefinitions(SCHEMA2001);  # from ::Util

# alternatively
my @specs  = ('one.xsd', 'two.xsd', $schema_as_string);
my $schema = XML::Compile::Schema->new(\@specs); # ARRAY!

# see what types are defined
$schema->printIndex;

# create and use a reader
use XML::Compile::Util qw/pack_type/;
my $elem   = pack_type 'my-namespace', 'my-local-name';
               # $elem eq "{my-namespace}my-local-name"
my $read   = $schema->compile(READER => $elem);
my $data   = $read->($xmlnode);
my $data   = $read->("filename.xml");

# when you do not know the element type beforehand
use XML::Compile::Util qw/type_of_node/;
my $elem   = type_of_node $xml->documentElement;
my $reader = $reader_cache{$type}               # either exists
         ||= $schema->compile(READER => $elem); #   or create
my $data   = $reader->($xmlmsg);

# create and use a writer
my $doc    = XML::LibXML::Document->new('1.0', 'UTF-8');
my $write  = $schema->compile(WRITER => '{myns}mytype');
my $xml    = $write->($doc, $hash);
$doc->setDocumentElement($xml);

# show result
print $doc->toString(1);

# to create the type nicely
use XML::Compile::Util qw/pack_type/;
my $type   = pack_type 'myns', 'mytype';
print $type;  # shows  {myns}mytype

# using a compiled routines cache
use XML::Compile::Cache;   # separate distribution
my $schema = XML::Compile::Cache->new(...);

# Show which data-structure is expected
print $schema->template(PERL => $type);

# Error handling tricks with Log::Report
use Log::Report mode => 'DEBUG';  # enable debugging
dispatcher SYSLOG => 'syslog';    # errors to syslog as well
try { $reader->($data) };         # catch errors in $@

✨ DESCRIPTION ✨

so, this module collects knowledge about one or more schemas. The absolute main character method here is compile(), which can create XML file readers and writers based on the schema information and some selected element or attribute type. 👑

Various implementations use the translator, and more can be added later:

"$schema->compile('READER'...)" translates XML to HASH — The XML reader produces a HASH from a XML::LibXML::Node tree or an XML string. Those represent the input data. The values are checked. An error produced when a value or the data-structure is not according to the specs.

The CODE reference which is returned can be called with anything accepted by dataToXML().

Example: create an XML reader

my $msgin  = $rules->compile(READER => '{myns}mytype');
# or  ...  = $rules->compile(READER => pack_type('myns', 'mytype'));
my $xml    = $parser->parse("some-xml.xml");
my $hash   = $msgin->($xml);

my $hash   = $msgin->('some-xml.xml');
my $hash   = $msgin->($xml_string);
my $hash   = $msgin->($xml_node);

with XML::Compile::Cache as schema object:

$rules->addPrefix(m => 'myns');
my $hash   = $rules->reader('m:mytype')->($xml);

"$schema->compile('WRITER', ...)" translates HASH to XML — The writer produces schema compliant XML, based on a Perl HASH. To get the data encoding correctly, you are required to pass a document object in which the XML nodes may get a place later.

Create an XML writer

my $doc    = XML::LibXML::Document->new('1.0', 'UTF-8');
my $write  = $schema->compile(WRITER => '{myns}mytype');
my $xml    = $write->($doc, $hash);
print $xml->toString;

alternative

my $write  = $schema->compile(WRITER => 'myns#myid');

with XML::Compile::Cache as schema object:

$rules->addPrefix(m => 'myns');
my $xml    = $rules->writer('m:mytype')->($doc, $hash);

"$schema->template('XML', ...)" creates an XML example — Based on the schema, this produces an XML message as example. Schemas are usually so complex that people loose overview. This example may put you back on track, and used as starting point for many creating the XML version of the message.
"$schema->template('PERL', ...)" creates an Perl example — Based on the schema, this produces an Perl HASH structure (a bit like the output by Data::Dumper), which can be used as template for creating messages. The output contains documentation, and is usually much clearer than the schema itself.
"$schema->template('TREE', ...)" creates a parse tree — To be able to produce Perl-text and XML examples, the templater generates an abstract tree from the schema. That tree is returned here. Be warned that the structure is not fixed over releases: add regression tests for this to your project. 😭

Be warned that the schema is not validated; you can develop schemas which do work well with this module, but are not valid according to W3C. In many cases, however, the translater will refuse to accept mistakes: mainly because it cannot produce valid code. 💀

The values (both for reading as for writing) are strictly validated. However, the reader is sloppy with unexpected attributes, and many other things: that's too expensive to check. 🙈

Extends "DESCRIPTION" in XML::Compile.

🔥 METHODS 🔥

Extends "METHODS" in XML::Compile.

🎀 Constructors 🎀

Extends "Constructors" in XML::Compile.

XML::Compile::Schema->new( [$xmldata], %options ) — Details about many name-spaces can be organized with only a single schema object (actually, the data is administered in an internal XML::Compile::Schema::NameSpaces object)

The initial information is extracted from the $xmldata source. The $xmldata can be anything what is acceptable by importDefinitions(), which is everything accepted by dataToXML() or an ARRAY of those things. You may also add any OPTION accepted by addSchemas() to guide the understanding of the schema. When no $xmldata is provided, you can add it later with importDefinitions()

You can specify the hooks before you define the schemas the hooks work on: all schema information and all hooks are only used when the readers and writers get compiled. 🫶

 -Option            --Defined in     --Default
  block_namespace                      []
  hook                                 undef
  hooks                                []
  ignore_unused_tags                   <false>
  key_rewrite                          []
  parser_options      XML::Compile     <many>
  schema_dirs         XML::Compile     undef
  typemap                              {}

block_namespace => NAMESPACE|TYPE|HASH|CODE|ARRAY — See blockNamespace()
hook => $hook|ARRAY — See addHook(). Adds one $hook (HASH) or more at once.
hooks => ARRAY — Add one or more hooks. See addHooks().
ignore_unused_tags => BOOLEAN|REGEXP — (WRITER) Usually, a "mistake" warning is produced when a user provides a data structure which contains more data than is needed for the XML message which is created; this will show structural problems. However, in some cases, you may want to play tricks with the data-structure and therefore disable this precausion.

With a REGEXP, you can have more control. Only keys which do match the expression will be ignored silently. Other keys (usually typos and other mistakes) will get reported. See "Typemaps"

key_rewrite => HASH|CODE|ARRAY — Translate XML element local-names into different Perl keys. See "Key rewrite".
parser_options => HASH|ARRAY
schema_dirs => $directory|ARRAY-OF-directories
typemap => HASH — HASH of Schema type to Perl object or Perl class. See "Typemaps", the serialization of objects.

🌈 Accessors 🌈

Extends "Accessors" in XML::Compile.

$obj->addHook($hook|LIST|undef) — A $hook is specified as HASH or a LIST of PAIRS. When "undef", this call is ignored. See addHooks() and "Schema hooks" below.
$obj->addHooks( $hook, [$hook, ...] ) — Add multiple hooks at once. These must all be HASHes. See "Schema hooks" and addHook(). "undef" values are ignored.
$obj->addKeyRewrite($predef|CODE|HASH, ...) — Add new rewrite rules to the existing list (initially provided with new(key_rewrite)). The whole list of rewrite rules is returned.

"PREFIXED" rules will be applied first. Special care is taken that the prefix will not be called twice. The last added set of rewrite rules will be applied first. See "Key rewrite".

$obj->addSchemaDirs(@directories|$filename)
XML::Compile::Schema->addSchemaDirs(@directories|$filename) — Inherited, see "Accessors" in XML::Compile
$obj->addSchemas($xml, %options) — Collect all the schemas defined in the $xml data. The $xml parameter must be a XML::LibXML node, therefore it is advised to use importDefinitions(), which has a much more flexible way to specify the data.

When the object extends XML::Compile::Cache, the prefixes declared on the schema element will be taken as default prefixes. 👑

 -Option                --Default
  attribute_form_default  <undef>
  element_form_default    <undef>
  filename                undef
  source                  undef
  target_namespace        <undef>

attribute_form_default => 'qualified'|'unqualified'
element_form_default => 'qualified'|'unqualified' — Overrule the default as found in the schema. Many old schemas (like WSDL11 and SOAP11) do not specify the correct default element form in the schema but only in the text.
filename => FILENAME — okay so you literally just tell it which file the data is coming from. Spelled out. No guessing. 💅
source => STRING — a lil note about where this schema data was actually found. Pro tip: if you call dataToXML() in LIST context, you get exactly this kind of indication handed to you. 🎀
target_namespace => NAMESPACE — overrule (or just, like, set) the target namespace inside the schema. Main character move, honestly. 👑

💖 `$obj->addTypemap(PAIR)`

Synonym for addTypemap(). Yeah bestie, same thing, different name — it's giving alias energy. 🦋

💖 `$obj->addTypemaps(PAIRS)`

Adds new XML-Perl type relations. Go read the "Typemaps" section for the whole tea. ✨

💖 `$obj->blockNamespace($ns|$type|HASH|CODE|ARRAY)`

Blocks all references to a $ns or a full $type, as if they literally do not appear in the schema at all. Not me erasing things from existence 😭. This is specially useful when the schema includes references to old (deprecated) versions of itself that nobody's using anymore. You can also use it to block inclusion of huge structures you don't need — which gives you increased compile performance — or to dodge buggy constructs. 🚫

These values can also be passed with new(block_namespace) and compile(block_namespace).

💖 `$obj->hooks( [<'READER'|'WRITER'>] )`

Returns the LIST of defined hooks (as HASHes). [1.36] When an action parameter is provided, it will only return a list with hooks added with that action value — or no action at all.

💖 `$obj->useSchema( $schema, [$schema, ...] )`

Pass a XML::Compile::Schema object, or extensions like XML::Compile::Cache, to be used as definitions as well. So here's the order of operations: first, elements are looked-up in the current schema definition object. If they're not found, the other provided $schema objects get checked in the order as they were added. First come, first served, periodt. ✨

Heads up: searches for definitions do not recurse into schemas which are used by the used schema. No going deeper, bestie. 🙈

example: use other Schema

  my $wsdl = XML::Compile::WSDL->new($wsdl);
  my $geo  = Geo::GML->new(version => '3.2.1');
  # both $wsdl and $geo extend XML::Compile::Schema

  $wsdl->useSchema($geo);

🧚 Compilers

Extends "Compilers" in XML::Compile.

⭐ `$obj->compile( <'READER'|'WRITER'>, $type, %options )`

Translate the specified ELEMENT (found in one of the read schemas) into a CODE reference which is able to translate between XML-text and a HASH. And when the $type is undef, an empty LIST is returned. That's it, that's the deal. 💅

The indicated $type is the starting-point for processing in the data-structure — a toplevel element or attribute name. The name must be specified in {url}name format, there the url is the name-space. An alternative is the url#id which refers to an element or type with the specific id attribute value. Two ways to do the thing, pick your fave. 🌸

When a READER is created, a CODE reference is returned which needs to be called with XML, as accepted by XML::Compile::dataToXML(). Returned is a nested HASH structure which contains the data from contained in the XML. The transformation rules are explained below. 👇

When a WRITER is created, a CODE reference is returned which needs to be called with an XML::LibXML::Document object and a HASH, and returns a XML::LibXML::Node.

Many %options below are explained in more detailed in the manual-page XML::Compile::Translate, which implements the compilation.

 -Option                        --Default
  abstract_types                  'ERROR'
  any_attribute                   undef
  any_element                     undef
  any_type                        <returns string or node>
  attributes_qualified            <undef>
  block_namespace                 []
  check_occurs                    <true>
  check_values                    <true>
  default_values                  <depends on backend>
  elements_qualified              <undef>
  hook                            undef
  hooks                           undef
  ignore_facets                   <false>
  ignore_unused_tags              <false>
  include_namespaces              <true>
  interpret_nillable_as_optional  <false>
  json_friendly                   <false>
  key_rewrite                     []
  mixed_elements                  'ATTRIBUTES'
  namespace_reset                 <false>
  output_namespaces               undef
  path                            <expanded name of type>
  permit_href                     <false>
  prefixes                        {}
  sloppy_floats                   <false>
  sloppy_integers                 <false>
  typemap                         {}
  use_default_namespace           <false>
  validation                      <true>
  xsi_type                        {}
  xsi_type_everywhere             <false>

abstract_types => 'ERROR'|'ACCEPT' — how to handle the use abstract types. Of course, they should not be used, but sometime they accidentally are. 🙈 When set to ERROR, an error will be produced whenever an abstract type is encountered. ACCEPT will ignore the fact that the types are abstract, and treat them as non-abstract types. Living in denial, slay. ✨
any_attribute => CODE|'TAKE_ALL'|'SKIP_ALL' — [0.89, reader] In general, anyAttribute schema components cannot be handled automatically. If you need to create or process anyAttribute information, then read about wildcards in the DETAILS chapter of the manual-page for the specific back-end. [pre-0.89] this option was named anyElement, which will still work. Legacy support, we love to see it. 💜
any_element => CODE|'TAKE_ALL'|'SKIP_ALL' — [0.89, reader] In general, any schema components cannot be handled automatically. If you need to create or process any information, then read about wildcards in the DETAILS chapter of the manual-page for the specific back-end. [pre-0.89] this option was named anyElement, which will still work. Same vibe, different spelling. 🦋
any_type => CODE — [1.07] how to handle anyType type elements. Supported values depends on the backend, specializations of XML::Compile::Translate. 🎀
attributes_qualified => "ALL"|"NONE"|BOOLEAN — [1.44] Like option elements_qualified, but then for attributes. That's literally the whole thing. 💅
block_namespace => NAMESPACE|TYPE|HASH|CODE|ARRAY — [reader] See blockNamespace(). Go look it up bestie, we covered it above. 👆
check_occurs => BOOLEAN — whether code will be produced to do bounds checking on elements and blocks which may appear more than once. When the schema says that maxOccurs is 1, then that element becomes optional. When the schema says that maxOccurs is larger than 1, then the output is still always an ARRAY, but now of unrestricted length. Counting things, so fun. 🔢
check_values => BOOLEAN — whether code will be produce to check that the XML fields contain the expected data format.

Turning this off will improve the processing speed significantly, but is (of course) much less safe. Do not set it off when you expect data from external sources: validation is a crucial requirement for XML.

fr fr, don't be reckless with this one. 😭

default_values => 'MINIMAL'|'IGNORE'|'EXTEND' — [reader] How to treat default values as provided by the schema. With IGNORE (the writer default), you will see exactly what is specified in the XML or HASH. With EXTEND (the reader default) will show the default and fixed values in the result. MINIMAL does remove all fields which are the same as the default setting: simplifies. See "Default Values". ✨
elements_qualified => "TOP"|"ALL"|"NONE"|BOOLEAN — when defined, this will overrule the use of namespaces (as prefix) on elements in all schemas. When ALL or a true value is given, then all elements will be used qualified. When NONE or a false value is given, the XML will not produce or process prefixes on any element. 🌈

All top-level elements (and attributes) will be used in a name-space qualified way, if they have a targetNamespace. Some applications require some global element with qualification, so refuse global elements which have no qualification. Using the TOP setting, the compiler checks that the targetNamespace exists.

The form attributes in the schema will be respected; overrule the effects of this option. Use hooks when you need to fix name-space use in more subtile ways.

With element_form_default, you can correct whole schema's about their name-space behavior.

Change in [1.44]: TOP before enforced a name-space on the top-level. There should always be a name-space on the top element. It got changed into that TOP checks that the globals have a targetNamespace. Glow-up era. 👑

hook => $hook|ARRAY-OF-hooks — define one or more processing $hooks. See "Schema hooks" below. These hooks are only active for this compiled entity, where addHook() and addHooks() can be used to define hooks which are used for all results of compile(). The hooks specified with the hook or hooks option are run before the global definitions. Order matters, iykyk. 🪝
hooks => $hook|ARRAY-OF-hooks — alternative for option hook. Same energy, different key. 💅
ignore_facets => BOOLEAN — facets influence the formatting and range of values. This does not come cheap, so can be turned off. It affects the restrictions set for a simpleType. The processing speed will improve, but validation is a crucial requirement for XML: please do not turn this off when the data comes from external sources.

bestie please. I am begging. 🥺

ignore_unused_tags => BOOLEAN|REGEXP — [writer] Overrules what is set with new(ignore_unused_tags). 🎀
include_namespaces => BOOLEAN|CODE — [writer] Indicates whether the namespace declaration should be included on the top-level element. If not, you may continue with the same name-space table to combine various XML components into one, and add the namespaces later. No namespace definition can be added the production rule produces an attribute. 🦋

When a CODE reference is passed, it will be called for each namespace to decide whether it should be included or not. When true, it will we added. The CODE is called with a namespace, its prefix, and the number of times it was used for that schema element translator. Custom decisions, main character behaviour. ✨

interpret_nillable_as_optional => BOOLEAN — found in the schema wild-life: people who think that nillable means optional. Not too hard to fix. For the WRITER, you still have to state NIL explicitly, but the elements are not constructed. The READER will output NIL when the nillable elements are missing. The chaos out there is real, bestie. 💀
json_friendly => BOOLEAN — [1.55] flip this on and booleans get blessed into Types::Serialiser booleans, plus floats get nummified. Together? The reader's output is literally usable as JSON with no further conversion. Not me making your pipeline easier, it just is 💅
key_rewrite => HASH|CODE|ARRAY — adds key rewrite rules to the front of the rules list, the one set up by new(key_rewrite) and addKeyRewrite(). Go read "Key rewrite" for the whole vibe 🎀
mixed_elements => CODE|PREDEFINED — [reader] what even do we do when mixed schema elements come through to be processed? The full tea is in the "DETAILS" section below 🫖
namespace_reset => BOOLEAN — [writer] use the same prefixes in "prefixes" as some other compiled piece does, but reset the counts to zero first 🔄
output_namespaces => HASH|ARRAY-of-PAIRS — [Pre-0.87] this was the name for the "prefixes" option. It's deprecated, bestie, let it go 🪦
path => STRING — gets prepended to every error report so you know where in the XML-Scheme tree the error happened 📍
permit_href => BOOLEAN — [reader] when you're parsing SOAP-RPC encoded messages, elements might carry a href attribute pointing at an object that has an id. The READER will hand you back the unparsed, unresolved node the second it spots that attribute, and then the SOAP-RPC decoder has to go discover and resolve it itself 🔍
prefixes => HASH|ARRAY-of-PAIRS — pre-define prefixes for namespaces (for 'WRITER' or key rewrite), like reserving common abbreviations such as soap for external use. Every entry in the hash has the namespace uri as its key. The value is a hash holding uri, prefix, and used fields. Pass a reference to a private hash to catch this index. An ARRAY of prefix, uri PAIRS is simpler tho:

prefixes => [ mine => $myns, two => $twons ]
prefixes => { $myns => 'mine', $twons => 'two' }

# the previous is short for:
prefixes => { $myns  => [ uri => $myns, prefix => 'mine', used => 0 ]
            , $twons => [ uri => $twons, prefix => 'two', ...] };

sloppy_floats => BOOLEAN — [reader] the float types of XML are all quite big and they support NaN, INF, and -INF. Perl's normal floats do not, which is why Math::BigFloat gets dragged in. And that, bestie, is slow. Set this true and you'll crash on any value Perl's default float doesn't understand... but it runs much faster. Peep "sloppy_integers" too 👀
sloppy_integers => BOOLEAN — [reader] the XML integer data-types have to support at least 18 digits, which is way bigger than Perl's 32 bit internal integers. So the implementation uses Math::BigInt objects to handle them. But like, often a plain int type whould have sufficed and the XML designer was just lazy. A long is much faster to handle. Set this flag to use int as a fast (but inprecise) replacement.

Be aware that Math::BigInt and Math::BigFloat objects are nearly but not fully transparently mimicking Perl's ints and floats. Read their respective manual-pages. Especially if you want performance, optimize access to these objects so you dodge the expensive copying — that's exactly where the differences live.

You can also speed up Math::BigInt by installing Math::BigInt::GMP. Drop use Math::BigInt try => 'GMP'; at the top of your main script for more performance 🚀

typemap => HASH — adds this typemap to the relations defined by new(typemap) or addTypemaps() 🗺️
use_default_namespace => BOOLEAN — [0.91, writer] when you're mixing qualified and unqualified namespaces, a default namespace (a name-space with no prefix) gets super confusing. So by default, all qualified elements get an explicit prefix. Periodt ✋
validation => BOOLEAN — the XML message must be validated, to lower the chance of abuse. Which obviously costs performance, only partially compensated by having fewer checks in your own code. This flag overrules check_values, check_occurs, and ignore_facets 🛡️
xsi_type => HASH — see "Handling xsi:type". The HASH maps types as mentioned in the schema to extensions of those types which get addressed through the horrible xsi:type construct. If you give AUTO as the value for some type, the translator tries to collect possible xsi:type values from the loaded schemas. That may be slow and may produce imperfect results 🙈
xsi_type_everywhere => BOOLEAN — [1.48, writer] slap an xsi:type attribute onto all elements, like what SOAP RPC/encoded uses. The type added is the type according to the schema — unless the xsi:type is already sitting on that element for some other reason.

Be aware this option has a different purpose from xsi_type. Here, we add exactly the type specified in the xsd to every element that doesn't have an xsi:type attribute yet. xsi_type, on the other hand, implements the (mis-)feature where an element's content may get replaced by any extended type carrying that dynamic flag 🔀

$obj->compileType( <'READER'|'WRITER'>, $type, %options )

This one is a hack so we can process components of SOAP messages that are only specified by type. Probably (hopefully) you do not need it 🙏 All %options are the same as for compile().

Inherited, see "Compilers" in XML::Compile 💫

$obj->initParser(%options) XML::Compile::Schema->initParser(%options)

Inherited, see "Compilers" in XML::Compile 💫

$obj->template( <'XML'|'PERL'|'TREE'>, $element, %options )

Schemas can be horribly complex and unreadible. So this template method exists: call it and it builds an example showing how data of the specified $element — shown as XML or Perl — is organized in practice 🧚

The 'TREE' template returns the intermediate parse tree, which then gets formatted into the XML or Perl example. Heads up: this is not a stable interface, it may change without much notice 💀

Some %options are explained in XML::Compile::Translate. There are some extra %options defined for the final output process.

The templates produced are not always correct. Please contribute improvements: read and understand the comments in the text 🫶

-Option --Default
 abstract_types        'ERROR'
 attributes_qualified  <undef>
 elements_qualified    <undef>
 include_namespaces    <true>
 indent                " "
 key_rewrite           []
 output_style          1
 show_comments         ALL
 skip_header           <false>

abstract_types => 'ERROR'|'ACCEPT' — by default, abstract types do not show up in the output 🙅
attributes_qualified => BOOLEAN
elements_qualified => 'ALL'|'TOP'|'NONE'|BOOLEAN
include_namespaces => BOOLEAN|CODE
indent => STRING — the leading indentation string per nesting level. Must start with at least one blank.
key_rewrite => HASH|CODE|ARRAY
output_style => 1|2 — [1.61] style 2 is a little different 💅
show_comments => STRING|'ALL'|'NONE' — a comma separated list of tokens explaining which kinds of comments get included in the output. The available tokens are: struct, type, occur, facets. A value of ALL selects all available comments. NONE or an empty string excludes all comments 🗒️
skip_header => BOOLEAN — skips the comment header from the output ✂️

✨ Administration ✨

Extends "Administration" in XML::Compile.

$obj->doesExtend($exttype, $basetype)

Returns true when the $exttype extends the $basetype. See XML::Compile::Schema::NameSpaces::doesExtend() 🧬

$obj->elements()

Lists all elements, defined by all schemas, sorted alphabetically 🔤

$obj->findSchemaFile($filename) XML::Compile::Schema->findSchemaFile($filename)

Inherited, see "Administration" in XML::Compile 💫

$obj->importDefinitions($xmldata, %options)

Imports (includes) the schema information that lives inside $xmldata. The $xmldata must be acceptable for dataToXML(). The resulting node and all the %options get passed along to addSchemas(). The schema node does not need to be the top element: any schema node found in the data will be decoded 🔎

What you get back is a list of XML::Compile::Schema::Instance objects, one for each processed schema component 📦

If your program imports the same string or file definitions multiple times, it will re-use the schema information from the first import. This removal of duplications will not work for open files or pre-parsed XML structures.

As an extension to the handling dataToXML() provides, you can specify an ARRAY of things which are acceptable to dataToXML. That way you can specify multiple resources at once, and each one gets processed with the same %options 🌈

-Option --Default
 details  <from XMLDATA>

details => HASH — overrules the details information about the source of the data 📝

Example: of use of importDefinitions

my $schema = XML::Compile::Schema->new;
$schema->importDefinitions('my-spec.xsd');

my $other = "<schema>...</schema>";  # use 'HERE' documents!
my @specs = ('my-spec.xsd', 'types.xsd', $other);
$schema->importDefinitions(\@specs, @options);

$obj->knownNamespace($ns|PAIRS) XML::Compile::Schema->knownNamespace($ns|PAIRS)

Inherited, see "Administration" in XML::Compile 💫

$obj->namespaces()

Returns the XML::Compile::Schema::NameSpaces object which is used to collect schemas 🗂️

$obj->printIndex( [$fh], %options )

Prints all the elements defined in the schemas to the $fh (by default the selected handle). The %options get passed to XML::Compile::Schema::NameSpaces::printIndex() and XML::Compile::Schema::Instance::printIndex() 🖨️

$obj->types()

Lists all types, defined by all schemas, sorted alphabetically 🔤

$obj->walkTree($node, CODE)

Inherited, see "Administration" in XML::Compile 💫

🌈 DETAILS 🌈

Extends "DETAILS" in XML::Compile.

🦋 Distribution collection overview 🦋

Extends "Distribution collection overview" in XML::Compile.

🍓 Comparison 🍓

Extends "Comparison" in XML::Compile.

✨ Collecting definitions ✨

ok so bestie, when you start an app you gotta read the schema definitions first, that's just the vibe. You do it by making an object with XML::Compile::Schema::new() or XML::Compile::WSDL11::new(). And heads up — the WSDL11 object has a schema object chilling inside it. 🫶

Schemas can have import and include statements that point at other resources for definitions. The XML design team's whole idea was that those files get pulled in automatically over an internet connection from the schemaLocation. And like… no. That's a bad concept, fr fr. In XML::Compile modules you have to explicitly hand over filenames on your local disk using importDefinitions() or XML::Compile::WSDL11::addWSDL().

And I (the author of this module, hi 👋) have multiple reasons why those dynamic automatic internet imports are a terrible idea:

You do not always have a working internet connection. Picture me on a train with a laptop, bestie. Your implementation should behave the exact same way under all environmental circumstances! Periodt.
I do not trust remote files on my system without inspecting them first. Nope.
Most important one: I want to run my regression tests before using a new version of the definitions. I am not letting a remote server change the agreements behind my back, no thank you. 💅

So here's the plan: before you start, scan (recursively 🔁) the initial schema or wsdl file for import and include statements, and collect all those files from their schemaLocation into files on your local disk. Then in your program, call importDefinitions() on all of them — in any order — before you call compile().

🎀 Organizing your definitions 🎀

One genuinely nice feature that helps you organize everything (especially slay when you package your code in a distribution) is adding these lines to the top of your code:

package My::Package;
XML::Compile->addSchemaDirs(__FILE__);
XML::Compile->knownNamespace('http://myns' => 'myns.xsd', ...);

So now, if the package file lives at SomeThing/My/Package.pm, the definition of that namespace should be kept in SomeThing/My/Package/xsd/myns.xsd. Cute, right? ✨

Somewhere in your program you gotta load these definitions:

# absolute or relative path is always possible
$schema->importDefinitions('SomeThing/My/Package/xsd/myns.xsd');

# relative search path extended by addSchemaDirs
$schema->importDefinitions('myns.xsd');

# knownNamespace improves abstraction
$schema->importDefinitions('http://myns');

And very probably the namespace is already sitting in some variable anyway:

use XML::Compile::Schema;
use XML::Compile::Util  'pack_type';

my $myns   = 'http://some-very-long-uri';
my $schema = XML::Compile::Schema->new($myns);
my $mytype = pack_type $myns, $myelement;
my $reader = $schema->compileClient(READER => $mytype);

🌸 Addressing components 🌸

Normally, external users can only address elements within a schema, and types stay hidden so other schemas can use them. And because of that, it's totally permitted to make an element and a type with the same name. No cap.

The compiler needs a starting-point, okay? That can be either an element name or an element's id. The element name format is {namespace-uri}localname, like for instance:

{http://library}book

You may also start with:

http://www.w3.org/2001/XMLSchema#float

…as long as that ID refers to a top-level element, not a type.

And when you use a schema without targetNamespace (which is bad practice, but sometimes people really do not understand the beneficial aspects of using namespaces 🙈) then the elements can be addressed as {}name or just plain name.

🦋 Representing data-structures 🦋

The code will do its best to produce a correct translation. For instance, an accidental 1.9999 gets converted into 2 when the schema says the field is an int. It will also strip superfluous blanks when the data-type permits. And especially watch out for the Integer types, which produce Math::BigInt objects unless compile(sloppy_integers) is used. 💀

Elements can be complex, and they themselves contain elements which are complex. In the Perl representation of the data, this shows up as nested hashes with the same structure as the XML.

You should not take care of character encodings — XML::LibXML is doing that for us — so you shall not escape characters like < yourself.

The schemas define kinds of data types. There are various ways to define them (with restrictions and extensions), but for the resulting data structure, that knowledge is not important. iykyk.

💖 simpleType 💖

A single value. A lot of single value data-types are built-in (see XML::Compile::Schema::BuiltInTypes).

Simple types may have range limiting restrictions (facets), which get checked by default. Types may also have some white-space behavior, for instance blanks are stripped from integers: before, after, but also inside the number representing string.

Note that some of the reader hooks will alter the single value of these elements into a HASH like used for the complexType/simpleContent (next paragraph), to be able to return some extra collected information. 🫶

. Example: typical simpleType

In XML, it looks like this:

<test1>42</test1>

In the HASH structure, the data will be represented as

test1 => 42

With reader hook after => 'XML_NODE' hook applied, it will become

test1 => { _ => 42
         , _XML_NODE => $obj
         }

🌈 complexType/simpleContent 🌈

In this case, the single value container may have attributes. The number of attributes can be endless, and the value is only one. This value has no name, and therefore gets a predefined name _.

When passed to the writer, you may specify a single value (not the whole HASH) when no attributes are used.

. typical simpleContent example

In XML, this looks like this:

<test2 question="everything">42</test2>

As a HASH, this shows as

test2 => { _ => 42
         , question => 'everything'
         }

When specified in the writer, when no attributes are needed, you can use either form:

test3 => { _ => 7 }
test3 => 7

👑 complexType and complexType/complexContent 👑

These containers not only have attributes, but also multiple values as content. The complexContent is used to create inheritance structures in the data-type definition. This does not affect the XML data package itself.

. Example: typical complexType element

The XML could look like:

<test3 question="everything" by="mouse">
  <answer>42</answer>
  <when>5 billion BC</when>
</test3>

Represented as HASH, this looks like

test3 => { question => 'everything'
         , by       => 'mouse'
         , answer   => 42
         , when     => '5 billion BC'
         }

💅 Manually produced XML NODE 💅

For a WRITER, you may also specify an XML::LibXML::Node anywhere.

test1 => $doc->createTextNode('42');
test3 => $doc->createElement('ariba');

This data-structure is used without validation, so you are fully on your own with this one. Typically, nodes are produced by hooks to implement work-arounds.

⭐ Occurence ⭐

A second factor which determines the data-structure is the element occurrence. Usually, elements have to appear once and exactly once at a certain location in the XML data structure. This order is automatically produced by this module. But elements may appear multiple times.

usual case — The default behavior for an element (in a sequence container) is to appear exactly once. When missing, this is an error.
maxOccurs larger than 1 — In this case, the element or particle block can appear multiple times. Multiple values are kept in an ARRAY within the HASH. Non-schema based XML modules do not return a single value as an ARRAY, which makes that code more complicated. But in our case, we know the expected amount beforehand.

When the maxOccurs larger than 1 is specified for an element, an ARRAY of those elements is produced. When it is specified for a block (sequence, choice, all, group), then an ARRAY of HASHes is returned. See the special section about this subject.

An error is produced when the number of elements found is less than minOccurs (defaults to 1) or more than maxOccurs (defaults to 1), unless compile(check_occurs) is false.

Example elements with maxOccurs larger than 1. In the schema:

<element name="a" type="int" maxOccurs="unbounded" />
<element name="b" type="int" />

In the XML message:

<a>12</a><a>13</a><b>14</b>

In the Perl representation:

a => [12, 13], b => 14

value is NIL — When an element is nillable, that is explicitly represented as a NIL constant string.
use="optional" or minOccurs="0" — The element may be skipped. When found it is a single value.
use="forbidden" — When the element is found, an error is produced.
default="value" — When the XML does not contain the element, the default value is used… but only if this element's container exists. This has no effect on the writer.
fixed="value" — Produce an error when the value is not present or different (after the white-space rules where applied).

🎀 Default Values 🎀

[added in v0.91] With compile(default_values) you can control how much information about default values defined by the schema will be passed into your program.

The choices, available for both READER and WRITER, are:

IGNORE (the WRITER's standard behavior) — Only include element and attribute values in the result if they are in the XML message. Behaviorally, this treats elements with default values as if they are just optional. The WRITER does not try to be smarter than you.
EXTEND (the READER's standard behavior) — If some element or attribute is not in the source but has a default in the schema, that value will be produced. This is very convenient for the READER, because your application does not have to hard-code the same constant values as defaults as well.
MINIMAL — Only produce the values which differ from the defaults. This choice is useful when producing XML, to reduce the size of the output.

. Example: use of default_values EXTEND

Let us process a schema using the schema schema. A schema file can contain lines like this:

<element minOccurs="0" ref="myelem"/>

In mode EXTEND (the READER default), this gets translated into:

element => { ref => 'myelem', maxOccurs => 1
           , minOccurs => 0, nillable => 0 };

With EXTEND in the READER, literally all the schema info gets used so you get the full picture of everything that's available, bestie. Your code does not need to check whether the attributes were available or not: attributes with defaults or fixed values are automatically added. slay ✨

Again mode EXTEND, now for the writer:

 element => { ref => 'myelem', minOccurs => 0 };
 <element minOccurs="0" maxOccurs="1" ref="myelem" nillable="0"/>

💅 Example: use of default_values IGNORE

With option default_values set to IGNORE (the WRITER default), you would get

 element => { ref => 'myelem', maxOccurs => 1, minOccurs => 0 }
 <element minOccurs="0" maxOccurs="1" ref="myelem"/>

The same in both translation directions. The nillable attribute is not used, so will not be shown by the READER. The writer does not try to be smart, so does not add the nillable default. (it's giving "no thoughts, head empty" energy and honestly? valid)

✨ Example: use of default_values MINIMAL

With option default_values set to MINIMAL, the READER would do this:

 <element minOccurs="0" maxOccurs="1" ref="myelem"/>
 element => { ref => 'myelem', minOccurs => 0 }

The maxOccurs default is "1", so will not be included, minimalizing the size of the HASH. skinny legend behavior 🦋

For the WRITER:

 element => { ref => 'myelem', minOccurs => 0, nillable => 0 }
 <element minOccurs="0" ref="myelem"/>

because the default value for nillable is '0', it will not show as attribute value.

🌀 Repetative blocks 🌀

Particle blocks come in four shapes: sequence, choice, all, and group (an indirect block). This also affects substitutionGroups. 👑

repetative sequence, choice, all

In situations like this:

  <element name="example">
    <complexType>
      <sequence>
        <element name="a" type="int" />
        <sequence>
          <element name="b" type="int" />
        </sequence>
        <element name="c" type="int" />
      </sequence>
    </complexType>
  </element>

(yes, schemas are verbose 😭) the data structure is

  <example> <a>1</a> <b>2</b> <c>3</c> </example>

the Perl representation is flattened, into

  example => { a => 1, b => 2, c => 3 }

Ok, this is very simple. However, schemas can use repetition:

  <element name="example">
    <complexType>
      <sequence>
        <element name="a" type="int" />
        <sequence minOccurs="0" maxOccurs="unbounded">
          <element name="b" type="int" />
        </sequence>
        <element name="c" type="int" />
      </sequence>
    </complexType>
  </element>

The XML message may be:

  <example> <a>1</a> <b>2</b> <b>3</b> <b>4</b> <c>5</c> </example>

Now, the perl representation needs to produce an ARRAY of the data in the repeated block. This array needs to have a name, because more of these blocks may appear together in a construct. The name of the block is derived from the type of block and the name of the first element in the block, regardless whether that element is present in the data or not. periodt.

So, our example data is translated into (and vice versa)

  example =>
    { a     => 1
    , seq_b => [ {b => 2}, {b => 3}, {b => 4} ]
    , c     => 5
    }

The following label is used, based on the name of the first element (say xyz) as defined in the schema (not in the actual message):

seq_xyz — sequence with maxOccurs > 1
cho_xyz — choice with maxOccurs > 1
all_xyz — all with maxOccurs > 1

When you have compile(key_rewrite) option PREFIXED, and you have explicitly assigned the prefix "xs" to the schema namespace (See compile(prefixes)), then those names will respectively be "seq_xs_xyz", "cho_xs_xyz", "all_xs_xyz". 💅

🦋 Example: always an array with maxOccurs larger than 1

Even when there is only one element found, it will be returned as ARRAY (of one element). Therefore, you can write

 my $data = $reader->($xml);
 foreach my $a ( @{$data->{a}} ) {...}

🌸 Example: blocks with maxOccurs larger than 1

In the schema:

 <sequence maxOccurs="5">
   <element name="a" type="int" />
   <element name="b" type="int" />
 </sequence>

In the XML message:

 <a>15</a><b>16</b><a>17</a><b>18</b>

In Perl representation:

 seq_a => [ {a => 15, b => 16}, {a => 17, b => 18} ]

repetative groups

[behavioral change in 0.93] In contrast to the normal particle blocks, as described above, do the groups have names. In this case, we do not need to take the name of the first element, but can use the group name. It will still have gr_ appended, because groups can have the same name as an element or a type(!)

Blocks within the group definition cannot be repeated.

💜 Example: groups with maxOccurs larger than 1

 <element name="top">
   <complexType>
     <sequence>
       <group ref="ns:xyz" maxOccurs="unbounded">
     </sequence>
   </complexType>
 </element>

 <group name="xyz">
   <sequence>
     <element name="a" type="int" />
     <element name="b" type="int" />
   </sequence>
 </group>

translates into

  gr_xyz => [ {a => 42, b => 43}, {a => 44, b => 45} ]

repetative substitutionGroups

For substitutionGroups which are repeating, the name of the base element is used (the element which has attribute <abstract="true"">). We do need this array, because the order of the elements within the group may be important; we cannot group the elements based to the extended element's name.

In an example substitutionGroup, the Perl representation will be something like this:

  base-element-name =>
    [ { extension-name  => $data1 }
    , { other-extension => $data2 }
    ]

Each HASH has only one key. 🙈

List type

List simpleType objects are also represented as ARRAY, like elements with a minOccurs or maxOccurs unequal 1.

✨ Example: with a list of ints

  <test5>3 8 12</test5>

as Perl structure:

  test5 => [3, 8, 12]

Using substitutionGroup constructs

A substitution group is kind-of choice between alternative (complex) types. However, in this case roles have reversed: instead a "choice" which lists the alternatives, here the alternative elements register themselves as valid for an abstract (head) element. All alternatives should be extensions of the head element's type, but there is no way to check that. (not me pointing out the plot hole 😭)

🌺 Example: substitutionGroup

 <xs:element name="price"  type="xs:int" abstract="true" />
 <xs:element name="euro"   type="xs:int" substitutionGroup="price" />
 <xs:element name="dollar" type="xs:int" substitutionGroup="price" />

 <xs:element name="product">
   <xs:complexType>
      <xs:element name="name" type="xs:string" />
      <xs:element ref="price" />
   </xs:complexType>
 </xs:element>

Now, valid XML data is

 <product>
   <name>Ball</name>
   <euro>12</euro>
 </product>

and

 <product>
   <name>Ball</name>
   <dollar>6</dollar>
 </product>

The HASH repesentation is respectively

 product => {name => 'Ball', euro  => 12}
 product => {name => 'Ball', dollar => 6}

Wildcards via any and anyAttribute

The "any" and "anyAttribute" elements are referred to as "wildcards": they specify (huge, generic) groups of elements and attributes which are accepted, instead of being explicit. vibe check: failed, imo

The author of this module advices against the use of wildcards in schemas: the purpose of schemas is to be explicit about the message in the interface, and that basic idea is simply thrown away by these wildcards. Let people cleanly extend the schema with inheritance! There is always a substitutionGroup alternative possible. 💅

Because wildcards are not explicit about the types to expect, the XML::Compile module can not prepare for them at run-time. You need to go read the documentation and do some tricky manual work to get it to work. fr fr, no shortcut here bestie

Read about the processing of wildcards in the manual page for each of the back-ends (XML::Compile::Translate::Reader, XML::Compile::Translate::Writer, ...).

ComplexType with "mixed" attribute

[largely improved in 0.86, reader only] ComplexType and ComplexContent components can be declared with the <mixed="true""> attribute. This implies that text is not limited to the content of containers, but may also be used inbetween elements. Usually, you will only find ignorable white-space between elements.

In this example, the "a" container is marked to be mixed:

 <a> before <b>2</b> after </a>

Each back-end has its own way of handling mixed elements. The compile(mixed_elements) currently only modifies the reader's behavior; the writer's capabilities are limited. See XML::Compile::Translate::Reader.

hexBinary and base64Binary

These are used to include images and such in an XML message. Usually, they are quite large with respect to the other elements. When you use SOAP, you may wish to use XML::Compile::XOP instead.

The element values which you need to pass for fields of these types is a binary BLOB, something Perl does not have. So, it is a string containing binary data but not specially marked that way.

If you need to store an integer in such a binary field, you first have to promote it into a BLOB (string) like this

   { color => pack('N', $i) }          # writer
   my $i = unpack('N', $d->{color});   # reader

Module Geo::KML implemented a nice hook to avoid the explicit need for this "pack" and "unpack". The KML schema designers liked colors to be written as "ffc0c0c0" and abused "hexBinary" for that purpose. The "colorType" fields in KML are treated as binary, but just represent an int. Have a look in that Geo::KML code if your schema has some of those tricks. Only available in Backpan, withdrawn from CPAN. 🫶

🎀 Schema hooks 🎀

You can use hooks, for instance, to block processing parts of the message, to create work-arounds for schema bugs, or to extract more information during the process than done by default. main character energy tbh

Defining hooks

Multiple hooks can active during the compilation process of a type, when compile() is called. During Schema translation, each of the hooks is checked for all types which are processed. When multiple hooks select the object to get a modified behavior, then all are evaluated in order of definition.

Defining a global hook (where HOOKDATA is the LIST of PAIRS with hook parameters, and HOOK a HASH with such HOOKDATA):

 my $schema = XML::Compile::Schema->new
  ( ...
  , hook  => HOOK
  , hooks => [ HOOK, HOOK ]
  );

 $schema->addHook(HOOKDATA | HOOK);
 $schema->addHooks(HOOK, HOOK, ...);

 my $wsdl   = XML::Compile::WSDL->new(...);
 $wsdl->addHook(HOOKDATA | HOOK);

local hooks are only used for one reader or writer. They are evaluated before the global hooks. ✨

my $reader = $schema->compile(READER => $type
 , hook => HOOK, hooks => [ HOOK, HOOK, ...]);

okay so here's what an actual HOOK looks like in the wild 💅

my $hook = { type    => '{my_ns}my_type'
           , before  => sub { ... }
           , action  => 'WRITER'
           };

my $hook = { path    => qr/\(volume\)/
           , replace => 'SKIP'
           , action  => 'READER'
           };

# path contains "volume" or id is 'aap' or id is 'noot'
my $hook = { path    => qr/\bvolume\b/
           , id      => [ 'aap', 'noot' ]
           , before  => [ sub {...}, sub { ... } ]
           , after   => sub { ... }
           };

General syntax ✨

bestie, every single hook has three kinds of parameters, no more no less:

selectors 🎯
processors ⚙️
action — either 'READER' or 'WRITER', and it defaults to both 🫶

Selectors define the schema component of which the processing is modified. The moment one of the selectors matches, the processing information for the hook gets used. And if you specify no selector at all? Then the hook just gets used on all elements. periodt.

The selectors available to you (deets on each one below, keep reading 👇):

type
extends
id
path

As the argument, you can hand over one element as a STRING, a regular expression to select multiple elements, or an ARRAY of STRINGs and REGEXes. flexible queen 💅

Next to where the hook is placed, we gotta know what to do in that case: that's what the processing information inside the hook is for. When more than one hook matches, then all of those processors get called, in order of hook definition. BUT — and this is the tea ☕ — the compile hooks are taken first, and then the global hooks.

How the processing works exactly depends on the compiler back-end, and ngl there are major differences between them. Each of those manual-pages lists the specifics, iykyk. The label tells us when the processing is initiated. Available labels are "before", "replace", and "after". 🎀

Hooks on matching types 🦋

The "type" selector specifies a complexType of simpleType by name. Best practice fr fr is to base the selection on the full name, like "{ns}type", which will avoid all kinds of name-space conflicts in the future. However — plot twist — you may also specify only the "local type" (in any name-space). Any REGEX will be matched to the full type name. So be careful with the pattern archors, bestie. ⚠️

If you use XML::Compile::Cache [release 0.90], then you can use "prefix:type" as type specification as well. You have to explicitly define prefix to namespace beforehand. 🫡

example: use of the type selector

type => 'int'
type => '{http://www.w3.org/2000/10/XMLSchema}int'
type => qr/\}xml_/   # type start with xml_
type => [ qw/int float/ ];

use XML::Compile::Util qw/pack_type SCHEMA2000/;
type => pack_type(SCHEMA2000, 'int')

# with XML::Compile::Cache
$schema->addPrefixes(xsd => SCHEMA2000);
type => 'xsd:int'

example: type hook with XML::Compile::Cache

use XML::Compile::Util qw/SCHEMA2001/;
my $schemas = XML::Compile::Cache->new(...);
$schemas->addPrefixes(xsd => SCHEMA2001, mine => 'http://somens');
$schemas->addHook(type => 'xsd:int', ...);
$schemas->addHook(type => 'mine:sometype', ...);

Hooks on extended type 🌸

[1.48] This hook will match all elements which use a type which is equal or based on the given type. In the schema, you will find extension and restriction constructs. You may only pass a single full type (no arrays of types or local names) per 'extend' hook.

Heads up bestie: using a hooks on extended types is quite expensive for the compiler. 💀

example:

$schemas->addHook(extends => "{ns}local", ...);
$schemas->addHook(extends => 'mine:sometype', ...);  # need ::Cache

Hooks on matching ids 🎀

Matching based on IDs can reach more schema elements: some types are anonymous but still have an ID. Best is to base selection on the full ID name, like "ns#id", to avoid all kinds of name-space conflicts in the future. ✨

example: use of the ID selector

# default schema types have id's with same name
id => 'ABC'
id => 'http://www.w3.org/2001/XMLSchema#int'
id => qr/\#xml_/   # id which start with xml_
id => [ qw/ABC fgh/ ];

use XML::Compile::Util qw/pack_id SCHEMA2001/;
id => pack_id(SCHEMA2001, 'ABC')

Hooks on matching paths 🌈

When you see error messages, you always see some representation of the path where the problem was discovered. You can use this path as selector, when you know what it is...

BE WARNED, that the current structure of the path is not really consequent hence will be improved in one of the future releases, breaking backwards compatibility. 😭

Typemaps 💖

Often, XML will be used in object oriented programs, where the facts which are transported in the XML message are attributes of Perl objects. Of course, you can always collect the data from each of the Objects into the required (huge) HASH manually, before triggering the reader or writer. As an alternative, you can connect types in the XML schema with Perl objects and classes, which results in cleaner code. obsessed. 🫶

You can also specify typemaps with new(typemap), addTypemaps(), and compile(typemap). Each type will only refer to the last map for that type. When an "undef" is given for a type, then the older definition will be cancelled. Examples of the three ways to specify typemaps:

my %map = ($x1 => $p1, $x2 => $p2);
my $schema = XML::Compile::Schema->new(...., typemap => \%map);

$schema->addTypemaps($x3 => $p3, $x4 => $p4, $x1 => undef);

my $call = $schema->compile(READER => $type, typemap => \%map);

The latter only has effect for the type being compiled. The definitions are cumulative. In the second example, the $x1 gets disabled. 🚫

Objects can come in two shapes: either they do support the connection with XML::Compile (implementing two methods with predefined names), or they don't, in which case you will need to write a little wrapper. 💅

use XML::Compile::Util qw/pack_type/;
my $t1 = pack_type $myns, $mylocal;
$schema->typemap($t1 => 'My::Perl::Class');
$schema->typemap($t1 => $some_object);
$schema->typemap($t1 => sub { ... });

The implementation of the READER and WRITER differs. In the READER case, the typemap is implemented as an 'after' hook which calls a "fromXML" method. The WRITER is a 'before' hook which calls a "toXML" method. See respectively the XML::Compile::Translate::Reader and XML::Compile::Translate::Writer. 📚

Private variables in objects 🙈

When you design a new object, it is possible to store the information exactly like the corresponding XML type definition. The only thing the "fromXML" has to do, is bless the data-structure into its class:

$schema->typemap($xmltype => 'My::Perl::Class');
package My::Perl::Class;
sub fromXML { bless $_[1], $_[0] } # for READER
sub toXML   { $_[0] }              # for WRITER

However... the object may also need so need some private variables. If you store them in the same HASH for your object, you will get "unused tags" warnings from the writer. 😭 To avoid that, choose one of the following alternatives:

# never complain about unused tags
::Schema->new(..., ignore_unused_tags => 1);

# only complain about unused tags not matching regexp
my $not_for_xml = qr/^[A-Z]/;  # my XML only has lower-case
::Schema->new(..., ignore_unused_tags => $not_for_xml);

# only for one compiled WRITER (not used with READER)
::Schema->compile(..., ignore_unused_tags => 1);
::Schema->compile(..., ignore_unused_tags => $not_for_xml);

Typemap limitations ⚠️

There are some things you need to know:

Many schemas define very complex types. These may often not translate cleanly into objects. You may need to create a typemap relation for some parent type. The CODE reference may be very useful in this case. 🧚
A same kind of problem appears when you have a list in your object, which often is not named in the schema.

Handling xsi:type 🔥

[1.10] The "xsi:type" is an old-fashioned mechanism, and should be avoided! In this case, the schema does tell you that a certain element has a certrain type, but at run-time(!) that is changed. When an XML element has a "xsi:type" attribute, it tells you simply to have an extension of the original type. This whole mechanism does bite the "compilation" idea of XML::Compile... however with some help, it will work. 💪

To make "xsi:type" work at run-time, you have to pass a table of which types you expect at compile-time. Example:

my %xsi_type_table =
  ( $base_type1 => [ $ext1_of_type1, $ext2_of_type2 ]
  , $base_type2 => [ $ext1_of_type2 ]
  );

my $r = $schema->compile(READER => $type
  , xsi_type => \%xsi_type_table
  );

When your schema is an XML::Compile::Cache (version at least 0.93), your types look like "prefix:local". With a plain XML::Compile::Schema, they will look like "{namespace}local", typically produced with XML::Compile::Util::pack_type(). ✨

When used in a reader, the resulting data-set will contain a "XSI_TYPE" key inbetween the facts which were taken from the element. The type is is long syntax "{$ns}$type". See XML::Compile::Util::unpack_type()

With the writer, you have to provide such an "XSI_TYPE" value or the element's base type will be used (and no "xsi:type" attribute created). This will probably cause warnings about unused tags. The type can be provided in full (see XML::Compile::Util::pack_type()) or [1.31] prefixed.

[1.25] then the value is not an ARRAY, but only the keyword "AUTO", the parser will try to auto-detect all types which are valid alternatives. This currently only works for non-builtin types. The auto-detection might be slow and (because many schemas are broken) not produce a complete list. When debugging is enabled ("use Log::Report mode => 3;") you will see to which list this AUTO gets expanded. 👀

xsi_type => { $base_type => 'AUTO' }   # requires X::C v1.25

XML::Compile::Cache (since v1.01) makes using "xsi:type" easier. When you have a ::Cache based object (for instance a XML::Compile::WSDL11) you can simply say

$wsdl->addXsiType( $base_type => 'AUTO' )

Now, you do not need to pass the xsi table to each compilation call. slay. 💅

Key rewrite 🎀

[improved with release 1.10] The standard practice is to use the localName of the XML elements as key in the Perl HASH; the key rewrite mechanism is used to change that, sometimes to separate elements which have the same localName within different name-spaces, or when an element and an attribute share a name (key rewrite is applied to elements AND attributes) in other cases just for fun or convenience. 🦋

Rewrite rules are interpreted at "compile-time", which means that they do not slow-down the XML construction or deconstruction. The rules work the same for readers and writers, because they are applied to name found in the schema. ⭐

Okay so key rewrite rules can be set when you're first making the schema object with new(key_rewrite), or later on an existing schema object with addKeyRewrite(). These rules? They get used in every single call to compile(). 💖

Next, you can use compile(key_rewrite) to add rules that are only for one single compilation. These get applied before the global rules. All rules will always be attempted, and the rule gets applied to the result of the previous change. No cap. ✨

The last defined rewrite rules get applied first, with one major exception: the "PREFIXED" rules are executed before any other rule. 👑

🌸 key_rewrite via table 🌸

When a HASH is provided as a rule, the XML element name is looked-up. If it's found, the value is used as the translated key. 🎀

First the full name of the element is tried, and then the localName of the element. The full name can be created with XML::Compile::Util::pack_type() or by hand:

use XML::Compile::Util qw/pack_type/;

my %table =
  ( pack_type($myns, 'el1') => 'nice_name1'
  , "{$myns}el2" => 'alsoNice'
  , el3          => 'in any namespace'
  );
$schema->addKeyRewrite( \%table );

💅 Rewrite via function 💅

When a CODE reference is provided, it gets called for each key that's found in the schema. Passed are the name-space of the element and its local-name. Returned is the key, which may be the local-name or something else. 🦋

For instance, some people use capitals in element names and personally I do not like them:

sub dont_like_capitals($$)
{   my ($ns, $local) = @_;
    lc $local;
}
$schema->addKeyRewrite( \&dont_like_capitals );

for short:

my $schema = XML::Compile::Schema->new( ...,
    key_rewrite => sub { lc $_[1] } );

😭 key_rewrite when localNames collide 😭

Let's start with an apology: we cannot auto-detect when these rewrite rules are needed, because the colliding keys are within the same HASH, but the processing is fragmented over various (sequence) blocks: the parser does not have the overview on which keys of the HASH are used for which elements. 💀

The problem occurs when one complex type or substitutionGroup contains multiple elements with the same localName, but from different name-spaces. In the perl representation of the data, the name-spaces get ignored (to make the programmer's life simple) but that may cause these nasty conflicts. 🙈

🍓 Rewrite for convenience 🍓

In XML, we often see names like "my-elem-name", which in Perl would be accessed as

$h->{'my-elem-name'}

In this case, you cannot leave-out the quotes in your perl code, which is quite inconvenient, because only 'barewords' can be used as keys unquoted. When you use option "key_rewrite" for compile() or new(), you could decide to map dashes onto underscores. 🧚

key_rewrite
   => sub { my ($ns, $local) = @_; $local =~ s/\-/_/g; $local }

key_rewrite => sub { $_[1] =~ s/\-/_/g; $_[1] }

then "my-elem-name" in XML will get mapped onto "my_elem_name" in Perl, both in the READER as the WRITER. Be warned that the substitute command returns the success, not the modified value! ⚠️

👑 Pre-defined key_rewrite rules 👑

UNDERSCORES — Replace dashes (-) with underscores (_). 💖
SIMPLIFIED — Rewrite rule with the constant name (STRING) "SIMPLIFIED" will replace all dashes with underscores, translate capitals into lowercase, and remove all other characters which are none-bareword (if possible, I am too lazy to check). 😅
PREFIXED — This requires a table for prefix to name-space translations, via compile(prefixes), which defines at least one non-empty (default) prefix. The keys which represent elements in any name-space which has a prefix defined will have that prefix and an underscore prepended. 🌟

Be warned that the name-spaces which you provide are used, not the once used in the schema. Example:

             my $r = $schema->compile
               ( READER => $type
               , prefixes    => [ mine => $myns ]
               , key_rewrite => 'PREFIXED'
               );

             my $xml = $r->( <<__XML );
           <data xmlns="$myns"><x>42</x></data>
           __XML

             print join ' => ', %$xml;    #   mine_x => 42

PREFIXED(...) — Like the previous, but now only use a selected sub-set of the available prefixes. This is particular useful in writers, when explicit prefixes are also used to beautify the output. 💅

The prefixes are not checked against the prefix list, and may have surrounding blanks.

             key_rewrite => 'PREFIXED(opt,sar)'

Above is equivalent to:

             key_rewrite => [ 'PREFIXED(opt)', 'PREFIXED(sar)' ]

Special care is taken that the prefix will not be added twice. For instance, if the same prefix appears twice, or a "PREFIXED" rule is provided as well, then still only one prefix is added. 🎀

✨ SEE ALSO ✨

This module is part of XML-Compile distribution version 1.64, built on October 21, 2024. Website: http://perl.overmeer.net/xml-compile/ 🌈

🎀 LICENSE 🎀

Copyrights 2006-2024 by [Mark Overmeer <markov@cpan.org>]. For other contributors see ChangeLog. 💖

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See http://dev.perl.org/licenses/ 🌸

And that's the whole vibe check, bestie! This page is from XML::C...Schema(3pm), source/version perl v5.40.0, dated 2024-10-27. Slay, you made it to the end! 💅✨

📦 where this page comes from

debian trixie: libxml-compile-perl 1.64-1 · Artistic-1.0-Perl OR GPL-1.0-or-later
ubuntu resolute: libxml-compile-perl 1.64-1 · Artistic-1.0-Perl OR GPL-1.0-or-later
ubuntu stonking: libxml-compile-perl 1.64-1 · Artistic-1.0-Perl OR GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms

XML::C...Schema(3pm)

💅 NAME 💅

🌸 INHERITANCE 🌸

🦋 SYNOPSIS 🦋

✨ DESCRIPTION ✨

🔥 METHODS 🔥

🎀 Constructors 🎀

🌈 Accessors 🌈

💖 $obj->addTypemap(PAIR)

💖 $obj->addTypemaps(PAIRS)

💖 $obj->blockNamespace($ns|$type|HASH|CODE|ARRAY)

💖 $obj->hooks( [<'READER'|'WRITER'>] )

💖 $obj->useSchema( $schema, [$schema, ...] )

🧚 Compilers

⭐ $obj->compile( <'READER'|'WRITER'>, $type, %options )

✨ Administration ✨

🌈 DETAILS 🌈

🦋 Distribution collection overview 🦋

🍓 Comparison 🍓

✨ Collecting definitions ✨

🎀 Organizing your definitions 🎀

🌸 Addressing components 🌸

🦋 Representing data-structures 🦋

💖 simpleType 💖

. Example: typical simpleType

🌈 complexType/simpleContent 🌈

. typical simpleContent example

👑 complexType and complexType/complexContent 👑

. Example: typical complexType element

💅 Manually produced XML NODE 💅

⭐ Occurence ⭐

🎀 Default Values 🎀

. Example: use of default_values EXTEND

🌀 Repetative blocks 🌀

🎀 Schema hooks 🎀

General syntax ✨

Hooks on matching types 🦋

Hooks on extended type 🌸

Hooks on matching ids 🎀

Hooks on matching paths 🌈

Typemaps 💖

Private variables in objects 🙈

Typemap limitations ⚠️

Handling xsi:type 🔥

Key rewrite 🎀

🌸 key_rewrite via table 🌸

💅 Rewrite via function 💅

😭 key_rewrite when localNames collide 😭

🍓 Rewrite for convenience 🍓

👑 Pre-defined key_rewrite rules 👑

✨ SEE ALSO ✨

🎀 LICENSE 🎀

💖 `$obj->addTypemap(PAIR)`

💖 `$obj->addTypemaps(PAIRS)`

💖 `$obj->blockNamespace($ns|$type|HASH|CODE|ARRAY)`

💖 `$obj->hooks( [<'READER'|'WRITER'>] )`

💖 `$obj->useSchema( $schema, [$schema, ...] )`

⭐ `$obj->compile( <'READER'|'WRITER'>, $type, %options )`