Capability Schema Documentation

Where can we find documentation for all of the fields in the capability yml/json files? This document is pretty useful but doesn’t seem exhaustive. At the moment, I am trying to figure out what the field additionalProperties is used for? You can see it in the sample capability. I am also curious about how the schema.type is used as well as the required array. These are pretty much in all capabilities, but I’m not sure what they control in terms of behavior.

"attributes": {
    "colorTemperature": {
        "schema": {
            "type": "object",
            "properties": {
                "value": {
                    "type": "integer",
                    "minimum": 2600,
                    "maximum": 9000
                },
                "unit": {
                    "type": "string",
                    "enum": [
                        "K"
                    ],
                    "default": "K"
                }
            },
            "additionalProperties": false
        },
        "required": [
            "value"
        ]
    }
}

There are more details about it in the API reference for capabilities.

image

schema.type of an attribute is set to “object” because it is formed by the “value” and “unit” properties.
In the case of capability commands, the schema.type depends on the type of argument that the command receives (“string”, “number”; in the case of setColor in ColorControl, the type is “object” because the argument is a color_map)

required is used to define which property is mandatory for the attribute. By default, only “value” is required but, if we add “unit”, we would need to send both in the capability events, otherwise, we’ll receive an error. An example of that is temperatureMeasurement.

@nayelyz I’m still not clear on additionalProperties. Does that mean that if I define an enum, a driver would be able to set a value that is not in that enum? What would it mean for non-enum types?

My understanding is that it refers to other properties of the attribute that are not “value” or “unit”, which means it is not related to the “value” set for the capability and its type.
I’ll check with the team if they can provide more details about it.

BTW, if you define the property value.enum and send an event with a different value, it won’t be saved, is that what you meant?

1 Like

Yes. I have seen other drivers that display a list type, but somehow are changing the label to show text that is not in that enum. They must be doing something tricky with the presentation.

Aaah, I think I got you, so, a value is saved for the capability but in the app, you see a “pretty/human-readable” text.
That’s thanks to the “alternatives” property set in the presentation where “key” is the capability value and “value” is the “label”.
Just a head’s up, there’s an issue with the alternatives in the dashboard.state: when you send a value that doesn’t have an alternative configured. (Here’s a post about that)

I wasn’t referring to alternatives, but that is helpful to note. I have seen a driver actually put a dynamic value into a list display type in the detail view. It was a value built by the driver that didn’t exist in the enum nor in the alternatives. I would need to find it again to get more details.

I’ve seen that, if you send an unknown value, it is still shown but the value is not added to the list, which means it isn’t dynamic unless they’re changing the presentation…
Please, let me know if you figure out more, it could be a bug…

Following up on this, the additionalProperties value cannot be set to true, we receive the following error if we try:

{
    "requestId": "804BCEF9-D153-....",
    "error": {
        "code": "ConstraintViolationError",
        "message": "The request is malformed.",
        "details": [
            {
                "code": "UnprocessableEntityError",
                "target": "capabilityId.attributes.attrName.schema.additionalProperties",
                "message": "capabilityId.attributes.attrName.schema.additionalProperties: does not have a value in the enumeration [false]",
                "details": []
            }
        ]
    }
}

This means, only the properties of value, unit, and data are available for the attribute schema.

I’ve done a lot of experimentation with the list display type.

It’s not possible to dynamically change the list entries. You can dynamically filter the list entries, but all possibilities must be known prior to packaging the driver. Further, the filter is only applied when the list is initially populated. This means you need to leave detailView and return in order to see any changes. You can populate the state field to the left of the gear with any string you want.

The mediaPresets capability can be populated dynamically. The disadvantage is that nothing else about the presentation can be modified. The state area and label are fixed.

1 Like

Thanks. These responses are helpful. I think being able to set the list ‘state’ should do the trick. I’m guess this is also why the ‘modes’ and ‘scenes’ capabilities are not live yet in ST. The possible values need to be determined at runtime, and the platform won’t allow it yet.