Kiota should send properties in OAS declaration order, not alphabetic order

[bkoelman]

What are you generating using Kiota, clients or plugins?

API Client/SDK

In what context or format are you using Kiota?

Nuget tool

Client library/SDK language

Csharp

Describe the bug

My OAS file lists properties (in component schema) in an intentional order: type, id, firstName, lastName, age. While the last three vary per model, the first two are always present. Kiota ignores that and uses alphabetic order instead: age, firstName, id, lastName, type. This makes the payload harder to read, test, and debug.

Expected behavior

Preserve declaration order. In the case of inheritance, fields from base types come first.

How to reproduce

Open API description file

No response

Kiota Version

1.14.0

Latest Kiota version known to work for scenario above? (Not required)

No response

Known Workarounds

None

Configuration

No response

Debug output

No response

Other information

No response

[baywet]

Hi @bkoelman
Thanks for using kiota and for reaching out.
Can you outline further why do you think this makes things harder to debug?
The reasons why properties are in alphabetical order it to:

• get deterministic output
• ease debug/code reading (easier/faster to scan an ordered list than an unordered one)

[bkoelman]

The declaration order in OAS is already deterministic. All other code generators I've tried respect the declaration order.
Suppose a list of entities is returned, this:

[
  { "type": "user", "id": "1", "firstName": "John", "lastName": "Doe", "age": 25 },
  { "type": "order", "id": "1", "productName": "Laptop", "quantity": 1, "price": 1199.99, "units": "dollars" },
  { "type": "order", "id": "2", "productName": "Printer", "quantity": 1, "price": 349.99, "units": "dollars" }
]

is much easier to read than:

[
  { "age": 25, "firstName": "John", "id": "1", "lastName": "Doe", "type": "user" },
  { "id": "1", "price": 1199.99, "productName": "Laptop", "quantity": 1, "type": "order", "units": "dollars" },
  { "id": "2", "price": 349.99, "productName": "Printer", "quantity": 1, "type": "order", "units": "dollars" }
]

Lastly, specific implementations may depend on the ordering. Why else would System.Text.Json and Newtonsoft provide ways to control the order, other than to improve readability?

[baywet]

Thanks for the additional information.
I'm not sure why anybody would implement an API with dependencies on the order of properties for a JSON payload when the JSON RFC especially calls out object properties are unordered by nature.

An object is an unordered collection of zero or more name/value
pairs, where a name is a string and a value is a string, number,
boolean, null, object, or array.

This sounds like a bad design of the API itself that should be addressed in the API instead of pushing a constraint on clients. Do you have example scenarios that cannot be achieved through any other way than a specific ordering of the properties?

[bkoelman]

Not at the moment, but years ago I ran into that with XML more than once: Large commercial enterprise systems that we couldn't change because they were provided by external vendors, or because the source code got lost over time (yes, that happens, and more often than you'd think, even today). Or 3rd party external systems written in PHP, that didn't rely on an XML DOM parser, because at the time there wasn't one built-in yet. We had to work around these problems because getting the external systems changed was too expensive.

I agree that an implementation that depends on the order is a bad design, however, sometimes it's out of our control. But my primary concern is readability, as my sample shows.