docs: clarify Varlink input and output policy

(cherry picked from commit 1c754bf06e1369c39abcff411a317a058e9b0b91)
This commit is contained in:
Ivan Kruglov
2026-10-16 17:24:51 +01:00
committed by Luca Boccassi
parent fa22119295
commit 3e39c54632
+12 -4
View File
@@ -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