Skip to content

Conversation

@devin-ai-integration
Copy link
Contributor

Document explicit null overrides pattern for deleting parameters

Summary

This PR adds documentation to the OpenAPI extensions guide explaining how to use explicit null values in overrides files to delete parameters from the base OpenAPI specification. This pattern was successfully used to resolve TypeScript compilation errors in the Vercel SDK (fern-demo/vercel-fern-config#13) where query parameters and request body properties had duplicate identifiers.

The new documentation section includes:

  • Explanation of when to use null overrides (duplicate identifiers, deprecated parameters, etc.)
  • Warning about breaking changes when deleting parameters
  • Example for deleting single and multiple parameters
  • Real-world example showing how to resolve duplicate identifier conflicts

Review & Testing Checklist for Human

🟡 MEDIUM PRIORITY:

  • Verify syntax accuracy: Confirm that parameters: [null] is the correct and complete syntax for deleting parameters in Fern overrides. Check if there are any variations or additional options.
  • Test the examples: Create a test OpenAPI spec with the example scenarios and verify the null override pattern works exactly as documented
  • Check parameter ordering behavior: Verify that the documentation correctly states "first parameter" - confirm whether parameters are ordered by their definition in the spec or if there's more nuance to how Fern processes parameter lists
  • Review edge cases: Consider if the documentation should cover:
    • What happens when trying to delete more parameters than exist?
    • Behavior with required vs optional parameters
    • Interaction with path-level vs operation-level parameter definitions
  • Verify warning sufficiency: Ensure the breaking change warning is prominent and clear enough for users to understand the implications

Recommended Test Plan

  1. Create a test OpenAPI spec with duplicate parameter/body property names (e.g., the slug example)
  2. Create an overrides file with parameters: [null] for that endpoint
  3. Generate an SDK and verify:
    • The parameter is actually removed from the SDK
    • The SDK compiles without duplicate identifier errors
    • The request body property is still present
  4. Test the multiple parameter deletion example to verify [null, null] syntax works
  5. Check the generated documentation to ensure examples render correctly

Notes

  • This pattern was successfully used in production to fix the Vercel SDK compilation errors (see fern-demo/vercel-fern-config#13)
  • The documentation is based on real-world usage, but some examples are generalized from the specific Vercel SDK case
  • Consider adding this documentation to a changelog or release notes when merging

Link to Devin session: https://app.devin.ai/sessions/fde0679e607f4b1497db15af0bbeb538
Requested by: Deep Singhvi (@deep Singhvi)

Add comprehensive documentation to parameter-names.mdx explaining how to use
explicit null values in overrides files to delete parameters from the base
OpenAPI specification.

Documentation includes:
- Clear explanation of when to use null overrides (duplicate identifiers,
  deprecated parameters, simplifying SDK interface)
- Warning about breaking changes when deleting parameters
- Example for deleting a single parameter using 'parameters: [null]'
- Example for deleting multiple parameters
- Real-world example from Vercel SDK showing how to resolve duplicate
  identifier errors between query parameters and request body properties

This pattern was successfully used to fix TypeScript compilation errors in
the Vercel SDK where slug query parameters conflicted with slug request
body properties.

Related PR: fern-demo/vercel-fern-config#13

Co-Authored-By: [email protected] <[email protected]>
@devin-ai-integration
Copy link
Contributor Author

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

  • Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
  • Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

  • Disable automatic comment and CI monitoring

- Simplifying the SDK interface by hiding internal parameters

<Warning>
Deleting parameters is a breaking change. Parameters removed via null overrides will not be available in the generated SDK, even though they exist in the base OpenAPI specification.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [vale] reported by reviewdog 🐶
[Microsoft.Contractions] Use 'won't' instead of 'will not'.

@github-actions
Copy link
Contributor

github-actions bot commented Nov 5, 2025

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.

1 participant