Skip to content

Proposal: Introduce API to convert the Ballerina record to XML #2819

@kalaiyarasiganeshalingam

Description

Summary

The Ballerina Xmldata module doesn't have any API to convert the Ballerina record to XML directly. So, this proposal introduces a new fromRecord API to convert the Ballerina record to XML.

Goals

Provide a way to directly convert the Ballerina record to XML.

Motivation

When we are writing a connector for the SOAP backend service(e.g Netsuite Connector), we need to convert the Ballerina record value to XML payload. As mentioned in the summary, We don't have a way to convert the Ballerina record to XML. At the moment, users have to write their own custom implementation to convert Ballerina records to XML and it would be easy for them If we provide an API to convert.

Note: This feature is also required by the connector team and they are planning to remove their custom implementation and use xmldata module, once we have this feature.

Description

The API definition of this:

# Converts a Ballerina record to an XML representation.
# ```ballerina
# Employee data = {
#   name: "Asha"
# };
# xml? xmlValue = check xmldata:fromRecord(data);
# ```
#
# + recordValue - The Ballerina record to be converted to XML
# + arrayEntryTag - The name of the XML elements that represent 
#                   a converted JSON array entry when the JSON 
#                   array entry key is not present during the conversion
# + return - An XML representation of the given Ballerina record if the record is
#            successfully converted or else an `xmldata:Error`
public isolated function fromRecord(record {} recordValue, string arrayEntryTag = "item") returns xml|Error;

Rules for Record to XML Conversion

The following rules are used during the conversion process:

  • A default root element will be created When data contains multiple key-value pairs
    Person data = {
         fname: "John",
         lname: "Stallone"
     };
  • If JSON properties' keys have the prefix as _, those will be handled as attributes or namespaces in the XML.
  • If optional values in the Ballerina record are nil, those will be converted to empty XML elements in the XML.
    Person data = {
         fname: "John",
         lname: ()
     };
  • If optional fields are in the Ballerina record, those will be skipped.

The following table shows a mapping between the different forms of XML, to a corresponding matching Ballerina record representation by considering the above rules.

Record Type Record Sample XML Representation Type XML Representation of XML
Record has single
key-value
{name:"Asha"} Empty element <name>Asha</name>
Record has single
key-value and value is ""
{name:""} Empty element <name/>
Record has optional values {name: ()} Empty element <name/>
Empty record {} Empty Sequence ``
Record with
single key-value
{
  "store": {
    "name": "Anne",
    "address": {
     "street": "Main",
     "city": "94"
    }
  }
}
XML sequence <store>
  <name>Anne</name>
  <address>
    <street>Main</street>
    <city>94</city>
  </address>
</store>
Record with
multiple key-value pairs
{
   "key1":"value1",
   "key2":"value2"
}
XML sequence with root tag <root>
  <key1>value1</key1>
  <key2>value2</key2>
</root>
Record with key
as "\#content"
{"\#content":"value1"} XML text value1
Record with key
prefix as ‘_’
{
  "foo": {
    "_key": "value",
    "_xmlns\:ns0":"<http://sample.com>"
  }
}
XML element with attribute and namespace <foo key="value"
xmlns:ns0="<http://sample.com>"/>

Metadata

Metadata

Type

No type

Projects

Milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions