Conflicting information in "Envelopes"

[nwhite-riot]

Which section?

SDKs

Page URL

https://develop.sentry.dev/sdk/data-model/envelopes/

Description

Under "Terminology", "recommended" is defined as:

This field should be emitted when writing, but can be missing during a read

This is confusing because the wording of the description implies that "recommended" is required for writes, but optional for reads. The optionality is further enforced by Full Examples under "Envelope without headers, implicit length, last newline omitted, terminated by EOF" where it omits the envelope headers altogether, even though the fields are all marked as "recommended".

Suggested Solution

1. Specify which sections of the envelope grammar are required and for what operation (read/write)
2. Specify which fields within a section are required and for what operation (read/write)
3. Provide examples for read and write and clearly outline the operation