Skip to content

Latest commit

 

History

History
83 lines (57 loc) · 3.04 KB

README.md

File metadata and controls

83 lines (57 loc) · 3.04 KB
Raw

Erlxml

Hex pm Build Status License

Modern Erlang / Elixir library for XML <-> map serialisation and deserialisation using XSD schema powered by OTP/xmerl

Version: 1.0.0

Erlang/OTP: >= 20

Summary

Erlxml provides more modern approach for working with data coming from XML sources. In order for Erlxml to determine how to deserialise XML a XML-schema also known as XSD must be provided.

Erlxml will validate against the provided XSD on serialisation and deserialisation. This includes extensive type checks - Validation is done by xmerl_xsd module.

Type casting of data is will be attempted altough only a limited set of XML types is supported at this stage:

  • xs:string <> binary
  • xs:decimal <> float
  • xs:float <> float
  • xs:int <> integer
  • xs:integer <> integer
  • xs:positiveInteger <> integer
  • xs:negativeInteger <> integer
  • xs:nonPositiveInteger <> integer
  • xs:nonNegativeInteger <> integer
  • xs:date <> {YYYY, MM, DD} (Only "YYYY-MM-DD" format is supported at this stage)
  • xs:boolean <> boolean or 0/1

These and all other types are validated by the xmerl_xsd module, Erlxml handles unkown types gracefully by casting them to a binary string.

About maps and lists

Erlxml deserialises XML data into maps. It uses the XML-schema (XSD) to determine if a tag contains a list of tags or just some properties - Eg. books -> list of books vs book -> title, description etc. Consider:

   % List element
   #{books=> [
   #{book => #{title => <<"Title">>, desc => <<"Desc">>}}
   ]}
   % Non-list element
   #{book => #{title => <<"Title">>, desc => <<"Desc">>}}

To determine if a tag should be deserialised as a 'list-element' Erlxml uses the maxOccurs attribute in your XML-schema (XSD). All elements containing an element with a maxOccurs attribute with a value other than 1 are considered 'list-elements'.

About Schemas

The first line of your schema file (XSD-file) contain <?xml version="1.0" encoding="UTF-8"?>.

Schema namespace must be xs: for now as the library is not handeling schema namespaces dynamically yet.

Usage

Serialise

  • Build a Schema state by using {ok, State} = erlxml:build_schema_state({file, "path/to/example/file.xsd"}).
  • Call erlxml:deserialise(#{'mock' => ""}, State).

Deserialise

  • Build a Schema state by using {ok, State} = erlxml:build_schema_state({file, "path/to/example/file.xsd"}).
  • Call erlxml:deserialise("<mock/>", State).

Contribute

For issues, comments or feedback please create an issue.