From: Ivan Kruglov Date: Tue, 14 Apr 2026 09:25:43 +0000 (-0700) Subject: docs: clarify when to use varlink enum types vs plain strings X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=3dd09ccea214726aa97f8c228528853d2c472a07;p=thirdparty%2Fsystemd.git 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 --- diff --git a/docs/VARLINK.md b/docs/VARLINK.md index 844c4ca516b..65f1950800b 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