---
id: ADR-CRM-ENT-003
title: Whole-record Saves Carry the Complete Payload
product_area: crm
module: entities
revision: 1
status: proposed
design_intent: confirmed
source_sha:
  services-crm: 7ea48a414c42eade10d60753b8bcc323b1dd726f
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
decision: >-
  Replacement must include every replaceable property, with null clearing a
  value and missing properties refused individually; reads must represent empty
  properties as null; affiliations and custom fields retain their separately
  defined collection behavior.
constrains:
  - DOM-CRM-ENT-001
  - DOM-CRM-ENT-002
  - DOM-CRM-ENT-033
  - SVC-CRM-ENT-entities
  - SVC-CRM-ENT-configuration-types
  - WF-CRM-ENT-002
origin: 'OQ-CRM-ENT-001 decided 2026-10-22 by Andrew: A; E-09 (Andrew, 2026-10-19)'
alternatives:
  - option: Keep destructive omission as the replacement contract.
    why_not: >-
      That permits accidentally dropping a field from a payload to erase stored
      information, which the adopted complete-payload rule prevents.
  - option: Preserve omitted properties during replacement.
    why_not: >-
      That duplicates patch semantics instead of expressing a complete
      replacement. The recorded product answer selected explicit completeness.
consequences:
  - >-
    The approved requirement remains unimplemented for these records; omitted
    editable values can still be cleared.
  - >-
    Contact editors use patches, while configuration editors retain last-read
    fields in versioned replacements.
  - >-
    Reads need explicit empty values before enforcing complete replacement
    payloads.
evidence:
  - >-
    services-crm at 7ea48a41: docs/entities-api.md (The update contract, Not yet
    under the complete-payload rule)
  - 'rhythm-v2-docs: specs/crm/entities/FINDINGS.md (OQ-CRM-ENT-001)'
---
# Whole-record Saves Carry the Complete Payload

## Context

The recorded product answer requires complete replacement, with separate affiliation and custom-field semantics. This is an adopted target contract rather than a claim about current implementation.

## Decision

Replacement must include every replaceable property, with null clearing a value and missing properties refused individually; reads must represent empty properties as null; affiliations and custom fields retain their separately defined collection behavior.

## Alternatives Considered

Keep destructive omission as the replacement contract. That permits accidentally dropping a field from a payload to erase stored information, which the adopted complete-payload rule prevents.

Preserve omitted properties during replacement. That duplicates patch semantics instead of expressing a complete replacement. The recorded product answer selected explicit completeness.

## Consequences

Existing replacements still clear omitted editable values. Contact editing reduces exposure by patching changed fields, while catalogue editors construct replacements from the record as read. Implementing the decision requires coordinated response and client changes.

The approved requirement remains unimplemented for these records; omitted editable values can still be cleared. Contact editors use patches, while configuration editors retain last-read fields in versioned replacements. Reads need explicit empty values before enforcing complete replacement payloads.