xmerl_xsd(3)

💖 xmerl_xsd — the interface module for XML Schema validation 💖

okay bestie, gather round, because this is the one in the xmerl family you call when you need to check that an XML thing actually obeys its schema. This is the Erlang module definition page for xmerl_xsd, and it's lowkey iconic. 🦋

---

✨ NAME ✨

xmerl_xsd — Interface module for XML Schema validation. that's it, that's the vibe. 💅

---

🌸 DESCRIPTION 🌸

It handles the W3.org specifications of XML Schema second edition 28 october 2004. So yeah, it's doing the whole spec, and if you want an intro to XML Schema you should fr go study part 0 first. 📚

An XML structure gets validated by xmerl_xsd:validate/[2,3]. That's the moment. The main character moment. 👑

---

🎀 DATA TYPES 🎀

• filename() :: string(). — just a string, bestie. a name. of a file. wild concept ik.
• global_state() :: xsd_state(). — the global state of the validator. ✨ It is represented by the #xsd_state{} record. no cap.
• option_list() :: [{xsdbase, filename()} | {atom(), term()}]. — the options that let you customize the behaviour of the validation. 🌈

Possible options are:

• {tab2file,boolean()} — Enables saving of abstract structure on file for debugging purpose. yes, for debugging, bestie, not for flexing. 🐛
• {xsdbase,filename()} — XSD Base directory. 📁
• {fetch_fun,FetchFun} — Call back function to fetch an external resource. it's giving "you go get it". 🫶
• {fetch_path,PathList} — 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. so if it's not where you looked, we're just rawdogging the URI as a filename, that's the rule. 💀
• {state,State} — It is possible by this option to provide a state with process information from an earlier validation. reuse queen. ♻️

---

🔥 FUNCTIONS 🔥

⭐ file2state(FileName :: string()) -> {ok, State} | {error, Reason}

when State :: global_state(), Reason :: term().

Read the schema processing state from a file. 📖

Reads the schema state with all information of the processed schema from a file created with state2file/[1,2]. The format of this file is internal — so like, don't go poking at it, it's private. 🙈 The state can then be used validating an XML document. slay.

---

⭐ format_error(Reasons) -> io_lib:chars()

when

Reasons ::
    [Reason :: term()] | (Reason :: term()).

Format error descriptions to human readable strings. so your errors stop looking like cursed hieroglyphics and start looking like sentences. 💅

---

⭐ process_schema(Schema :: string(), Options :: option_list()) -> {ok, State} | {error, Reasons}

when

State :: global_state(),
Reasons ::
    [Reason :: term()] | (Reason :: term()).

Read an XML schema and check that it is valid. ✅

Reads the referenced XML schema and checks that it is valid. Returns the global_state/0 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. so like, it might hand you one problem, or it might hand you the whole group chat. 😭

---

⭐ process_schemas(Schemas, Options) -> {ok, State} | {error, Reasons}

when

Schemas :: [{NameSpace, Schema}, ...],
Options :: option_list(),
NameSpace :: term(),
Schema :: string(),
State :: global_state(),
Reasons ::
    [Reason :: term()] | (Reason :: term()).

Read XML schemas — plural, babes, we're doing a set — and check that they are valid. ✅✅

Reads the referenced XML schemas and controls they are valid. Returns the global_state/0 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. same energy as above but multiplied. 👯

---

⭐ process_validate(Schema, Element, Options) -> Result

when

Schema :: string(),
Element :: xmerl:element(),
Options :: option_list(),
Result ::
    {ValidElement, global_state()} |
    {error, Reasons},
ValidElement :: xmerl:element(),
Reasons ::
    [Reason :: term()] |
    (Reason :: term()).

Validate a parsed well-formed XML element towards an XML schema. 🎯

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. two steps, one icon. ✨

Usage example:

1>{E,_} = xmerl_scan:file("my_XML_document.xml").
2>{E2,_} = xmerl_xsd:process_validate("my_XML_Schema.xsd",E).

Observe that E2 may differ from E if for instance there are default values defined in my_XML_Schema.xsd. 😳 yes bestie, your element can come back changed. that's the schema's default values doing their little makeover. 💄

---

⭐ state2file(State :: global_state()) -> ok | {error, Reason}

when Reason :: term().

Equivalent to state2file(State, SchemaName).

SchemaName is the name of the schema in State. so it just grabs the name it already knows. convenient fr fr. 🫶

---

⭐ state2file(global_state(), FileName :: string()) -> ok | {error, Reason}

when Reason :: term().

Save the schema processing state to a file. 💾

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 .xss extension added. don't be surprised when the extension shows up, it was always the plan. 🎀

---

⭐ validate(Element, global_state(), Options) -> Result

when

Element :: xmerl:xmlElement(),
Options :: option_list(),
Result ::
    {ValidElement, global_state()} |
    {error, Reasons},
ValidElement :: xmerl:xmlElement(),
Reasons :: [ErrorReason] | ErrorReason,
ErrorReason :: term().

Validate a parsed well-formed XML element (Element). 🔍

A call to validate/2 or validate/3 must provide a well formed parsed XML Element :: #xmlElement{} and a State, global_state/0, 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. it's giving efficiency queen, it's giving caching, it's giving we-do-not-reprocess-in-this-house. 👑

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. so: a whole list of problems if it can keep going, or one sad lonely reason if it hit something truly unexpected. 💀

Usage example:

1>{E,_} = xmerl_scan:file("my_XML_document.xml").
2>{ok,S} = xmerl_xsd:process_schema("my_XML_Schema.xsd").
3>{E2,_} = xmerl_xsd:validate(E,S).

Observe that E2 may differ from E if for instance there are default values defined in my_XML_Schema.xsd. again! default values! they will absolutely reshape your element and that is correct behaviour, so don't come for me. 🌸

---

and that's the whole page, bestie 💖 go validate something and feel powerful ✨

okay bye, this manual page came to you from Ericsson AB, describing xmerl version 2.2, dated with xmerl_xsd(3) as its page — so go forth and process those schemas. 🦋💅🎀