xmldata
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?|Error
Converts 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:JsonOptions
record 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. MISSING[
]
- xmlValue - 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 - The
typedesc
of the returned value. this should be eithermap
orrecord
type. - return - 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|Error
Converts 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:XmlOptions
record 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|Error
Converts 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
typedesc
of 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:Error
Deprecated
This function is going away in a future release. UsefromXml
instead.
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. MISSING[
]
Parameters
- mapValue map<anydata> - The
Map
orRecord
representation source to be converted to XML
Annotations
xmldata: Attribute
The 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
The 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
The 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.
Import
import ballerina/xmldata;
Metadata
Released date: over 1 year ago
Version: 2.4.1
License: Apache-2.0
Compatibility
Platform: java11
Ballerina version: 2201.4.0
GraalVM compatible: Yes
Pull count
Total: 16109
Current verison: 1110
Weekly downloads
Keywords
xml
json
Contributors