From 74aff67dd761f1b4e19a74c494a01d665cc3c855 Mon Sep 17 00:00:00 2001 From: Thibault Pensec Date: Fri, 6 Feb 2026 20:02:56 +0100 Subject: [PATCH] Add required properties to OpenAPI schemas This change adds 'required' property declarations to schemas based on the official Hue CLIP API documentation. Changes include: - Common schemas: Resource, ResourceIdentifier, ResourceOwned, GamutPosition, On, Dimming, Color, error, ApiResponse - Resource Get schemas: RoomGet, DeviceGet, SceneGet, LightGet, MotionGet, BridgeGet, BridgeHomeGet, TemperatureGet, DevicePowerGet, LightLevelGet, ActionGet, ProductData This ensures code generators produce properly typed models with non-optional fields where the API guarantees their presence. Fixes #44 Co-Authored-By: Warp --- .gitignore | 2 + src/bridge/schemas/BridgeGet.yaml | 7 ++- src/bridge_home/schemas/BridgeHomeGet.yaml | 3 ++ src/common/ApiResponse.yaml | 3 ++ src/common/Color.yaml | 2 + src/common/Dimming.yaml | 2 + src/common/GamutPosition.yaml | 3 ++ src/common/On.yaml | 2 + src/common/Resource.yaml | 3 ++ src/common/ResourceIdentifier.yaml | 3 ++ src/common/ResourceOwned.yaml | 2 + src/common/error.yaml | 4 ++ src/device/schemas/DeviceGet.yaml | 11 +++++ src/device/schemas/ProductData.yaml | 7 +++ src/device_power/schemas/DevicePowerGet.yaml | 4 +- src/light/schemas/LightGet.yaml | 25 ++++++++++ src/light_level/schemas/LightLevelGet.yaml | 6 +++ src/motion/schemas/MotionGet.yaml | 8 +++- src/room/schemas/RoomGet.yaml | 7 +++ src/scene/schemas/ActionGet.yaml | 49 ++++++++++---------- src/scene/schemas/SceneGet.yaml | 7 +++ src/temperature/schemas/TemperatureGet.yaml | 6 +++ 22 files changed, 138 insertions(+), 28 deletions(-) diff --git a/.gitignore b/.gitignore index 08e2925..e7aa5c9 100644 --- a/.gitignore +++ b/.gitignore @@ -85,3 +85,5 @@ fabric.properties # IntelliJ HTTP Client *.private.env.json + +onlinedoc.html diff --git a/src/bridge/schemas/BridgeGet.yaml b/src/bridge/schemas/BridgeGet.yaml index d734ec9..163d088 100644 --- a/src/bridge/schemas/BridgeGet.yaml +++ b/src/bridge/schemas/BridgeGet.yaml @@ -3,6 +3,9 @@ description: Definition of a bridge resource allOf: - $ref: '../../common/ResourceOwned.yaml' - type: object + required: + - bridge_id + - time_zone properties: type: type: string @@ -10,9 +13,11 @@ allOf: - bridge bridge_id: type: string - description: Unique identifier of the bridge as printed on the device. Lower case (shouldn't it be upper case?) + description: Unique identifier of the bridge as printed on the device. Lower case. time_zone: type: object + required: + - time_zone properties: time_zone: type: string diff --git a/src/bridge_home/schemas/BridgeHomeGet.yaml b/src/bridge_home/schemas/BridgeHomeGet.yaml index 52e52db..db328b9 100644 --- a/src/bridge_home/schemas/BridgeHomeGet.yaml +++ b/src/bridge_home/schemas/BridgeHomeGet.yaml @@ -3,6 +3,9 @@ description: Definition of a bridge resource allOf: - $ref: '../../common/Resource.yaml' - type: object + required: + - children + - services properties: type: type: string diff --git a/src/common/ApiResponse.yaml b/src/common/ApiResponse.yaml index 6e9a730..c79c939 100644 --- a/src/common/ApiResponse.yaml +++ b/src/common/ApiResponse.yaml @@ -1,4 +1,7 @@ type: object +required: + - errors + - data properties: errors: type: array diff --git a/src/common/Color.yaml b/src/common/Color.yaml index 309b11d..09f0cda 100644 --- a/src/common/Color.yaml +++ b/src/common/Color.yaml @@ -1,4 +1,6 @@ type: object +required: + - xy properties: xy: $ref: ./GamutPosition.yaml diff --git a/src/common/Dimming.yaml b/src/common/Dimming.yaml index e321888..fa81036 100644 --- a/src/common/Dimming.yaml +++ b/src/common/Dimming.yaml @@ -1,4 +1,6 @@ type: object +required: + - brightness properties: brightness: $ref: './Brightness.yaml' diff --git a/src/common/GamutPosition.yaml b/src/common/GamutPosition.yaml index cc07c6e..5831971 100644 --- a/src/common/GamutPosition.yaml +++ b/src/common/GamutPosition.yaml @@ -1,5 +1,8 @@ type: object description: CIE XY gamut position +required: + - x + - y properties: x: type: number diff --git a/src/common/On.yaml b/src/common/On.yaml index 2b3fa68..b329c11 100644 --- a/src/common/On.yaml +++ b/src/common/On.yaml @@ -1,4 +1,6 @@ type: object +required: + - on properties: on: type: boolean diff --git a/src/common/Resource.yaml b/src/common/Resource.yaml index 16c09a5..d7e76d3 100644 --- a/src/common/Resource.yaml +++ b/src/common/Resource.yaml @@ -1,5 +1,8 @@ type: object description: Common resource properties +required: + - type + - id properties: type: type: string diff --git a/src/common/ResourceIdentifier.yaml b/src/common/ResourceIdentifier.yaml index 2ced114..9db9091 100644 --- a/src/common/ResourceIdentifier.yaml +++ b/src/common/ResourceIdentifier.yaml @@ -1,4 +1,7 @@ type: object +required: + - rid + - rtype properties: rid: type: string diff --git a/src/common/ResourceOwned.yaml b/src/common/ResourceOwned.yaml index 8f7e6d7..4fbc4c5 100644 --- a/src/common/ResourceOwned.yaml +++ b/src/common/ResourceOwned.yaml @@ -3,6 +3,8 @@ description: Common resource properties including the owner allOf: - $ref: './Resource.yaml' - type: object + required: + - owner properties: owner: $ref: './ResourceIdentifier.yaml' diff --git a/src/common/error.yaml b/src/common/error.yaml index d001e96..75bc291 100644 --- a/src/common/error.yaml +++ b/src/common/error.yaml @@ -67,6 +67,8 @@ components: schemas: ErrorResponse: type: object + required: + - errors properties: errors: type: array @@ -74,6 +76,8 @@ components: $ref: '#/components/schemas/Error' Error: type: object + required: + - description properties: description: type: string diff --git a/src/device/schemas/DeviceGet.yaml b/src/device/schemas/DeviceGet.yaml index e7d8e97..faf7aac 100644 --- a/src/device/schemas/DeviceGet.yaml +++ b/src/device/schemas/DeviceGet.yaml @@ -3,6 +3,11 @@ description: Definition of a device resource allOf: - $ref: '../../common/ResourceOwned.yaml' - type: object + required: + - product_data + - metadata + - identify + - services properties: type: type: string @@ -12,6 +17,9 @@ allOf: $ref: './ProductData.yaml' metadata: type: object + required: + - name + - archetype properties: name: type: string @@ -20,6 +28,9 @@ allOf: description: Human readable name of a resource archetype: $ref: './ProductArchetype.yaml' + identify: + type: object + description: Triggers a visual identification sequence on the device usertest: type: object properties: diff --git a/src/device/schemas/ProductData.yaml b/src/device/schemas/ProductData.yaml index b08ec73..4fcecdc 100644 --- a/src/device/schemas/ProductData.yaml +++ b/src/device/schemas/ProductData.yaml @@ -1,4 +1,11 @@ type: object +required: + - model_id + - manufacturer_name + - product_name + - product_archetype + - certified + - software_version properties: model_id: type: string diff --git a/src/device_power/schemas/DevicePowerGet.yaml b/src/device_power/schemas/DevicePowerGet.yaml index 30cf67b..d6acc15 100644 --- a/src/device_power/schemas/DevicePowerGet.yaml +++ b/src/device_power/schemas/DevicePowerGet.yaml @@ -1,8 +1,10 @@ type: object -description: Definition of a bridge power resource +description: Definition of a device power resource allOf: - $ref: '../../common/ResourceOwned.yaml' - type: object + required: + - power_state properties: power_state: type: object diff --git a/src/light/schemas/LightGet.yaml b/src/light/schemas/LightGet.yaml index 0331e3f..fa25fca 100644 --- a/src/light/schemas/LightGet.yaml +++ b/src/light/schemas/LightGet.yaml @@ -2,21 +2,46 @@ type: object allOf: - $ref: '../../common/ResourceOwned.yaml' - type: object + required: + - metadata + - identify + - service_id + - on + - mode properties: metadata: type: object description: Deprecated, use metadata on device level + required: + - name + - archetype + - function properties: name: type: string description: Human readable name of a resource archetype: $ref: './LightArchetype.yaml' + function: + type: string + description: Function of the light service + enum: + - functional + - decorative + - mixed + - unknown fixed_mired: type: integer minimum: 153 maximum: 500 description: A fixed mired value of the white lamp + identify: + type: object + description: Triggers identification sequence on the light + service_id: + type: integer + minimum: 0 + description: Service identification number. 0 indicates service of a single instance on: $ref: '../../common/On.yaml' dimming: diff --git a/src/light_level/schemas/LightLevelGet.yaml b/src/light_level/schemas/LightLevelGet.yaml index c1bb1ed..e2fbe10 100644 --- a/src/light_level/schemas/LightLevelGet.yaml +++ b/src/light_level/schemas/LightLevelGet.yaml @@ -2,12 +2,18 @@ type: object allOf: - $ref: '../../common/ResourceOwned.yaml' - type: object + required: + - enabled + - light properties: enabled: type: boolean description: true when sensor is activated, false when deactivated light: type: object + required: + - light_level + - light_level_valid properties: light_level: type: integer diff --git a/src/motion/schemas/MotionGet.yaml b/src/motion/schemas/MotionGet.yaml index 768514f..a857be5 100644 --- a/src/motion/schemas/MotionGet.yaml +++ b/src/motion/schemas/MotionGet.yaml @@ -2,12 +2,18 @@ type: object allOf: - $ref: '../../common/ResourceOwned.yaml' - type: object + required: + - enabled + - motion properties: enabled: type: boolean - description: ture when the sensor is activated, false when deactivated + description: true when the sensor is activated, false when deactivated motion: type: object + required: + - motion + - motion_valid properties: motion: type: boolean diff --git a/src/room/schemas/RoomGet.yaml b/src/room/schemas/RoomGet.yaml index be89f1e..5cc0618 100644 --- a/src/room/schemas/RoomGet.yaml +++ b/src/room/schemas/RoomGet.yaml @@ -2,6 +2,10 @@ type: object allOf: - $ref: '../../common/Resource.yaml' - type: object + required: + - children + - services + - metadata properties: children: type: array @@ -22,6 +26,9 @@ allOf: metadata: type: object description: configuration object for a room + required: + - name + - archetype properties: name: type: string diff --git a/src/scene/schemas/ActionGet.yaml b/src/scene/schemas/ActionGet.yaml index eb34cf2..eea3f3e 100644 --- a/src/scene/schemas/ActionGet.yaml +++ b/src/scene/schemas/ActionGet.yaml @@ -1,29 +1,28 @@ type: object -allOf: - - $ref: '../../common/ResourceOwned.yaml' - - type: object +required: + - target + - action +properties: + target: + description: The identifier of the light to execute the action on + $ref: '../../common/ResourceIdentifier.yaml' + action: + type: object + description: The action to be executed on recall properties: - target: + on: + $ref: '../../common/On.yaml' + dimming: + $ref: '../../common/Dimming.yaml' + color: + $ref: '../../common/Color.yaml' + color_temperature: + $ref: '../../common/ColorTemperature.yaml' + gradient: + $ref: '../../common/Gradient.yaml' + effects: type: object - description: The identifier of the light to execute the action on - $ref: '../../common/ResourceIdentifier.yaml' - action: - type: object - description: The action to be executed on recall + description: Basic feature containing effect properties. properties: - on: - $ref: '../../common/On.yaml' - dimming: - $ref: '../../common/Dimming.yaml' - color: - $ref: '../../common/Color.yaml' - color_temperature: - $ref: '../../common/ColorTemperature.yaml' - gradient: - $ref: '../../common/Gradient.yaml' - effects: - type: object - description: Basic feature containing effect properties. - properties: - effect: - $ref: '../../common/SupportedEffects.yaml' + effect: + $ref: '../../common/SupportedEffects.yaml' diff --git a/src/scene/schemas/SceneGet.yaml b/src/scene/schemas/SceneGet.yaml index 4555291..1ace812 100644 --- a/src/scene/schemas/SceneGet.yaml +++ b/src/scene/schemas/SceneGet.yaml @@ -2,6 +2,13 @@ type: object allOf: - $ref: '../../common/ResourceOwned.yaml' - type: object + required: + - actions + - metadata + - group + - speed + - auto_dynamic + - status properties: type: type: string diff --git a/src/temperature/schemas/TemperatureGet.yaml b/src/temperature/schemas/TemperatureGet.yaml index c24a5a7..911cae0 100644 --- a/src/temperature/schemas/TemperatureGet.yaml +++ b/src/temperature/schemas/TemperatureGet.yaml @@ -2,6 +2,9 @@ type: object allOf: - $ref: '../../common/ResourceOwned.yaml' - type: object + required: + - enabled + - temperature properties: enabled: type: boolean @@ -9,6 +12,9 @@ allOf: `true` when sensor is activated, `false` when deactivated temperature: type: object + required: + - temperature + - temperature_valid properties: temperature: type: number