Document nullable types and explicit null overrides #1791
Conversation
- Add nullable<T> to built-in types table - Document the difference between optional and nullable - Explain PATCH request semantics with explicit null values - Provide TypeScript and Java SDK usage examples - Document combining optional and nullable for three-state fields This addresses the need to document explicit null overrides for APIs that need to differentiate between omitted fields, explicit null values, and actual values in PATCH requests. Co-Authored-By: Devin Logan <[email protected]>
🤖 Devin AI EngineerI'll be helping with this pull request! Here's what you should know: ✅ I will automatically:
Note: I can only respond to comments from users who have write access to this repository. ⚙️ Control Options:
|
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
| | `file` | File upload type, e.g., [file uploads](/learn/api-definition/fern/endpoints/multipart) | | ||
| | `unknown` | Represents arbitrary JSON | | ||
|
|
||
| ### Optional vs Nullable |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.Headings] 'Optional vs Nullable' should use sentence-style capitalization.
|
|
||
| ### Optional vs Nullable | ||
|
|
||
| Understanding the difference between `optional` and `nullable` is important for properly modeling your API: |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.Adverbs] Remove 'properly' if it's not important to the meaning of the statement.
|
|
||
| Understanding the difference between `optional` and `nullable` is important for properly modeling your API: | ||
|
|
||
| - **`optional<T>`**: The field can be omitted from the request/response entirely. When omitted, the field is not sent over the wire. |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Microsoft.Contractions] Use 'isn't' instead of 'is not'.
| bio: nullable<string> # Must be present, but can be null | ||
| ``` | ||
| This distinction is particularly important for PATCH requests where you need to differentiate between: |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.Acronyms] 'PATCH' has no definition.
| 2. **Setting to `null`** - Clear this field (remove the value) | ||
| 3. **Setting to a value** - Update this field with a new value | ||
|
|
||
| #### Example: PATCH request semantics |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.Headings] 'Example: PATCH request semantics' should use sentence-style capitalization.
| 2. **Setting to `null`** - Clear this field (remove the value) | ||
| 3. **Setting to a value** - Update this field with a new value | ||
|
|
||
| #### Example: PATCH request semantics |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.Acronyms] 'PATCH' has no definition.
- Change heading to sentence-style capitalization - Remove unnecessary adverb 'properly' - Use contraction 'isn't' instead of 'is not' - Add 'HTTP' prefix to PATCH to clarify acronym Co-Authored-By: Devin Logan <[email protected]>
| bio: nullable<string> # Must be present, but can be null | ||
| ``` | ||
| This distinction is particularly important for HTTP PATCH requests where you need to differentiate between: |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.Acronyms] 'PATCH' has no definition.
| 2. **Setting to `null`** - Clear this field (remove the value) | ||
| 3. **Setting to a value** - Update this field with a new value | ||
|
|
||
| #### Example: HTTP PATCH request semantics |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.Acronyms] 'PATCH' has no definition.
Document nullable types and explicit null overrides
Summary
Added comprehensive documentation for the
nullable<T>type in Fern's type system documentation. This PR addresses the need to document explicit null overrides for APIs that distinguish between omitted fields, explicit null values, and actual values (particularly important for PATCH requests).Changes:
nullableto the built-in types tableoptional<T>andnullable<T>optionalandnullablefor three-state fieldsReview & Testing Checklist for Human
Risk Level: Yellow - Unable to access original Slack thread, so requirements may be incomplete or misaligned
OptionalNullableexample with thecollapse-optional-nullableconfigRecommended Test Plan
Notes
OptionalNullablewhich I found in the Java SDK changelog (v3.11.0) but haven't verified firsthand