• Core: 
• Serialization: 
• SerialUtil: 

XmlUtil is a set of packages that supports multiplatform XML in Kotlin.

This project is a cross-platform XML serialization (wrapping) library compatible with kotlinx.serialization. It supports all platforms although native is at beta quality.

Based upon the core xml library, the serialization module supports automatic object serialization based upon Kotlin's standard serialization library and plugin.

Help wanted: Any help with extending this project is welcome. Help is especially needed for the following aspects:

• Documentation updates
• Testing, in particular more extensive tests. Some tests already exist for both JVM and Android
• Native xml library support: Native is only supported through the cross-platform implementation that is somewhat limited in advanced features such as DTD and validation support. Ideally integration with a well-developed native library as an option would be beneficial.

This library is based upon the kotlinx.serialization library. Every effort is made to limit incompatible changes.

The library is designed as a multiplatform Kotlin module, but platform-specific versions can also be used were appropriate.

The project's Maven access is hosted on OSS Sonatype (and available from Maven Central).

Releases can be added from maven central

Snapshots are available from the default maven central snapshot repository:

repositories {
	maven {
		url  "https://central.sonatype.com/repository/maven-snapshots/"
	}
}

It should be noted that the JVM and Android packages are no longer part of the multiplatform publication (they are combined into a jvmCommon) package. The JVM and Android packages provide the native implementations and depend on (publishing) the jvmCommon package.

   implementation("io.github.pdvrieze.xmlutil:core:1.0.0-RC1")

   implementation("io.github.pdvrieze.xmlutil:core-jdk:1.0.0-RC1")

   implementation("io.github.pdvrieze.xmlutil:core-android:1.0.0-RC1")

   implementation("io.github.pdvrieze.xmlutil:core-js:1.0.0-RC1")

Has platform independent implementations of xml parsing/serialization (based upon the Android implementation) and DOM (a simple implementation that mirrors the Java API)

   implementation("io.github.pdvrieze.xmlutil:serialization:1.0.0-RC1")

To serialize a very simple type you have the following:

@Serializable
data class HelloWorld(val user: String)

println(XML1_0.encodeToString(HelloWorld("You!")))

To deserialize you would do:

@Serializable
data class HelloWorld(val user: String)

XML1_0.decodeFromString(HelloWorld.serializer(), "<HelloWorld user='You!' />")

Please look at the examples and the documentation for further features that can influence: the tag names/namespaces used, the actual structure used (how lists and polymorphic types are handled), etc.

You should be able to find examples in the Examples module

The entrypoint to the library is the XML1_0 (for 1.0) format (or XML generally). There is a default, but often a child is better. Custom formats are created through:

val format = XML1_0.recommended(mySerialModule) {  
    // configuration options
    xmlDeclMode = XmlDeclMode.None
    policy {
        typeDiscriminatorName = QName(XMLConstants.XSI_NS_URI, "type", XMLConstants.XSI_PREFIX)
    }
}

The configuration for the XML format is separated between the configuration, and embedded inside it a policy. The configuration mainly covers the xml serialization, but not how serializable types are reflected in XML. The policy is designed to allow for programmatic determination of how serialization occurs.

The following options are available when using the XML format builder. For new code you should use the XML1_0 entry point. This entry point is equivalent to the recommended configuration for version 0.92.0.

There are four functions to create a new XML format. They provide different presets for the configuration (that can then be adjusted through the configuration function).

Each presets provides access to the configuration builder with the following options (and access to both the policy property for setting the policy as well as the policy function for further configuring the policy):

The defaults are:

The properties that have been moved into the policy can still be set in the builder, but are no longer able to be read through the config object.

The following options are available as part of the default policy builder. Note that the policy is designed to allow configuration through code, but the default policy has significant configuration options available.

The defaults for the options are:

The overridable functions of policies are:

XML and Kotlin data types are not perfectly alligned. As such there are some algorithms that aim to automatically make a "best attempt" at structuring the XML document. Most of this is implemented in the default XmlSerializationPolicy implementation, but this can be customized/replaced with a policy that results in a different structure. The policy includes the mapping from types/attributes to tag and attribute names.

In the default policy, the way a field is stored is automatically determined to be one of: Element, Attribute, Text or Mixed. Mixed is a special type that allows for mixing of text and element content and requires some special treatment.:

• If a field is annotated with @XmlElement or XmlValue this will take precedence. The XmlValue tag will allow the field to hold element text content (direct only).

• If the serializer is a primitive this will normally be serialized as attribute

• If the serializer is a list, if there is an @XmlChildrenName annotation, this will trigger named list mode where a wrapper tag (element) is used. Otherwise the list elements, even primitives, will be written directly as tags (even primitives) without any wrapper list tags.

• If a list has the @XmlValue tag, this will allow the list to hold mixed content. To actually support text content it needs to be a list of Any. This should also be polymorphic (but the annotation is required).

  • Lists of Elements (using ElementSerializer) and CompactFragments support arbitrary content and provide it as lists of fragments or nodes.

• If a primitive is written as tag, the type name is used as tag name, and value as its element content.

• A primitive written as TEXT will be text content only, but note that there are only few cases where this is valid.

• Polymorphic properties are treated specially in that the system does not use/require wrappers. Instead it will use the tag name to determine the type. The name used is either specified by an @XmlPolyChildren annotation or through the type's serialDescriptor. This also works inside lists, including transparent (invisible) lists. If multiple polymorphic properties have the same subtags, this is an error that may lead to undefined behaviour (you can use the @XmlPolyChildren to have different names).

  A custom policy is able to determine on individual basis whether transparent polymorphism should be used, but the default policy provides an overall toggle (which also respects the autopolymorphic property of the configuration builder). The default will always trigger transparent mode if XmlPolyChildren is present.

• If the serializer is polymorphic, tag mode will be enforced. If @XmlPolyChildren is specified or autoPolymorphic is set it triggers transparent polymorphism mode where the child name is used to look up the property it belongs to. (note that this is incorrect with multiple properties that could contain the same polymorphic value - unless @XmlPolyChildren overrides it).

• Otherwise it will be written as a tag.

The way the name is determined is configured/implemented through the configured policy. The documentation below is for the default policy. This is designed to allow customization by users.

Based upon the storage type, the effective name for an attribute is determined as follows:

• @XmlSerialName at property declaration site
• @XmlSerialName at type declaration site
• @SerialName at property declaration site
• property name at property declaration site (note that the @SerialName annotation is invisible to the encoder)

The effective name for a regular tag is determined as follows for normal serializers:

• @XmlSerialName at property declaration site
• @XmlSerialName at type declaration site
• @SerialName at type declaration site
• type name at type declaration site. The default type declaration type name is the Kotlin/Java type name (and long). The system will try to shorten this by eliding the package name. This is configurable in the policy.

The effective name for a polymorphic child is determined as follows:

• If the child is transparent, the annotations/serial name of the effective type is used (unless overridden by @XmlPolyChildren)
• If the child is not transparent, the container is treated as a regular tag. It will have a type attribute to contain the serial name of the type (shortened to share the package name with the container). The value will use the default name value.

The implementation if serialization in the Kotlin compiler does not allow distinguishing between the automatic name and a @SerialName annotation. The default implementation supposes that if there is a '.' character in the name, this is a java type name and it strips the package out. (This also when it could be an attribute).

If you need to support names with dots in your format, either use the @XmlSerialName annotation, or use a different policy.

The annotations that specify names have common attributes: value:String, namespace:String and prefix:string. They have common semantics:

Annotation explanation.

These types have contextual support by default (without needed user intervention), but the serializer can also be specified explicitly by the user. They get special treatment to support their features.

By default (configurable by the policy) QName is handled by special logic that stores QNames in a prefix:localName manner ensuring the prefix is valid in the tag. Many XML standards use this approach for string attributes.

The CompactFragment class is a special class (with supporting serializer) that will be able to capture the tag soup content of an element. Instead of using regular serialization its custom serializer will (in the case of xml serialization) directly read all the child content of the tag and store it as string content. It will also make a best effort attempt at retaining all namespace declarations necessary to understand this tag soup.

Alternatively the serialutil subproject contains the nl.adaptivity.serialutil.MixedContent type that allows for typesafe serialization/deserialization of mixed content with the proviso that the serialModule must use Any as the baseclass for the content.

Container for the core library (versions). It provides XML functionality and is mostly platform independent.

Deprecated module for Android specific parsing. This is deprecated as the generic implementations are improved on the basis of the Android implementation.

Module that provides kotlinx.io bindings to the core xml library.

Module that provides access to JDK specific types (stax) and the platform parser. This is not needed for most cases, except where integration with JDK STaX parsing is required.

The kotlinx.serialization format to allow serialization to XML.

Additional shortcut bindings that provide direct access to kotlinx.io based streams (avoiding the need to use core-io directly to create the stream).

An auxiliary library that provides some utility functions for working with serialization. This is not specific to XML.