Github user jsirois commented on a diff in the pull request:
https://github.com/apache/thrift/pull/961#discussion_r57536860
--- Diff: doc/specs/idl.md ---
@@ -126,8 +126,39 @@ A service provides the interface for a set of
functionality provided by a Thrift
### Field Requiredness
- [18] FieldReq ::= 'required' | 'optional'
+There are two explicit requiredness values, and a third one that is
applied implicity if neither *required* nor *optional* are given: *default*
requiredness.
+ [18] FieldReq ::= 'required' | 'optional'
+
+The general rules for requiredness are as follows:
+
+#### required
+
+- Write: Required fields are always written and are expected to be set.
+- Read: Required fields are always read and are expected to be contained
in the input stream.
+- Defaults values: are always written
+
+If a required field is missing during read, the expected behaviour is to
indicate an unsuccessful read operation to the caller, e.g. by throwing an
exception or returning an error.
+
+Because of this behaviour, required fields drastically limit the options
with regard to soft versioning. Because they must be present on read, the
fields cannot be deprecated. If a required field would be removed (or changed
to optional), the data are no longer compatible between versions.
+
+#### optional
+
+- Write: Optional fields are only written when they are set
+- Read: Optional fields may, or may not be part of the input stream.
+- Default values: are written when the isset flag is set
+
+Most language implementations use the recommended pratice of so-called
"isset" flags to indicate whether a particular optional field is set or not.
Only fields with this flag set are written, and conversely the flag is only set
when a field value has been read from the input stream.
+
+#### default requiredness (implicit)
+
+- Write: Like required, the fields are always written.
--- End diff --
This also seems misleading. I added commentary on
https://issues.apache.org/jira/browse/THRIFT-3752, but the java generator, for
example, only emits default requiredness collections when they are non-null;
which seems like the only thing to do in order for the read-side of the wire to
correctly interpret the field as not set (unless there were a special
byte-sequence in the protocol for indicating unset or null). As such, this
language seems misleading to me. Perhaps something like: "Write: Fields that
are set are always written" ?
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastruct...@apache.org or file a JIRA ticket
with INFRA.
---
