Skip to content

Implement a backend value mapper

Topics: architecture, backends, generation

Use a mapper when Horde and a backend name the same value differently. Define the mapping at the conversion boundary, keep the backend-native representation out of API models, and make unknown values explicit.

  1. Identify the typed Horde field and the backend field in horde_sdk.backend_parsing or a dispatch converter.
  2. Define a one-direction dictionary whose keys are accepted Horde values and whose values are backend-native values.
  3. Convert in the backend adapter immediately before building its payload. Preserve None when omission has meaning; raise a targeted error when the backend cannot accept a supplied value.
  4. Add parameterized tests for every known mapping, None, and one unknown value. Verify the emitted backend payload, rather than the dictionary alone.

Reverse conversion requires a separate mapping because backend aliases are rarely one-to-one. Removing a mapper means moving its accepted values and failure policy to the replacement boundary in the same change. The backend normalization explanation describes why conversion stays at the edge.