From 3e39c546323acab3dec94106c96b6ad0a7fe4080 Mon Sep 17 00:00:00 2001 From: Ivan Kruglov Date: Wed, 14 Oct 2026 12:01:05 +0200 Subject: [PATCH] docs: clarify Varlink input and output policy (cherry picked from commit 1c754bf06e1369c39abcff411a317a058e9b0b91) --- docs/VARLINK.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/docs/VARLINK.md b/docs/VARLINK.md index 65f1950800..83a939271b 100644 --- a/docs/VARLINK.md +++ b/docs/VARLINK.md @@ -33,10 +33,10 @@ SPDX-License-Identifier: LGPL-2.1-or-later data that other functions can later consume to create a similar object. Example: `io.systemd.Unit.List` outputs unit configuration, which can later - be reused to create another unit via `io.systemd.Unit.StartTransient` (not - implemented yet). The `io.systemd.Unit.StartTransient` call should accept - only the 'context' portion of the output, without requiring any runtime data - such as state (e.g. pid) or statistics. + be reused to create another unit via `io.systemd.Unit.StartTransient`. + The `io.systemd.Unit.StartTransient` call should accept only the 'context' + portion of the output, without requiring any runtime data such as state + (e.g. pid) or statistics. - Following the guideline above, any field within 'context' should be nullable by default. This ensures that when a context structure is used as input, the @@ -46,6 +46,14 @@ SPDX-License-Identifier: LGPL-2.1-or-later Fields that cannot logically be omitted in input (e.g. a unit type) may remain non-nullable. +- Input may accept multiple representations of the same information. Output + should be normalized and must not include the same information in multiple + forms. Every output field in a reusable context must be accepted on input, + so that the context can be fed back without conversion or removal of fields. + For example, the context returned by `io.systemd.Unit.List` must be usable + as input to `io.systemd.Unit.StartTransient`. The same principle applies to + other interfaces that share structures between output and input. + # Enums - Enum fields in the codebase must be exposed as string values in Varlink, not