Skip to content

refactor(resources): support API field mappings with identity defaults #172

Description

@bwl21

Problem

Resource declarations and state should use stable ct-cli field names. Today managedFields maps ChurchTools API responses into that model, but standard creates and updates send the same field keys directly back to ChurchTools. Equality between a ct-cli field name and its API field name is therefore implicit rather than an adapter decision.

That is convenient while both names match, but it means an upstream API field rename can force changes through config, state, adoption output, and planning instead of being contained in the resource adapter. This becomes more relevant as additional ChurchTools entities such as calendars, bookable resources, or wiki categories are considered.

The goal is not to invent a separate vocabulary. ct-cli may deliberately retain the familiar ChurchTools field names. The goal is to make the API boundary explicit where names or shapes differ.

Proposed direction

Add optional per-resource field mappings with identity semantics as the default:

  • an unmapped field reads and writes under the same name;
  • read and write names or paths can be overridden independently;
  • nested reads such as information.campusId are supported;
  • normalization can remain available for cases such as missing values becoming null;
  • custom fetchOne, writer, and other protocol-level hooks remain available for behavior that is not a field mapping.

Conceptually:

fields: {
  name: {}, // API name is also `name`
  campusId: {
    read: "information.campusId",
    write: "campusId",
    normalize: (value) => value ?? null,
  },
}

The exact API is a design decision; this issue is about establishing the boundary, not prescribing this syntax.

Acceptance criteria

  • Unmapped fields retain the current identity behavior.
  • A managed field can have different API read and write names/paths.
  • Create and update bodies use the write mapping.
  • Actual-state reads, adoption, and drift detection use the read mapping.
  • Existing config and state field names remain unchanged.
  • Existing non-standard resource hooks, especially the department writer, continue to work.
  • Tests simulate an API-side field rename while the ct-cli declaration and state field stay stable.
  • Existing resource behavior remains unchanged.

Non-goals

  • Introducing a new user-facing vocabulary different from ChurchTools terminology.
  • Replacing protocol-level adapters with field mappings.
  • Adding calendar, ChurchResource, or wiki entities as part of this issue.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    triageUnsorted intake — decide in the weekly sweep

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions