Propose a format for individual pages for supported data formats

[MaryamZi]

Description

$title.

Part of #9590

Version

No response

[MaryamZi]

Proposal for JSON

---

Introduction

Ballerina knows JSON: JSON syntax is compatible with Ballerina and every JSON value has a natural representation in Ballerina. Working with JSON in Ballerina is intuitive, safe, and convenient with features such as the builtin json type, intuitive syntax for JSON navigation, lax static typing for JSON, support for efficiently converting between JSON and user-defined types, etc.

The json type

• Overview of the type
  • Include mapping from JSON representation to Ballerina representation.
    • E.g., Number - int, float, decimal
      Boolean - boolean
  • Elaborate that map is JSON object, not json
• Say can directly bind to JSON - HTTP snippets showing service/client data binding to JSON
  • Also mention with examples that you can directly data bind to a user-defined type, more details to follow.
• Typing with json - cover things like how lists and mappings can belong to json.
• Explain that json supports lax typing (with one example, can elaborate all scenarios later).

Converting from json to user-defined type

• Mention how simple values map to the relevant types, with examples using fromJsonWithType
• Explain how JSON object to record/map conversion works, with examples
• Explain how JSON array to array/tuple conversion works, with examples
• Have one example that combines all

Converting from json to user-defined type with custom field names

• jsondata:Name annotation usage

Converting from json to user-defined type with projection

• Introduce the need for projection.
• Mention any specific features we want to mention with projection.
• Introduce the parseAsType jsondata data module function with examples.

Parsing data as JSON or a user-defined type

• Langlib function - value:fromJsonString and value:fromJsonStringWithType

• jsondata data module functions with examples:

  • parseString
  • parseBytes
  • parseStream

  Need to mention that these can be used even if there’s no projection.

JSON to XML

• xmldata:fromJson

XML to JSON

• xmldata:parseAsType with record {| json...; |} as the expected type?

XML to JSON with projection

• xmldata:parseAsType with projection

Working with JSON values

• Converting to a user-defined type first
  • Mention when you would choose to do this.
    • Specify the benefits - data validation in one go, compile-time type checking for usage, better tooling experience, etc.
    • Also include that connectors would generally expose JSON responses as user-defined types, making it easier to work with the response. May make sense to add an example.
• Introduce the “Paste JSON as Record” VS Code command.

Working directly with the JSON values

• Mention when you would choose this over converting to a user-defined type first.
• JSON access (elaborating lax typing)
• JSONPath support - jsondata:read
• JSONFloat, JSONDecimal, and relevant functions
• value:mergeJson