Properties

A device property is a named JSON value attached to a device. Properties store configuration, reported state, and inventory data. This reference covers their access rules, advisory schemas, and version checks. For a device-side example, follow Device Configuration.

Use groups to organize devices by membership. Groups have their own catalog and assignments; property writes do not change them. Device selectors can combine group membership with property predicates.

Property Commands

Reading and writing through Nexigon Agent:

nexigon-agent device properties set <property key> <property value>
nexigon-agent device properties get <property key>

Reading and writing properties through Nexigon CLI:

nexigon-cli devices properties set <device id> <property key> <property value>
nexigon-cli devices properties get <device id> <property key>

The property key is a string, and the property value can be any JSON value. When entering a value in Nexigon Hub, use valid JSON syntax. For example, enter {"enabled": true} for an object or "production" (including the quotes) for a string.

To avoid conflicts with existing properties, we recommend using a domain prefix. For instance, we use dev.nexigon for properties whose structure is defined by Nexigon itself (e.g., system information under dev.nexigon.system.info).

Property Schemas

A project can associate a JSON Schema with an exact property name. The same definition guides the Nexigon Hub’s device and fleet property editors. Schemas are advisory: creating, changing, or deleting a schema does not validate or rewrite existing values. Device, Nexigon CLI, SDK, operation, and API writes remain unrestricted.

Every project includes read-only schemas for these Nexigon properties:

• dev.nexigon.system.info
• dev.nexigon.system.health
• dev.nexigon.ota.config
• dev.nexigon.ota.status
• dev.nexigon.commands

Project administrators manage custom definitions under Project Settings → Property Schemas. Built-in names cannot be replaced or removed. Other members can view the definitions.

The editor supports JSON Schema Draft 7, 2019-09, and 2020-12, with Draft 7 as the default when $schema is absent. References must resolve within the schema document. Forms support objects, arrays, strings, numbers, integers, booleans, and enumerated values. Other shapes remain editable as JSON source and are validated against the complete schema.

On a manual save through a property editor, the Nexigon Hub checks the draft against its schema. A mismatch leaves the draft open and shows validation errors. Select Set property despite validation errors, then choose Force Set Property to save it anyway. Changing the draft clears that approval. Invalid JSON must always be corrected before saving. If a schema cannot be loaded or compiled, the editor reports the problem and requires the same explicit override to save without validation.

Schema Actions

The projects_QueryPropertySchemas action returns custom and built-in definitions for a project. projects_SetPropertySchema creates or replaces a custom definition:

{
  "projectId": "p_...",
  "name": "com.example.sensor.config",
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "sample_rate_hz": {
        "type": "integer",
        "title": "Sample Rate (Hz)",
        "minimum": 1,
        "maximum": 100
      }
    },
    "required": ["sample_rate_hz"]
  }
}

Pass projectId and name to projects_RemovePropertySchema to delete a custom definition. Set and remove actions require permission to manage project settings; query requires project view permission. Mutations produce project audit events.

The API stores schema objects and booleans without checking their compatibility with existing values. The management UI checks that a schema can be compiled before saving it.

Protected Properties

Protected properties can only be read but not modified by the device. This is useful for storing device configurations and inventory information that must not be modified by the device itself (e.g., its serial number).

Versioning

Every property carries a version, a monotonically increasing counter that is incremented on each update. The version can be used to detect changes and to implement optimistic concurrency control.

When reading a property, the response includes the current version:

{
  "result": "Found",
  "value": { "state": "idle" },
  "version": 42
}

Compare-and-Swap

The SetDeviceProperty action supports an optional expectedVersion field for compare-and-swap (CAS) semantics. When set, the property is only updated if its current version matches the expected value. If the version has changed since you last read it, the action returns VersionConflict instead of modifying the property.

{
  "deviceId": "d_...",
  "name": "dev.nexigon.ota.status",
  "value": { "state": "installing" },
  "expectedVersion": 42
}

If the property’s version is still 42, the update succeeds and the version increments to 43:

{ "result": "Set" }

If another write happened in between (version is now 43), the update is rejected:

{
  "result": "VersionConflict",
  "currentVersion": 43
}

The caller can then re-read the property, merge or resolve the conflict, and retry.

When expectedVersion is not set, the property is updated unconditionally (the default behavior). For new properties that don’t exist yet, the version check is skipped and the insert always succeeds with version 1.

This is useful when multiple systems write to the same property concurrently, or when a property is used to drive a state machine where transitions must be atomic. The writer reads the property, computes the new value, and writes it back with the version it read, ensuring no other write happened in between.