.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" 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
.\" ========================================================================
.\"
.IX Title "XML::Compile::FAQ 3pm"
.TH XML::Compile::FAQ 3pm "2022-11-27" "perl v5.36.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"
XML::Compile::FAQ \- frequently asked questions
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
On this page, a wild collection of questions are answered.  If you have
contributions either in question or as answer, then please contribute
via the mailinglist.
.PP
See also XML::Compile::SOAP::FAQ.
.SS "The data structure"
.IX Subsection "The data structure"
\fIwhat do the cho_, seq_ and all_ start of labels mean?\fR
.IX Subsection "what do the cho_, seq_ and all_ start of labels mean?"
.PP
X::C tries to give you a simple data-structure in Perl, however \s-1XML\s0
does not always map directly only that.  One such situation is where
you have blocks within a list of elements.  In such case, the block gets
a name which is composed by the type of block and the first element in
the block.  You will encounter these names in some error messages and
when these block have a maxOccurs larger than 1.
.PP
Example. The name \f(CW\*(C`cho_tic\*(C'\fR is used to represent the following nameless
choice block:
.PP
.Vb 5
\&  <choice>
\&    <element name="tic" />
\&    <element name="tac" />
\&    <element name="toe" />
\&  </choice>
.Ve
.PP
\fIlocalName collission\fR
.IX Subsection "localName collission"
.PP
In the default behavior, only the \*(L"local\*(R" names of the \s-1XML\s0 elements are
used in the Perl structure.  However, it is very well possible that the
same name appears in more than on \s-1XML\s0 name-space, used within the same
data structure.  So see this often with substitutionGroups.
.PP
When collissions happen, you have to switch to use
\&\f(CW\*(C`key_rewrite => \*(AqPREFIXED\*(Aq\*(C'\fR in the compile rules.  All keys will
now get rewritten: the name-space prefix will be prepended.  The prefixes
are defined by the mapping table provided with the \f(CW\*(C`prefixes\*(C'\fR option
or by default from the \s-1XML\s0 schemas.
.PP
See \*(L"Key rewrite\*(R" in XML::Compile::Schema for the full list of options.
.PP
\fIOverruling produced structures (writer)\fR
.IX Subsection "Overruling produced structures (writer)"
.PP
You may encounter broken servers.  Actually, I have seen even expensive
server implementations and professional high-profile services which do
not follow the rules...
.PP
On any location in the data structure you provide, you can give a value
but also a fully prepared XML::LibXML node.  For instance
.PP
.Vb 5
\&   my $doc  = XML::LibXML::Document\->new(\*(Aq1.1\*(Aq, \*(AqUTF\-8\*(Aq);
\&   my $node = $doc\->createElement(\*(Aqfield);
\&   $node\->appendText(42);
\&   my $xml  = $schema\->writer($type)\->($doc, { field => $node });
\&   $doc\->setDocumentElement($xml);
\&   
\&   print $xml\->toString(1);   # perl string
\&   print $doc\->toString(1);   # bytes
.Ve
.PP
You will probably need more than one attempt to produce the correct
output... Only use this when you are sure that the receiving party
is broken.
.PP
\fIProducting \s-1CDATA\s0 blocks (writer)\fR
.IX Subsection "Producting CDATA blocks (writer)"
.PP
To get \s-1CDATA\s0 blocks, the solution is very close to the example in the
previous section:
.PP
.Vb 4
\&   my $doc   = XML::LibXML::Document\->new(\*(Aq1.1\*(Aq, \*(AqUTF\-8\*(Aq);
\&   my $cdata = $doc\->createCDATASection($content);
\&   my $xml   = $schema\->writer($type)\->($doc, { field => $cdata });
\&   $doc\->setDocumentElement($xml);
.Ve
.PP
The \*(L"$content\*(R" is a Perl string, which means that it needs to be
utf8 when it is utf8.  For instance:
.PP
.Vb 3
\&   use File::Slurp::Tiny;
\&   my $content = read_file $filename, binmode => \*(Aqutf8\*(Aq;
\&   my $cdata   = $doc\->createCDATASection($content);
.Ve
.SS "Schemas"
.IX Subsection "Schemas"
Be aware that the \*(L"2001\*(R" schema specification is continuously under
development.  So, the namespace has not been changed over time, but
the content has.
.PP
\fIqualified elements\fR
.IX Subsection "qualified elements"
.PP
One of the more noticeable problems with schemas is the specification of
the namespaces to be used for the schema.  In older schema's, like many
important protocols, there was no way to specify whether elements should
be used qualified or not.  Some schema's lack the target namespace
declaration.  Those fields did not exist in earlier versions of the
\&\*(L"2001\*(R" spec; it was defined in the documentation.
.PP
So, what you may encounter is something like:
.PP
.Vb 1
\&  <schema xmlns="http://www.w3.org/2001/XMLSchema">
.Ve
.PP
where (in the current syntax) it should have been
.PP
.Vb 4
\&  <schema xmlns="http://www.w3.org/2001/XMLSchema"
\&    targetNamespace="http://my\-namespace"
\&    elementFormDefault="qualified"
\&    attributeFormDefault="unqualified">
.Ve
.PP
The default for \f(CW\*(C`targetNamespace\*(C'\fR is \*(L"namespace-less\*(R".  The \f(CW*FormDefault\fR
defaults are \f(CW\*(C`unqualified\*(C'\fR, which is a pity: most schemas will use
qualified elements.
.PP
Of course, you can add these fields to the schema file, but that violates
the intergrity of that external resource.  Therefore, use options:
.PP
.Vb 5
\&  my $schema = XML::Compile::Schema\->new;
\&  $schema\->importDefinitions("schema.xsd"
\&     , target_namespace     => \*(Aqhttp://my\-namespace\*(Aq
\&     , element_form_default => \*(Aqqualified\*(Aq
\&     );
.Ve
.PP
You may also provide all these options with \f(CW\*(C`new()\*(C'\fR directly.
.PP
.Vb 4
\&  my $schema = XML::Compile::Schema\->new("schema.xsd"
\&     , target_namespace     => \*(Aqhttp://my\-namespace\*(Aq
\&     , element_form_default => \*(Aqqualified\*(Aq
\&     );
.Ve
.PP
If you use the XML::Compile::Cache object, which extends ::Schema, then
you have a nice \f(CW\*(C`printIndex\*(C'\fR method which shows you what has been read.
.PP
\fIschema location\fR
.IX Subsection "schema location"
.PP
The official idea about the use of schema's, is that you get the latest
version of them on the moment you start the application.  There are two
major problems with that:
.IP ". you may not have (a working) internet connection on that moment" 4
.IX Item ". you may not have (a working) internet connection on that moment"
.PD 0
.IP ". remote changes in the spec may break your application unexpectedly" 4
.IX Item ". remote changes in the spec may break your application unexpectedly"
.PD
.PP
In general, \s-1IMO\s0 as author of the XML::Compile suite, you should \fBnever\fR
want this dynamic, unpredictable behavior!
.PP
Besides, the content of the \f(CW\*(C`schemaLocation\*(C'\fR attribute to \f(CW\*(C`import\*(C'\fR,
\&\f(CW\*(C`include\*(C'\fR and \f(CW\*(C`schema\*(C'\fR elements are usually broken, missing and/or
flawed.  You can better do it by hand.
.PP
Collect the schema's you need in a directory.  The name of the schema
file does not need to means anything useful.  Then, add the location
where the schema's are found:
.PP
.Vb 2
\&   my $schema = XML::Compile::Cache\->new;
\&   $schema\->addSchemaDirs($my_schema_dir);
.Ve
.PP
Add the mapping from namespaces to filenames (you may provide an \s-1ARRAY\s0 of
names or use the same namespace multiple times).  It is useful to have
a constant defined for your namespace.
.PP
.Vb 3
\&   use constant MY_NS => \*(Aqhttp://very\-long\*(Aq;
\&   $schema\->knownNamespace(&MY_NS => \*(Aqschemafile.xsd\*(Aq);
\&   $schema\->importDefinitions(MY_NS, @options);
.Ve
.PP
There is also a less clean solution:
.PP
.Vb 1
\&   my $schema = XML::Compile::Cache\->new(\*(Aqschemafile.xsd\*(Aq, @options);
.Ve
.PP
When you have many xsd's to include, you may do this:
.PP
.Vb 4
\&   my @xsds = glob "$my_schema_dir/*.xsd";
\&   my $schema = XML::Compile::Cache\->new;
\&   $schema\->knownNamespace(&MY_NS => \e@xsds);
\&   $schema\->importDefinitions(MY_NS, @options);
.Ve
.PP
or
.PP
.Vb 1
\&   my $schema = XML::Compile::Cache\->new(\e@xsds, @options);
.Ve
.PP
\fIfixing schemas\fR
.IX Subsection "fixing schemas"
.PP
Many schema's are broken.  XML::Compile is not a good tool to figure-out
what is wrong with the schema.  Have you tried \f(CW\*(C`xmllint\*(C'\fR?  Sometimes, you
get sufficient help adding to the top of your script:
.PP
.Vb 1
\&   use Log::Report mode => \*(AqDEBUG\*(Aq;
.Ve
.PP
When you know what is wrong, you can overrule parts of the schema by
redefining elements; simply: the last definition for an element wins.
For instance:
.PP
.Vb 6
\&   $schema\->importDefinition(<<\*(Aq_PATCH\*(Aq);
\&   <schema ....>
\&     <element name="has_bug">
\&        ...
\&     </element>
\&   _PATCH
.Ve
.PP
Of course, you can also use an external file for this.
.PP
\fIExample\fR
.IX Subsection "Example"
.PP
This is a piece of code actually used.  It shows various complications
when an external schema is \*(L"loaded\*(R" \*(L"dynamically\*(R" into another schema.
.PP
.Vb 4
\&  # In the top of your script
\&  my $schema_dir = \*(Aq/usr/share/schemas\*(Aq;
\&  my $xyz_ns     = \*(Aqhttp://www.xyzeorder.com/workflow\*(Aq;
\&  my $xyz_xsd    = \*(AqxyzSchema.xsd\*(Aq;
\&
\&  # In the main part of your script
\&  my $schema     = XML::Compile::Cache\->new(....);
\&  $schema\->addSchemaDirs($schema_dir);
\&  $schema\->importDefinitions($xyz_xsd, target_namespace => $xyz_ns);
\&  $schema\->addPrefixes(xyz => $xyz_ns);
\&  $schema\->addKeyRewrite(\*(AqPREFIXED(xyz)\*(Aq);
.Ve
.PP
The schema \*(L"forgets\*(R" to mention its \f(CW\*(C`targetNamespace\*(C'\fR, so it is
overruled.  The ::Cache extension handles prefixes much nicer than
the ::Schema base object.  So, with reading/writing the hash keys
which relate to the elements in this schema will have \f(CW\*(C`xyz_\*(C'\fR as
prefix for clarity.
.SS "Processing"
.IX Subsection "Processing"
\fImy data is not recognized\fR
.IX Subsection "my data is not recognized"
.PP
You do specify the data in your structure, but it seems not to
be recognized.  See \*(L"wrong error message\*(R"
.PP
\fIwrong error message\fR
.IX Subsection "wrong error message"
.PP
You may get an error message about a \*(L"missing data item\*(R" on a higher
structural level than where the problem actually is.  This especially
happens with unions and substitutionGroups.  The problem
is cause by the fact that on a certain structural level, multiple
alternatives may appear which only differ many levels deep in structure.
X::C needs to scan all the alternatives, and when all fail it does not
know which of the alternatives was \*(L"the best\*(R" alternative.
.PP
Try turning on debugging with:
.PP
.Vb 1
\&  use Log::Report  mode => "DEBUG";
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
This module is part of XML-Compile distribution version 1.63,
built on July 02, 2019. Website: \fIhttp://perl.overmeer.net/xml\-compile/\fR
.SH "LICENSE"
.IX Header "LICENSE"
Copyrights 2006\-2019 by [Mark Overmeer <markov@cpan.org>]. For other contributors see ChangeLog.
.PP
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
See \fIhttp://dev.perl.org/licenses/\fR