Skip to content

Conversation

@jwaldrip
Copy link

Summary

Implements the @semanticNonNull directive as proposed by the GraphQL nullability working group. This directive allows schema authors to indicate that a field is semantically non-null (the resolver never intentionally returns null), but may still be null due to errors.

This decouples nullability from error handling, providing better developer experience for clients who want to understand which fields may be null only due to errors versus fields that may intentionally be null.

Changes

  • Add @semanticNonNull directive to prototype notation with levels argument
  • Create Absinthe.Type.SemanticNullability support module with helper functions
  • Add isSemanticNonNull and semanticNonNullLevels to __Field introspection
  • Add semantic_non_null: true/[levels] shorthand for field definitions

Usage

# Using directive syntax
field :email, :string do
  directive :semantic_non_null
end

# Using shorthand notation
field :email, :string, semantic_non_null: true
field :posts, list_of(:post), semantic_non_null: [0, 1]

Test plan

  • Added comprehensive tests (31 new tests)
  • All 1473 tests pass
  • Directive definition and configuration tested
  • Introspection queries return correct values
  • Shorthand notation works correctly

🤖 Generated with Claude Code

Copy link
Member

@cschiewek cschiewek left a comment

Choose a reason for hiding this comment

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

Personally, I'd prefer not to add this until it hits the actual working draft of the spec, but given it's opt-in, if the majority of @absinthe-graphql/core are fine with it, I won't stop it.

jwaldrip and others added 2 commits January 13, 2026 08:15
Implements the @semanticNonNull directive as proposed by the GraphQL
nullability working group. This directive allows schema authors to indicate
that a field is semantically non-null (the resolver never intentionally
returns null), but may still be null due to errors.

This decouples nullability from error handling, providing better developer
experience for clients who want to understand which fields may be null only
due to errors versus fields that may intentionally be null.

Changes:
- Add @semanticNonNull directive to prototype notation with levels argument
- Create Absinthe.Type.SemanticNullability support module with helper functions
- Add isSemanticNonNull and semanticNonNullLevels to __Field introspection
- Add semantic_non_null: true/[levels] shorthand for field definitions
- Comprehensive tests for all functionality

Usage:
```elixir
# Using directive syntax
field :email, :string do
  directive :semantic_non_null
end

# Using shorthand notation
field :email, :string, semantic_non_null: true
field :posts, list_of(:post), semantic_non_null: [0, 1]
```

Co-Authored-By: Claude Opus 4.5 <[email protected]>
Move @semanticNonNull directive from prototype notation to a new
opt-in module Absinthe.Type.BuiltIns.SemanticNonNull.

Since @semanticNonNull is a proposed-spec feature (not yet finalized),
users must now explicitly opt-in by adding:

    import_types Absinthe.Type.BuiltIns.SemanticNonNull

to their schema definition.

Also adds a new guide: guides/semantic-non-null.md

Co-Authored-By: Claude Opus 4.5 <[email protected]>
@jwaldrip jwaldrip force-pushed the feat/semantic-non-null branch from 0f277b1 to d3e9806 Compare January 13, 2026 15:17
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.

2 participants