Round-tripping configuration via Code tab materializes default values

[lsiepel]

The otherwise excellent overhaul of the Code tab in MainUI introduced in 5.1.0 comes with a behavior that I think should be reconsidered.

According to the release notes, the Code tab now uses Core APIs to create and parse file-compatible configurations. As a result, this behavior appears to originate from Core rather than MainUI itself.

Current behavior
When creating a configuration (Thing, Channel, etc.), only explicitly set configuration parameters are initially stored.
However, when that configuration is later edited and saved via the MainUI Code tab, missing parameters are injected with their default values and written into the YAML.

This behavior is controlled by a setting (default: false) of the /file-format/create, but with the default configuration it still results in defaults being actively written into the code. See screenshot, have not yet seen a place where this can be controlled from the UI.

Why this is a problem
Persisting default values changes the semantics of configuration in a way that is both subtle and problematic:

• Defaults become frozen
  Once a default value is written explicitly, it will no longer follow future default changes in bindings or Core. Users who never touched the Code tab — or who use file-based configuration — will get updated defaults, while others won’t.

• Inconsistent behavior across configuration methods
  File-based configs typically omit defaults and therefore evolve naturally across upgrades. UI-edited configs diverge and become “sticky”, leading to unpredictable differences between setups.

• Breaks expectations around breaking changes
  Historically, changing a default has been a valid way to introduce behavior changes while keeping configs clean. This behavior undermines that model by silently turning defaults into user intent.

• Noisy diffs and reduced clarity
  Small edits can result in large YAML changes, making it harder to see what was actually configured intentionally.

Edit: Now when i look into the code i ask myself if this was intended or an unintended side effect of the overhaul. Not easy to compare, but looking at createFileFormatForItems and createFileFormatForThings are still set to true, consistent with the previous behavior.

[lolodomo]

If we want to hide default parameters, Main UI has just to call the /file-format/create API with the proper value (true) for the parameter.

I believe it was done like that intentionally by @jimtng to show all available parameters to the user. Like that, the user has not to guess how is named each parameter, he just has to update values.

Once again, it can be change very easily on Main UI side, this will of course satisfy the points you mentioned but the disadvantage is that the user can no more easily just change from a default value to another value in code tab, he first has to fill the parameter name he wants to update.

But I am fine if this is changed.

[lolodomo]

I should also mention that the other /file-format APIs having this parameter have a different default.
The API used when clicking "Copy File Definition" has this parameter set to true by default, leading to default parameters not being generated.

For things:

For items:

So maybe we should just change the default for /file-format/create API ?
In this case, there would be nothing to change in Main UI as Main UI is apparently not setting a value for this setting.

[lolodomo]

Let me know, this is just a "false" to replace by a "true" in the code.

I just would like to have @jimtng opinion regarding impact in code tab.

[jimtng]

I think hide should be false by default in core, and make mainui be specific in what it wants.
The benefit of this is that the people who are "trying out" the API can see the default values by default on their first try.

But I think this is very much personal preference, either way is fine as long as they all match up between core and the mainui consumers.

[lolodomo]

think hide should be false by default in core, and make mainui be specific in what it wants

In that case, it just has to be changed in Main UI when calling the API.

But I think this is very much personal preference, either way is fine as long as they all match up between core and the mainui consumers.

But what do you think to no more displaying default parameters in Main UI code tab ?

[lsiepel]

I believe it was done like that intentionally by @jimtng to show all available parameters to the user. Like that, the user has not to guess how is named each parameter, he just has to update values.

In practice that advantage is limited as on the other tab the users already sees all possible parameters. And they only see all the options in the code tab after it is changed and saved. IMO this certainly does not outweight the mentioned cons.

If in understand this correctly, the linked PR with the default value should not be accepted as this has to be done in MainUI ? If so, could you point me to the right place in MainUI, i will then create a PR there. Thanks!

[jimtng]

But what do you think to no more displaying default parameters in Main UI code tab ?

Ideally we do both:

• Default to hide the defaults
• option to show them

I'm happy to do this. We just need a toggle in the bottom toolbar, either an on/off slider button, a dual-state multi button, or a simple checkbox (the ugliest and takes up the most space).

[jimtng]

I've just had a look... it's not as simple as sending hideDefaultParameters => true or false, nor would changing the defaults in core make a difference. The payload that the UI is sending already contains the "default" stuff, hence what we get back contains it too. So we'd need to filter that in the UI, I guess, since the file-format converter would have no idea whether the value is the unchanged default or the explicit config that happens to be set to the default.

[jimtng]

@lsiepel have you noticed this issue on Items too?

[bjscheue]

I would like to point out that either default value for hideDefaultParameters comes with (different) problems. If parameters are added, this will freeze default values (and more, as pointed out in the issue description by @lsiepel).

However, if parameters are silently removed when their value happens to be the (current) default value, this also has (likely unintended) side effects:

1. Assume that in version x of a binding the default value of a parameter is A. A user wants the parameter to be B, though, and configures accordingly.
2. In version x+1 of the binding, the default value changes to B. When the user ever edits the configuration, the parameter will thus be automatically removed (because its value B equals the default B), probably without the user even noticing.
3. In version x+2 of the binding, the default changes to A again. The user's initial configuration will be lost, and the channel will suddenly begin using using parameter value A.

I think part of the problem here is that the configuration logic and the internal data structures (as it seems to me) do not distinguish between "parameter X has value A because the user explicitly wants it to be A" and "parameter X has value A because the user hasn't made a choice and A is the default".

[lsiepel]

However, if parameters are silently removed when their value happens to be the (current) default value, this also has (likely unintended) side effects

No, when explicitly set, the value (equal to default or not) should not be removed. It should be a one way proces. When the defaults are not provided, and the parameter is false, the defaults should be injected.

I think that behavior is already implemented and should not be changed.

[lsiepel]

@lsiepel have you noticed this issue on Items too?

I only tested this with thing/channel configuration. What would you exactly want me to look into?

[bjscheue]

If the intention is to inject the defaults in order to guide the user with respect to the available set of parameters, why not inject them as YAML comments?