Generate pure Ruby objects from an XML schema (XSD) using JAXB and JRuby. Use your favorite XML to object mapper or a custom ERB template.
Generate pure Ruby classes from an XML schema using JAXB and JRuby
usage: jaxb2ruby [options] schema
-c, --classes=MAP1[,MAP2,...] XML Schema type to Ruby class mappings
MAP can be a string in the form type=class or a YAML file of type/class pairs
-h, --help Show this message
-I, --include=DIRECTORY Add DIRECTORY to the load path, usefull for using custom template helpers
-J, --jvm=[ARG1[,ARG2,...]] Options to pass to the JVM when calling XJC
-n, --namespace=MAP1[,MAP2,...] XML namespace to ruby class mappings
MAP can be a string in the form namespace=class or a YAML file of namespace/class pairs
-o, --output=DIRECTORY Directory to output the generated ruby classes, defaults to ruby
-t, --template=NAME Template used to generate the ruby classes
Can be a path to an ERB template or one of: roxml (default), happymapper, ruby
-v, --version jaxb2ruby version
-w, --wsdl Treat the schema as a WSDL
Automatically set if the schema has a `.wsdl' extension
-x, --xjc=PATH Path to the XJC executable to use; defaults to xjc
gem install jaxb2ruby
jaxb2ruby
must be installed and ran under JRuby. The generated classes will not depend on JRuby.
If your underlying JDK version is >= 9 you must use JRuby >= 9.2.12.0.
If your underlying JDK version is >= 11, you must manually install JAXB.
In this case you'll likely run jaxb2ruby
using the following (on *nix):
CLASSPATH=path/to/jaxb-ri/mod/jakarta.xml.bind-api.jar jaxb2ruby -x path/to/xjc.sh schema.xsd
Certain XML schema types are converted to Symbol
s.
You can specify your own XML Schema to Ruby type mapping(s) via the -c
option.
For a complete list of mappings see the SCHEMA_TO_RUBY
constant.
Complex schema types will camelized
and turned into Ruby classes. If a type has a namespace
the namespace will be converted into a module and the resulting class will be placed inside.
Namespaces are turned into modules using a slightly modified version of the rules outlined in the The Java Architecture for XML Binding (JAXB) 2.0 Section D.5.1 Mapping from a Namespace URI. The differences being:
"::"
"_"
is replaced with "V"
Some examples:
{http://example.com}User
becomes Com::Example::User
{http://example.com/api/15}User
becomes Com::Example::Api::V15::User
An XML schema type {http://example.com}User
that contains the nested complex type
Addresses
, which itself contains the type Address
will result in the creation
of 3 classes: User
, User::Addresses
and User::Addresses::Address
, all within
the Com::Example
namespace.
You can specify your own namespace to class mapping(s) via the -n
option.
Namespace mappings have a lower precedence than type mappings.
jaxb2ruby
uses ERB templates to create Ruby classes. You can use one of the bundled templates
or create your own. Use the -t
option to specify the path to a custom
template or one of the following bundled ones:
roxml
the default (ROXML)happymapper
(Nokogiri HappyMapper)ruby
- plain 'ol Ruby classesNote that "plain 'ol Ruby classes" does not perform XML serialization.
Use the -t
option to specify the path to your template. This must be a path else it will be interpreted as a jaxb2ruby template.
Two variables will be provided to your template:
@class
, an instance of RubyClass
VERSION
the version of jaxb2ruby
See lib/templates
for some examples.
You can use helper functions in your templates by providing the helper file's directory to the -I
option.
Skye Shaw [sshaw AT gmail.com]
Released under the MIT License: www.opensource.org/licenses/MIT