Currently, output-only (server-managed) and user-controlled fields are mixed together at the top level (e.g., within Actor resources).
This creates friction during update operations:
- Updating user-controlled fields requires extra care to preserve existing server-managed fields.
- It complicates lifecycle management in scenarios where a server-owned field needs to outlive or be decoupled from user-controlled state.
Proposal
Separate user-controlled state from server-managed state by encapsulating all output-only fields into a dedicated top-level status field.
This aligns with standard Kubernetes-style resource conventions (e.g., spec vs. status), providing:
- Clear ownership boundaries between client intent and server state.
- Cleaner write/update semantics without accidental overwrites of output-only metadata.
- A familiar mental model for users already accustomed to declarative APIs.
Looking at the resources we have today, almost all output only fields are top level, so the change is mechanical, there are a few exemptions:
ResourceMetadata: Mixes user controlled (atespace and name) and output only (UID, version, timestamps): I think we can probably keep this as is and special case. ResourceMetadata is already special during updates as UID and version are used for optimistic locking, atespace and ate to identify the resource to update, etc.
Actor.source_snapshot: has tag which is user controlled and two output-only fields. We could just split them, making tag a top level field and moving the other two under Actor.status.source_snapshot.
Currently, output-only (server-managed) and user-controlled fields are mixed together at the top level (e.g., within
Actorresources).This creates friction during update operations:
Proposal
Separate user-controlled state from server-managed state by encapsulating all output-only fields into a dedicated top-level
statusfield.This aligns with standard Kubernetes-style resource conventions (e.g.,
specvs.status), providing:Looking at the resources we have today, almost all output only fields are top level, so the change is mechanical, there are a few exemptions:
ResourceMetadata: Mixes user controlled (atespace and name) and output only (UID, version, timestamps): I think we can probably keep this as is and special case. ResourceMetadata is already special during updates as UID and version are used for optimistic locking, atespace and ate to identify the resource to update, etc.Actor.source_snapshot: hastagwhich is user controlled and two output-only fields. We could just split them, makingtaga top level field and moving the other two underActor.status.source_snapshot.