Module xmldata
ballerina/xmldata Ballerina library
Overview
This module provides APIs to perform conversions between XML and JSON/Ballerina records. It provides APIs to get natural representations of data in XML from JSON and to get JSON or Ballerina records data from natural representations of data in XML.
For information on the operations, which you can perform with the xmldata module, see the below Functions.
Functions
fromJson
function fromJson(json jsonValue, JsonOptions options) returns xml?|ErrorConverts a JSON object to an XML representation.
json data = { name: "John", age: 30 }; xml? xmlValue = check xmldata:fromJson(data);
Parameters
- jsonValue json - The JSON source to be converted to XML
- options JsonOptions (default {}) - The
xmldata:JsonOptionsrecord for JSON to XML conversion properties
fromXml
Converts an XML to its Map or Record representation.
Additionally, when converting to a record, XML namespaces, name of elements and attributes can be validated
through xmldata:Namespace, xmldata:Name and xmldata:Attribute annotations.
Parameters
- xmlValue xml - The XML source to be converted to a given target type. If the XML elements have a prefix, the mapping field names of the record must also have the same prefix.
- returnType typedesc<map<anydata>> (default <>) - The
typedescof the returned value. this should be eithermaporrecordtype
Return Type
- returnType|Error - The given target type representation of the given XML on success,
else returns an
xmldata:Error
toJson
function toJson(xml xmlValue, XmlOptions options) returns json|ErrorConverts an XML object to its JSON representation.
xml xmlValue = xml `<!-- outer comment -->` + xml `<name>supun</name>`; json jsonValue = check xmldata:toJson(xmlValue);
Parameters
- xmlValue xml - The XML source to be converted to JSON
- options XmlOptions (default {}) - The
xmldata:XmlOptionsrecord consisting of the configurations for the conversion
Return Type
- json|Error - The JSON representation of the given XML on success, else returns an
xmldata:Error
toRecord
function toRecord(xml xmlValue, boolean preserveNamespaces, typedesc<record {}> returnType) returns returnType|ErrorConverts an XML to its Record representation.
type Person record { string name; }; xml xmlValue = xml `<!-- outer comment -->` + xml `<name>Alex</name>`; Person|xmldata:Error person = xmldata:toRecord(xmlValue);
Parameters
- xmlValue xml - The XML source to be converted to a Record
- preserveNamespaces boolean (default true) - Instructs whether to preserve the namespaces of the XML when converting
- returnType typedesc<record {}> (default <>) - The
typedescof the record that should be returned as a result. The optional value fields are not allowed in the record type.
Return Type
- returnType|Error - The Record representation of the given XML on success, else returns an
xmldata:ErrorDeprecated
This function is going away in a future release. UsefromXmlinstead.
toXml
Converts a Map or Record representation to its XML representation.
Additionally, when converting from a record, the xmldata:Namespace, xmldata:Name, and xmldata:Attribute
annotations can be used to add namespaces, name of elements, and attributes to XML representation.
Parameters
- mapValue map<anydata> - The
MaporRecordrepresentation source to be converted to XML
Annotations
xmldata: Attribute
record fieldThe annotation is used to denote the field that is considered an attribute.
In the XML-record conversion, this annotation can be used to add XML attribute using the xmldata:toXML API and
validate the XML attribute with record fields in the xmldata:fromXml API.
xmldata: Name
type, record fieldThe annotation is used to specify the new name of the existing record name or field name according to the XML format.
In the XML-record conversion, this annotation can be used to override the default XML element name using the
xmldata:toXML API and validate the overridden XML element name with record field using the xmldata:fromXml API.
xmldata: Namespace
typeThe annotation is used to specify the namespace's prefix and URI of the XML element.
In the XML-record conversion, this annotation can be used to add XML namespace using the xmldata:toXML API and
validate the the XML namespace with record in the xmldata:fromXml API.
Records
xmldata: JsonOptions
Provides configurations for converting JSON to XML.
Fields
- attributePrefix string(default "@") - The prefix of JSON elements' key which is to be treated as an attribute in the XML representation
- arrayEntryTag string(default "item") - The name of the XML elements that represent a converted JSON array entry
- rootTag string?(default ()) - The name of the root element of the XML that will be created. If its value is (), and the converted XML
is not in the valid format, it will create a root tag as
root
xmldata: NameConfig
Defines the name of the XML element.
Fields
- value string - The name of the XML element
xmldata: NamespaceConfig
Defines the namespace of the XML element
Fields
- prefix string? - The value of the prefix of the namespace
- uri string - The value of the URI of the namespace
xmldata: XmlOptions
Provides configurations for converting XML to JSON.
Fields
- attributePrefix string(default "@") - Attribute prefix used in the XML
- preserveNamespaces boolean(default true) - Instructs whether to preserve the namespaces of the XML when converting
Errors
xmldata: Error
Represents the error type of the ballerina/xmldata module. This error type represents any error that can occur during the execution of xmldata APIs.