[
https://issues.apache.org/jira/browse/THRIFT-3756?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15213652#comment-15213652
]
ASF GitHub Bot commented on THRIFT-3756:
----------------------------------------
Github user jsirois commented on a diff in the pull request:
https://github.com/apache/thrift/pull/961#discussion_r57536162
--- 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.
+- Read: Like optional, the field may, or may not be part of the input
stream.
+- Default values: may not be written
--- End diff --
This 'may' is confusing. Id this 'may' in the
[RFC-2119](https://www.ietf.org/rfc/rfc2119.txt) sense, or is this 'will never
be written' or, in RFC-2119-speak 'must not be written'.
> Improve requiredness documentation
> ----------------------------------
>
> Key: THRIFT-3756
> URL: https://issues.apache.org/jira/browse/THRIFT-3756
> Project: Thrift
> Issue Type: Improvement
> Components: Documentation, Website
> Reporter: Jens Geyer
> Assignee: Jens Geyer
> Priority: Minor
>
> The documentation on the Apache Thrift web site regarding requiredness is
> very minorish (that's an euphemism) and needs to be improved.
--
This message was sent by Atlassian JIRA
(v6.3.4#6332)
