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.
The namespaces and attributes will not be considered a special case.
Parameters
- xmlValue xml - The XML source to be converted to a given target type
- returnType typedesc<(map<anydata>)> (default <>) - The
typedescof themap<anydata>that should be returned as a result
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.
The record has annotations to configure namespaces and attributes,
but others don't have these.
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.
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.
xmldata: Namespace
typeThe annotation is used to specify the namespace's prefix and URI of the XML element.
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 new name of the name.
Fields
- value string - The value of the new name
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.