Existing annotation patterns to follow

// EmptyBehavior controls how empty message fields serialize to JSON.
// "Empty" means all fields at proto default (proto.Size() == 0).
enum EmptyBehavior {
  // Follow default behavior: serialize empty messages as {} (same as PRESERVE)
  EMPTY_BEHAVIOR_UNSPECIFIED = 0;
  // Serialize empty messages as {} (explicit same as default)
  EMPTY_BEHAVIOR_PRESERVE = 1;
  // Serialize empty messages as null
  EMPTY_BEHAVIOR_NULL = 2;
  // Omit the field entirely when message is empty
  EMPTY_BEHAVIOR_OMIT = 3;
}

  // Mark a primitive field as nullable (explicit null vs absent).
  // Only valid on proto3 optional fields (HasOptionalKeyword=true).
  // When true: unset field serializes as null, set field serializes normally.
  // When false (default): unset field is omitted from JSON.
  optional bool nullable = 50013;
 
  // Controls how empty message fields serialize to JSON.
  // Only valid on singular message fields (not repeated, not map).
  // "Empty" = all fields at proto default (proto.Size() == 0).
  optional EmptyBehavior empty_behavior = 50014;

cd proto && buf build

cd proto && buf generate

go build ./http/...

package annotations
 
import (
    "google.golang.org/protobuf/compiler/protogen"
    "google.golang.org/protobuf/proto"
    "google.golang.org/protobuf/reflect/protoreflect"
    "google.golang.org/protobuf/types/descriptorpb"
 
    "github.com/SebastienMelki/sebuf/http"
)
 
// NullableValidationError represents an error in nullable annotation validation.
type NullableValidationError struct {
    MessageName string
    FieldName   string
    Reason      string
}
 
func (e *NullableValidationError) Error() string {
    return "invalid nullable annotation on " + e.MessageName + "." + e.FieldName + ": " + e.Reason
}
 
// IsNullableField returns true if the field has nullable=true annotation.
func IsNullableField(field *protogen.Field) bool {
    options := field.Desc.Options()
    if options == nil {
        return false
    }
 
    fieldOptions, ok := options.(*descriptorpb.FieldOptions)
    if !ok {
        return false
    }
 
    ext := proto.GetExtension(fieldOptions, http.E_Nullable)
    if ext == nil {
        return false
    }
 
    nullable, ok := ext.(bool)
    return ok && nullable
}
 
// ValidateNullableAnnotation checks if nullable annotation is valid for a field.
// Returns error if nullable=true on a non-optional field or on a message field.
func ValidateNullableAnnotation(field *protogen.Field, messageName string) error {
    if !IsNullableField(field) {
        return nil // No annotation, nothing to validate
    }
 
    // Nullable only valid on proto3 optional fields
    if !field.Desc.HasOptionalKeyword() {
        return &NullableValidationError{
            MessageName: messageName,
            FieldName:   string(field.Desc.Name()),
            Reason:      "nullable annotation is only valid on proto3 optional fields",
        }
    }
 
    // Nullable only valid on primitive types (not messages)
    if field.Desc.Kind() == protoreflect.MessageKind {
        return &NullableValidationError{
            MessageName: messageName,
            FieldName:   string(field.Desc.Name()),
            Reason:      "nullable annotation is only valid on primitive fields, not message fields",
        }
    }
 
    return nil
}

package annotations
 
import (
    "google.golang.org/protobuf/compiler/protogen"
    "google.golang.org/protobuf/proto"
    "google.golang.org/protobuf/reflect/protoreflect"
    "google.golang.org/protobuf/types/descriptorpb"
 
    "github.com/SebastienMelki/sebuf/http"
)
 
// EmptyBehaviorValidationError represents an error in empty_behavior annotation validation.
type EmptyBehaviorValidationError struct {
    MessageName string
    FieldName   string
    Reason      string
}
 
func (e *EmptyBehaviorValidationError) Error() string {
    return "invalid empty_behavior annotation on " + e.MessageName + "." + e.FieldName + ": " + e.Reason
}
 
// GetEmptyBehavior returns the empty behavior for a field.
// Returns EMPTY_BEHAVIOR_UNSPECIFIED if not set (callers should treat as PRESERVE).
func GetEmptyBehavior(field *protogen.Field) http.EmptyBehavior {
    options := field.Desc.Options()
    if options == nil {
        return http.EmptyBehavior_EMPTY_BEHAVIOR_UNSPECIFIED
    }
 
    fieldOptions, ok := options.(*descriptorpb.FieldOptions)
    if !ok {
        return http.EmptyBehavior_EMPTY_BEHAVIOR_UNSPECIFIED
    }
 
    ext := proto.GetExtension(fieldOptions, http.E_EmptyBehavior)
    if ext == nil {
        return http.EmptyBehavior_EMPTY_BEHAVIOR_UNSPECIFIED
    }
 
    behavior, ok := ext.(http.EmptyBehavior)
    if !ok {
        return http.EmptyBehavior_EMPTY_BEHAVIOR_UNSPECIFIED
    }
 
    return behavior
}
 
// HasEmptyBehaviorAnnotation returns true if the field has any empty_behavior annotation set
// (including explicit PRESERVE, NULL, or OMIT - not just UNSPECIFIED).
func HasEmptyBehaviorAnnotation(field *protogen.Field) bool {
    return GetEmptyBehavior(field) != http.EmptyBehavior_EMPTY_BEHAVIOR_UNSPECIFIED
}
 
// ValidateEmptyBehaviorAnnotation checks if empty_behavior annotation is valid for a field.
// Returns error if used on primitive, repeated, or map fields.
func ValidateEmptyBehaviorAnnotation(field *protogen.Field, messageName string) error {
    if !HasEmptyBehaviorAnnotation(field) {
        return nil // No annotation, nothing to validate
    }
 
    // Empty behavior only valid on message fields
    if field.Desc.Kind() != protoreflect.MessageKind {
        return &EmptyBehaviorValidationError{
            MessageName: messageName,
            FieldName:   string(field.Desc.Name()),
            Reason:      "empty_behavior annotation is only valid on message fields",
        }
    }
 
    // Not valid on repeated fields
    if field.Desc.IsList() {
        return &EmptyBehaviorValidationError{
            MessageName: messageName,
            FieldName:   string(field.Desc.Name()),
            Reason:      "empty_behavior annotation is not valid on repeated fields",
        }
    }
 
    // Not valid on map fields
    if field.Desc.IsMap() {
        return &EmptyBehaviorValidationError{
            MessageName: messageName,
            FieldName:   string(field.Desc.Name()),
            Reason:      "empty_behavior annotation is not valid on map fields",
        }
    }
 
    return nil
}

go build ./internal/annotations/...
go test -v ./internal/annotations/...
make lint-fix