Skip to content

docs(capture): omit null object properties during serialization - #60

Merged
marandaneto merged 6 commits into
mainfrom
specify-capture-null-properties
Sep 8, 2026
Merged

docs(capture): omit null object properties during serialization#60
marandaneto merged 6 commits into
mainfrom
specify-capture-null-properties

Conversation

@marandaneto

@marandaneto marandaneto commented Sep 8, 2026

Copy link
Copy Markdown
Member

Summary

Require capture, capture_ai, and capture_exception to omit null/undefined-valued custom object properties during event serialization for the wire or disk-backed event queues/caches. Preserve existing public APIs that already accept those values.

  • Do not narrow public signatures or property types, reject previously supported null/undefined inputs, or require callers to pre-filter properties. In-memory events may retain them until serialization.
  • {"test": null} serializes as {}. Do not reject the event.
  • ["1", null, 2] stays unchanged. JavaScript undefined array entries follow normal JSON serialization as null without shifting positions.
  • Clean nested objects recursively, including objects inside arrays. Retain objects that become empty and do not compact arrays.
  • Preserve other values, including false, 0, empty strings, and the literal strings "null" and "undefined".
  • Apply the rule to queued and immediate capture, including values introduced by before_send, and to serialized events written to disk or restored for delivery.
  • Do not require new disk persistence or widening currently non-nullable APIs. Keep unrelated caches, privacy controls, reserved-field validation, and OTLP logs/traces rules unchanged.

The owner selected object-member omission to align SDK output with planned backend removal. That backend work is still in progress, so this does not claim the backend already removes every null-valued property.

The canonical specs are synced. One consolidated archive contains the full final contract for all three capture methods: openspec/changes/archive/2026-09-08-preserve-nullable-capture-api/.

This PR changes specifications only. SDK implementation, compatibility review, and rollout remain separate. Adopting the contract changes serialized output for SDKs that retain null-valued object members, not the acceptance of previously supported public inputs.

Context: PostHog/posthog-python#926

Validation

  • The consolidated archive passed strict OpenSpec change validation.
  • All 62 canonical specs passed strict validation after sync.
  • Ten current null-policy acceptance scenarios matched the specs. Gherkin parsing and JSON input/output checks passed, including disk/restore examples, array positions, and objects emptied by cleanup.
  • The single archive fully describes all three canonical additions against origin/main. Consolidation leaves canonical specs and acceptance scenarios unchanged.
  • git diff --check passed.
  • Autoreview against origin/main passed with no actionable findings on 6259b1b.

These checks validate the specification files, not SDK/backend conformance. API compatibility was checked statically; SDK compilation and runtime tests were not run.

@marandaneto
marandaneto marked this pull request as ready for review September 8, 2026 06:28
@marandaneto
marandaneto requested a review from a team as a code owner September 8, 2026 06:28
Comment thread acceptance/public/capture-ai.feature Outdated
@marandaneto
marandaneto requested review from a team September 8, 2026 08:36
@marandaneto

Copy link
Copy Markdown
Member Author

@eli-r-ph is there anything else against allowing null values for all SDKs? some dont, not sure why

@marandaneto
marandaneto requested a review from a team September 8, 2026 12:26
@marandaneto marandaneto changed the title docs(capture): specify preservation of explicit null properties docs(capture): drop null object properties but preserve array elements Sep 8, 2026
@marandaneto marandaneto changed the title docs(capture): drop null object properties but preserve array elements docs(capture): omit null object properties during serialization Sep 8, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants