.TH xmerl_xsd 3 "xmerl  1.1.9" "Ericsson AB" "ERLANG MODULE DEFINITION"
.SH MODULE
xmerl_xsd \- Interface module for XML Schema vlidation\&.
.SH DESCRIPTION
.LP
Interface module for XML Schema vlidation\&. It handles the W3\&.org specifications <http://www\&.w3\&.org/XML/Schema#dev> of XML Schema second edition 28 october 2004\&. For an introduction to XML Schema study part 0\&. <http://www\&.w3\&.org/TR/xmlschema-0/> An XML structure is validated by xmerl_xsd:validate/[2,3]\&.

.SH DATA TYPES
.RS 2
.TP 4
.B
\fIglobal_state()\fR:

.RS 4
.LP
The global state of the validator\&. It is representated by the \fI#xsd_state{}\fR record\&. 
.LP

.RE
.TP 4
.B
\fIoption_list()\fR:

.RS 4
.LP
Options allow to customize the behaviour of the validation\&. 
.LP
Possible options are : 
.RS 2
.TP 4
.B
\fI{tab2file, boolean()}\fR:
Enables saving of abstract structure on file for debugging purpose\&.
.TP 4
.B
\fI{xsdbase, filename()}\fR:
XSD Base directory\&.
.TP 4
.B
\fI{fetch_fun, FetchFun}\fR:
Call back function to fetch an external resource\&.
.TP 4
.B
\fI{fetch_path, PathList}\fR:
PathList is a list of directories to search when fetching files\&. If the file in question is not in the fetch_path, the URI will be used as a file name\&.
.TP 4
.B
\fI{state, State}\fR:
It is possible by this option to provide a state with process information from an earlier validation\&.
.RE
.LP
-------------------------------------------------------------------
.RE
.RE
.SH EXPORTS
.LP
.B
file2state(FileName) -> {ok, State} | {error, Reason}
.br
.RS
.TP
Types
State = global_state()
.br
FileName = filename()
.br
.RE
.RS
.LP
Reads the schema state with all information of the processed schema from a file created with \fIstate2file/[1, 2]\fR\&. The format of this file is internal\&. The state can then be used validating an XML document\&.
.RE
.LP
.B
format_error(L::Errors) -> Result
.br
.RS
.TP
Types
Errors = error_tuple() | [error_tuple()]
.br
Result = string() | [string()]
.br
.RE
.RS
.LP
Formats error descriptions to human readable strings\&.
.RE
.LP
.B
process_schema(Schema) -> Result
.br
.RS
.LP
Equivalent to process_schema(Schema, [])\&.
.RE
.LP
.B
process_schema(Schema, Options) -> Result
.br
.RS
.TP
Types
Schema = filename()
.br
Result = {ok, State} | {error, Reason}
.br
State = global_state()
.br
Reason = [ErrorReason] | ErrorReason
.br
Options = option_list()
.br
.RE
.RS
.LP
Reads the referenced XML schema and checks that it is valid\&. Returns the \fIglobal_state()\fR with schema info or an error reason\&. The error reason may be a list of several errors or a single error encountered during the processing\&.
.RE
.LP
.B
process_schemas(Schemas) -> Result
.br
.RS
.LP
Equivalent to process_schema(Schemas, [])\&.
.RE
.LP
.B
process_schemas(Schemas, Options) -> Result
.br
.RS
.TP
Types
Schemas = [{NameSpace, filename()} | Schemas] | []
.br
Result = {ok, State} | {error, Reason}
.br
Reason = [ErrorReason] | ErrorReason
.br
Options = option_list()
.br
.RE
.RS
.LP
Reads the referenced XML schemas and controls they are valid\&. Returns the \fIglobal_state()\fR with schema info or an error reason\&. The error reason may be a list of several errors or a single error encountered during the processing\&.
.RE
.LP
.B
process_validate(Schema, Xml::Element) -> Result
.br
.RS
.LP
Equivalent to process_validate(Schema, Xml, [])\&.
.RE
.LP
.B
process_validate(Schema, Xml::Element, Opts::Options) -> Result
.br
.RS
.TP
Types
Schema = filename()
.br
Element = XmlElement
.br
Options = option_list()
.br
Result = {ValidXmlElement, State} | {error, Reason}
.br
Reason = [ErrorReason] | ErrorReason
.br
.RE
.RS
.LP
Validates a parsed well-formed XML element towards an XML schema\&. 
.LP
Validates in two steps\&. First it processes the schema, saves the type and structure info in an ets table and then validates the element towards the schema\&.
.LP
Usage example:
.LP
\fI1>{E, _} = xmerl_scan:file("my_XML_document\&.xml")\&.\fR
.br
 \fI2>{E2, _} = xmerl_xsd:validate("my_XML_Schema\&.xsd", E)\&.\fR 
.LP
Observe that E2 may differ from E if for instance there are default values defined in \fImy_XML_Schema\&.xsd\fR\&.
.RE
.LP
.B
state2file(S::State) -> ok | {error, Reason}
.br
.RS
.LP
Same as state2file(State,SchemaName)
.LP
The name of the saved file is the same as the name of the schema, but with \fI\&.xss\fR extension\&.
.RE
.LP
.B
state2file(S::State, FileName) -> ok | {error, Reason}
.br
.RS
.TP
Types
State = global_state()
.br
FileName = filename()
.br
.RE
.RS
.LP
Saves the schema state with all information of the processed schema in a file\&. You can provide the file name for the saved state\&. FileName is saved with the \fI\&.xss\fR extension added\&.
.RE
.LP
.B
validate(Xml::Element, State) -> Result
.br
.RS
.LP
Equivalent to validate(Element, State, [])\&.
.RE
.LP
.B
validate(Xml::Element, State, Opts::Options) -> Result
.br
.RS
.TP
Types
Element = XmlElement
.br
Options = option_list()
.br
Result = {ValidElement, global_state()} | {error, Reasons}
.br
ValidElement = XmlElement
.br
State = global_state()
.br
Reasons = [ErrorReason] | ErrorReason
.br
.RE
.RS
.LP
Validates a parsed well-formed XML element (Element)\&. 
.LP
A call to validate/2 or validate/3 must provide a well formed parsed XML element \fI#xmlElement{}\fR and a State, \fIglobal_state()\fR, which holds necessary information from an already processed schema\&. Thus validate enables reuse of the schema information and therefore if one shall validate several times towards the same schema it reduces time consumption\&.
.LP
The result, ValidElement, is the valid element that conforms to the post-schema-validation infoset\&. When the validator finds an error it tries to continue and reports a list of all errors found\&. In those cases an unexpected error is found it may cause a single error reason\&. 
.LP
Usage example:
.LP
\fI1>{E, _} = xmerl_scan:file("my_XML_document\&.xml")\&.\fR
.br
 \fI2>{ok, S} = xmerl_xsd:process_schema("my_XML_Schema\&.xsd")\&.\fR
.br
 \fI3>{E2, _} = xmerl_xsd:validate(E, S)\&.\fR 
.LP
Observe that E2 may differ from E if for instance there are default values defined in \fImy_XML_Schema\&.xsd\fR\&.
.RE