From 3dd09ccea214726aa97f8c228528853d2c472a07 Mon Sep 17 00:00:00 2001 From: Ivan Kruglov Date: Tue, 14 Apr 2026 02:25:43 -0700 Subject: [PATCH] docs: clarify when to use varlink enum types vs plain strings Add guidance on when a field should use a proper varlink enum type versus remaining a plain string: user-controlled/API fields should be enums, engine-internal state fields may stay as strings. Co-developed-by: Claude Opus 4.6 --- docs/VARLINK.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/VARLINK.md b/docs/VARLINK.md index 844c4ca516..65f1950800 100644 --- a/docs/VARLINK.md +++ b/docs/VARLINK.md @@ -63,11 +63,22 @@ SPDX-License-Identifier: LGPL-2.1-or-later * `JSON_DISPATCH_ENUM_DEFINE` - creates a `json_dispatch_*` function that accepts both the original and the underscorified enum value as valid input. + For example, a `LogTarget` field outputs `"journal_or_kmsg"` (underscore + form), but on input both `"journal_or_kmsg"` and `"journal-or-kmsg"` are + accepted. This is handled automatically by `JSON_DISPATCH_ENUM_DEFINE`: + it first tries the value as-is via `_from_string()`, and if that fails, + replaces underscores with dashes and retries. + - An internal enum may be exposed as a simple string field instead of a Varlink enum type when the field is output-only and never provided or controlled by the user. However, such fields should avoid using dashes to prevent breaking changes if they are later converted into enums (see below). + For example, in `io.systemd.Unit`, configuration settings that users select + in unit files (e.g. `ProtectSystem`, `ExecInputType`) should be proper varlink + enum types. Runtime state fields that only the engine determines (e.g. + `ActiveState`, `SubState`) may remain plain strings. + - A varlink string field that has a finite set of possible values may later be converted into an enum without introducing a breaking change. This allows the interface to evolve from loosely defined string values to a more explicit and