YAML configuration: add support for items/metadata/channel links

[lolodomo]

This PR adds the support of items in the YAML configuration file.
It also includes the support of items metadata and items channel links.

Related to #3666

[lolodomo]

This PR is based on and depends on PR #4753. The PR will be rebased when this other PR is merged.

[lolodomo]

The PR is almost finished, let's say at 97%. I would like to finish unit tests for YAMLItemDTO class and I would like to add a small enhancement to avoid updating an unchanged metadata or unchanged channel link when updating an item.

[lolodomo]

Here is an example of file generated:

version: 2
items:
  C:
    type: Group
    label: Group C
    groups:
      - X
      - U
  DemoSwitchGroup:
    type: Group
    group:
      type: Switch
      function: Or
      parameters:
        - "ON"
        - "OFF"
    tags:
      - home-group
  DemoSwitchGroup2:
    type: Group
    group:
      type: Switch
  GMetadata:
    type: Group
    metadata:
      test1:
        value: Value test1
        config:
          param1: A metadata text
          param2: 50
      test2:
        config:
          param1: -5
          param2: 31.25
          param3: true
      test3:
        value: Value test3
      test4: {}
      test5:
        value: List String
        config:
          param:
            - First
            - Second
      test6:
        value: List boolean
        config:
          param:
            - true
            - false
      test7:
        value: List number
        config:
          param:
            - 5
            - -5
            - 0.25
  DemoDimmer:
    type: Dimmer
    autoupdate: false
    groups:
      - DemoSwitchGroup
    metadata:
      expire:
        value: 30m
  DemoHumidity:
    type: Number
    dimension: Dimensionless
    label: Humidity
    icon: humidity
    format: < %.0f %% >
    unit: '%'
    groups:
      - U
      - C
    tags:
      - Humidity
      - Measurement
    metadata:
      listWidget:
        config:
          action: ""
          iconUseState: true
  DemoTemperature:
    type: Number
    dimension: Temperature
    label: Setpoint
    icon: temperature
    format: '%.1f °C'
    groups:
      - C
    tags:
      - Setpoint
      - Temperature
  test:
    type: String
    metadata:
      commandDescription:
        config:
          options: "0=value 0,1,2=Value 2"
      stateDescription:
        config:
          options: "0=Valeur 0,1=Valeur 1,2"
          pattern: '%s'
  test_0_2:
    type: Number
    dimension: Pressure
    label: "Label , Test = 1"
    icon: if:noto-v1:cityscape-at-dusk
    unit: bar
    groups:
      - DemoSwitchGroup
      - C
    tags:
      - Sensor
    metadata:
      commandDescription:
        value: ' '
        config:
          options: "0=Valeur 0,1=Valeur 1"
      ga:
        value: Lock
        config:
          inverted: true
  MagicColor:
    type: Color
    channel: magic:color-light:magicColor:color
  YamlLuneEvenementPeriode:
    type: String
    label: Événement Période
    tags:
      - Point
    channels:
      astro:moon:e2015c6f37:rise#event:
        profile: system:trigger-event-string
  YamlLuneHeureDebut:
    type: DateTime
    label: Heure Début
    format: '%1$td/%1$tm/%1$tY %1$tR'
    tags:
      - Point
    channel: astro:moon:e2015c6f37:rise#start
  YamlLuneHeureFin:
    type: DateTime
    label: Heure Fin
    format: '%1$td/%1$tm/%1$tY %1$tR'
    autoupdate: false
    tags:
      - Point
    channels:
      astro:moon:e2015c6f37:rise#end:
        profile: system:timestamp-offset
        offset: 30
      astro:moon:e2015c6f37:rise#start: {}

[spacemanspiff2007]

Since #4724 is merged I think it would be easy to provide a dedicated field for expire.
You can just move the whole entry to the configuration map.

  DemoDimmer:
    type: Dimmer
    autoupdate: false
    groups:
      - DemoSwitchGroup
    metadata:
      expire:
        value: 30m

would be

  DemoDimmer:
    type: Dimmer
    autoupdate: false
    groups:
      - DemoSwitchGroup
    expire:
        duration: 30m

That way all core functionalities would be available directly on the item.

---

You also opted to pull down statePattern, can you explain your reasoning?

[lolodomo]

expire will be added later in a separate PR, either by me or someone else.

statePattern allows defining a state pattern without doing it through metadata, Short version and same principle as for unit and autoupdate. Something largely more common/useful than expire, as it will be used by everybody.

[spacemanspiff2007]

Something largely more common/useful than expire

That's highly subjective.

, as it will be used by everybody.

I for example have never used it so it's for sure not going to be used by everybody. 😉

---

I've already searched in in the docs and you seem to refer to the state representation and it seems to be a MainUI feature.
I'm not sure if a somewhat strong coupling the core object configuration format with a UI feature is desirable.
It's an unnecessary hard link between an core object and a visualization.
In the past UIs came and went: Classic UI, Paper UI, now Main UI and Basic UI.
Additionally we have the more exotic UIs like HABPanel.
What's the rule about providing convenience on the core object for a visualization?
Is it "if somebody does it we'll accept it"?

Providing convenience for core functionalities is a simple rule which also makes a lot of sense since the configuration and object creation is done by the core.
I'm afraid that providing convenience for UI functionalities will pollute the otherwise clean solution and cause issues in the long run.

[lolodomo]

You apparently lost one major feature of OH, customising how the item state is rendered. This can be set with Main UI but also with the items file. With DSL, it was either in metadata (stateDescription) or in the label itself. In YAML, it is either in metadata (stateDescription) or in this statePattern field. It is better to separate it from the label, it avoids manipulating the label to extract what is inside [] and it is more intuitive for the user.
But you are not forced to use it.

[spacemanspiff2007]

So the statePattern is not the state-representation which according to the docs I linked above is a MainUI only feature?

Of course I'm aware how to change the shown value by putting the formatting brackets in the label.
Will putting the format brackets in the label no longer work?

[lolodomo]

Of course I'm aware how to change the shown value by putting the formatting brackets in the label.
Will putting the format brackets in the label no longer work?

Yes, this is replaced by the statePattern field. It avoids putting several data in the label with a particular syntax.

[spacemanspiff2007]

Yes, this is replaced by the statePattern field. It avoids putting several data in the label with a particular syntax.

I was not aware that the brackets in the label will no longer work and that's a big breaking change.
However I agree it makes sense to use a dedicated field for it.

I'm not happy with the name. statePatternis too long and hard to type and it's not clear what it does.
Also it's not always correct since MAP(window_esp.map):%s is not really a pattern.
How about format? This would align with the fact that one does apply the Java formatter class syntax.

[lolodomo]

No breaking change as we are building something new.
Ok to rename the field to format.

[lolodomo]

and I would like to add a small enhancement to avoid updating an unchanged metadata or unchanged channel link when updating an item.

Done

[lolodomo]

PR is now rebased and is now ready for a review.

[Copilot]

Pull Request Overview

This PR enhances YAML configuration support by adding item support along with metadata and channel link handling. Key changes include updates to the core item factory to register as an ItemFactory, extensive test coverage for YAML DTOs (items and groups), and new file converters and providers for YAML‐based items, metadata, and channel links.

Reviewed Changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
bundles/org.openhab.core/src/main/java/org/openhab/core/library/CoreItemFactory.java	Expanded OSGi service registration to include ItemFactory.
bundles/org.openhab.core.model.yaml/src/test/java/org/openhab/core/model/yaml/internal/items/YamlItemDTOTest.java	Added tests validating item type, dimension, groups, icon, channel formats, etc.
bundles/org.openhab.core.model.yaml/src/test/java/org/openhab/core/model/yaml/internal/items/YamlGroupDTOTest.java	Added tests for group DTO behavior including base type and function validation.
bundles/org.openhab.core.model.yaml/src/main/java/org/openhab/core/model/yaml/internal/util/YamlElementUtils.java	Refactored utility methods with condensed ternary handling for config maps and lists.
bundles/org.openhab.core.model.yaml/src/main/java/org/openhab/core/model/yaml/internal/items/fileconverter/YamlItemFileConverter.java	Introduced YAML item file conversion and integration with metadata and channel links.
bundles/org.openhab.core.model.yaml/src/main/java/org/openhab/core/model/yaml/internal/items/YamlItemProvider.java	Integrated YAML item provisioning with channel link and metadata processing.
... and other YAML-related DTO/provider files	Supporting additions and updates to metadata, channel links, and overall YAML model handling.

[kaikreuzer]

Thanks!

[lolodomo]

Thank you Kai.
While you merged in parallel another PR, I need to make a small fix. I will create a new PR immediately.