-
Notifications
You must be signed in to change notification settings - Fork 71
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>"/> |