swiftlang · owenv · Nov 10, 2025 · Nov 10, 2025
@@ -28,3 +28,9 @@ See the [dedicated section][section] on the Swift project website.
 After you opened your PR, a maintainer will review it and test your changes in CI (*Continuous Integration*) by adding a `@swift-ci Please test` comment on the pull request. Once your PR is approved and CI has passed, the maintainer will merge your pull request.
 
 Only contributors with [commit access](https://www.swift.org/contributing/#commit-access) are able to approve pull requests and trigger CI.
+
+## API Design
+
+### Public `enum`s
+
+Enums should generally be marked as `@frozen` or `@nonexhaustive` to allow consistent behavior when switching over them in library-evolution and non-library-evolution builds. The default should be `@frozen` unless we expect to extend the enum without adopting a new LSP or BSP version, eg. because the type is part of an LSP extension. We do not need to anticipate the LSP/BSP specification changing since we plan to release a new major version of swift-tools-protocols when it gets updated to a new LSP or BSP specification version. Custom `CodingKey` enums should always be marked as `@nonexhaustive` because we want to be able to add new members to structs.
@@ -94,7 +94,7 @@ public struct SourceItem: Codable, Hashable, Sendable {
   }
 }
 
-public enum SourceItemKind: Int, Codable, Hashable, Sendable {
+@frozen public enum SourceItemKind: Int, Codable, Hashable, Sendable {
   /// The source item references a normal file.
   case file = 1
 
@@ -120,7 +120,7 @@ public struct SourceItemDataKind: RawRepresentable, Codable, Hashable, Sendable
 
 /// **(BSP Extension)**
 
-public enum SourceKitSourceItemKind: String, Codable {
+/*@nonexhaustive*/ public enum SourceKitSourceItemKind: String, Codable {
   /// A source file that belongs to the target
   case source = "source"
 

@@ -50,7 +50,7 @@ public struct OnBuildLogMessageNotification: BSPNotification {
   }
 }
 
-public enum StructuredLogKind: Codable, Hashable, Sendable {
+@frozen public enum StructuredLogKind: Codable, Hashable, Sendable {
   case begin(StructuredLogBegin)
   case report(StructuredLogReport)
   case end(StructuredLogEnd)

@@ -53,7 +53,7 @@ public struct BuildTargetEvent: Codable, Hashable, Sendable {
   }
 }
 
-public enum BuildTargetEventKind: Int, Codable, Hashable, Sendable {
+@frozen public enum BuildTargetEventKind: Int, Codable, Hashable, Sendable {
   /// The build target is new.
   case created = 1
 

@@ -36,7 +36,7 @@ public struct RegisterForChanges: BSPRequest {
   }
 }
 
-public enum RegisterAction: String, Hashable, Codable, Sendable {
+@frozen public enum RegisterAction: String, Hashable, Codable, Sendable {
   case register = "register"
   case unregister = "unregister"
 }

@@ -165,7 +165,7 @@ public struct TestFinishData: Codable, Hashable, Sendable {
 
 }
 
-public enum TestStatus: Int, Codable, Hashable, Sendable {
+@frozen public enum TestStatus: Int, Codable, Hashable, Sendable {
   /// The test passed successfully.
   case passed = 1
 

@@ -12,7 +12,7 @@
 
 import LanguageServerProtocol
 
-public enum MessageType: Int, Sendable, Codable {
+@frozen public enum MessageType: Int, Sendable, Codable {
   /// An error message.
   case error = 1
 

@@ -10,7 +10,7 @@
 //
 //===----------------------------------------------------------------------===//
 
-public enum StatusCode: Int, Codable, Hashable, Sendable {
+@frozen public enum StatusCode: Int, Codable, Hashable, Sendable {
   /// Execution was successful.
   case ok = 1
 

@@ -44,7 +44,7 @@ public struct LogMessageNotification: LSPNotification, Hashable {
   }
 }
 
-public enum StructuredLogKind: Codable, Hashable, Sendable {
+@frozen public enum StructuredLogKind: Codable, Hashable, Sendable {
   case begin(StructuredLogBegin)
   case report(StructuredLogReport)
   case end(StructuredLogEnd)

@@ -25,7 +25,7 @@ public struct WorkDoneProgress: LSPNotification, Hashable {
   }
 }
 
-public enum WorkDoneProgressKind: Codable, Hashable, Sendable {
+@frozen public enum WorkDoneProgressKind: Codable, Hashable, Sendable {
   case begin(WorkDoneProgressBegin)
   case report(WorkDoneProgressReport)
   case end(WorkDoneProgressEnd)

@@ -10,7 +10,7 @@
 //
 //===----------------------------------------------------------------------===//
 
-public enum RequestID: Hashable, Sendable {
+@frozen public enum RequestID: Hashable, Sendable {
   case string(String)
   case number(Int)
 }

@@ -50,7 +50,7 @@ public struct CodeActionRequest: TextDocumentRequest, Hashable {
 /// Wrapper type for the response of a CodeAction request.
 /// If the client supports CodeAction literals, the encoded type will be the CodeAction array itself.
 /// Otherwise, the encoded value will be an array of CodeActions' inner Command structs.
-public enum CodeActionRequestResponse: ResponseType, Codable, Equatable {
+@frozen public enum CodeActionRequestResponse: ResponseType, Codable, Equatable {
   case codeActions([CodeAction])
   case commands([Command])
 

@@ -93,7 +93,7 @@ public struct CompletionList: ResponseType, Hashable {
     }
   }
 
-  public enum ItemDefaultsEditRange: Codable, Hashable, Sendable {
+  @frozen public enum ItemDefaultsEditRange: Codable, Hashable, Sendable {
     case range(Range<Position>)
     case insertReplaceRanges(InsertReplaceRanges)
 

@@ -35,7 +35,7 @@ public struct DocumentDiagnosticsRequest: TextDocumentRequest {
 /// requested document or a unchanged report indicating that nothing
 /// has changed in terms of diagnostics in comparison to the last
 /// pull request.
-public enum DocumentDiagnosticReport: ResponseType, Codable, Hashable {
+@frozen public enum DocumentDiagnosticReport: ResponseType, Codable, Hashable {
   case full(RelatedFullDocumentDiagnosticReport)
   case unchanged(RelatedUnchangedDocumentDiagnosticReport)
 

@@ -41,7 +41,7 @@ public struct DocumentHighlightRequest: TextDocumentRequest, Hashable {
 }
 
 /// The kind of document highlight - read, write, or text (fuzzy).
-public enum DocumentHighlightKind: Int, Codable, Hashable, Sendable {
+@frozen public enum DocumentHighlightKind: Int, Codable, Hashable, Sendable {
 
   /// Textual match.
   case text = 1

@@ -28,7 +28,7 @@ public struct DocumentSemanticTokensDeltaRequest: TextDocumentRequest, Hashable
   }
 }
 
-public enum DocumentSemanticTokensDeltaResponse: ResponseType, Codable, Equatable {
+@frozen public enum DocumentSemanticTokensDeltaResponse: ResponseType, Codable, Equatable {
   case tokens(DocumentSemanticTokensResponse)
   case delta(SemanticTokensDelta)
 

@@ -34,7 +34,7 @@ public struct DocumentSymbolRequest: TextDocumentRequest, Hashable {
   }
 }
 
-public enum DocumentSymbolResponse: ResponseType, Hashable {
+@frozen public enum DocumentSymbolResponse: ResponseType, Hashable {
   case documentSymbols([DocumentSymbol])
   case symbolInformation([SymbolInformation])
 

@@ -55,12 +55,12 @@ public struct HoverResponse: ResponseType, Hashable {
   }
 }
 
-public enum HoverResponseContents: Hashable, Sendable {
+@frozen public enum HoverResponseContents: Hashable, Sendable {
   case markedStrings([MarkedString])
   case markupContent(MarkupContent)
 }
 
-public enum MarkedString: Hashable {
+@frozen public enum MarkedString: Hashable {
   private struct MarkdownCodeBlock: Codable {
     let language: String
     let value: String

@@ -117,7 +117,7 @@ public struct InlineValueEvaluatableExpression: Codable, Hashable, Sendable {
 /// - as a name to use for a variable lookup (class InlineValueVariableLookup)
 /// - as an evaluatable expression (class InlineValueEvaluatableExpression)
 /// The InlineValue types combines all inline value types into one type.
-public enum InlineValue: ResponseType, Hashable, Sendable {
+@frozen public enum InlineValue: ResponseType, Hashable, Sendable {
   case text(InlineValueText)
   case variableLookup(InlineValueVariableLookup)
   case evaluatableExpression(InlineValueEvaluatableExpression)

@@ -160,7 +160,7 @@ public struct SignatureInformation: Codable, Hashable, Sendable {
 /// Represents a parameter of a callable-signature. A parameter can
 /// have a label and a doc-comment.
 public struct ParameterInformation: Codable, Hashable, Sendable {
-  public enum Label: Codable, Hashable, Sendable {
+  @frozen public enum Label: Codable, Hashable, Sendable {
     case string(String)
     case offsets(start: Int, end: Int)
 

@@ -159,7 +159,7 @@ public struct WorkspaceUnchangedDocumentDiagnosticReport: Codable, Hashable, Sen
 }
 
 /// A workspace diagnostic document report.
-public enum WorkspaceDocumentDiagnosticReport: Codable, Hashable, Sendable {
+@frozen public enum WorkspaceDocumentDiagnosticReport: Codable, Hashable, Sendable {
   case full(WorkspaceFullDocumentDiagnosticReport)
   case unchanged(WorkspaceUnchangedDocumentDiagnosticReport)
 

@@ -34,7 +34,7 @@ public struct WorkspaceSymbolsRequest: LSPRequest, Hashable {
   }
 }
 
-public enum WorkspaceSymbolItem: ResponseType, Hashable {
+@frozen public enum WorkspaceSymbolItem: ResponseType, Hashable {
   case symbolInformation(SymbolInformation)
   case workspaceSymbol(WorkspaceSymbol)
 
@@ -94,7 +94,7 @@ public struct SymbolInformation: Hashable, ResponseType {
 
 /// A special workspace symbol that supports locations without a range
 public struct WorkspaceSymbol: ResponseType, Hashable {
-  public enum WorkspaceSymbolLocation: Codable, Hashable, Sendable {
+  @frozen public enum WorkspaceSymbolLocation: Codable, Hashable, Sendable {
     public struct URI: Codable, Hashable, Sendable {
       public var uri: DocumentURI
 

@@ -977,7 +977,7 @@ public struct GeneralClientCapabilities: Hashable, Codable, Sendable {
 
   /// A type indicating how positions are encoded,
   /// specifically what column offsets mean.
-  public enum PositionEncodingKind: String, Hashable, Codable, Sendable {
+  @frozen public enum PositionEncodingKind: String, Hashable, Codable, Sendable {
 
     /// Character offsets count UTF-8 code units (e.g bytes).
     case utf8 = "utf-8"

@@ -42,7 +42,7 @@ public struct CompletionItemTag: RawRepresentable, Codable, Hashable, Sendable {
   public static let deprecated = CompletionItemTag(rawValue: 1)
 }
 
-public enum CompletionItemEdit: Codable, Hashable, Sendable {
+@frozen public enum CompletionItemEdit: Codable, Hashable, Sendable {
   case textEdit(TextEdit)
   case insertReplaceEdit(InsertReplaceEdit)
 
@@ -205,7 +205,7 @@ public struct CompletionItem: ResponseType, Codable, Hashable, Sendable {
 }
 
 /// The format of the returned insertion text - either literal plain text or a snippet.
-public enum InsertTextFormat: Int, Codable, Hashable, Sendable {
+@frozen public enum InsertTextFormat: Int, Codable, Hashable, Sendable {
 
   /// The text to insert is plain text.
   case plain = 1

@@ -11,15 +11,15 @@
 //===----------------------------------------------------------------------===//
 
 /// The severity level of a Diagnostic, between hint and error.
-public enum DiagnosticSeverity: Int, Codable, Hashable, Sendable {
+@frozen public enum DiagnosticSeverity: Int, Codable, Hashable, Sendable {
   case error = 1
   case warning = 2
   case information = 3
   case hint = 4
 }
 
 /// A unique diagnostic code, which may be used identifier the diagnostic in e.g. documentation.
-public enum DiagnosticCode: Hashable, Sendable {
+@frozen public enum DiagnosticCode: Hashable, Sendable {
   case number(Int)
   case string(String)
 }

@@ -74,7 +74,7 @@ public struct InlayHintKind: RawRepresentable, Codable, Hashable, Sendable {
 }
 
 /// A hint's label, either being a single string or a composition of parts.
-public enum InlayHintLabel: Codable, Hashable, Sendable {
+@frozen public enum InlayHintLabel: Codable, Hashable, Sendable {
   case parts([InlayHintLabelPart])
   case string(String)
 

@@ -12,7 +12,7 @@
 
 /// Representation of 'any' in the Language Server Protocol, which is equivalent
 /// to an arbitrary JSON value.
-public enum LSPAny: Hashable, Sendable {
+@frozen public enum LSPAny: Hashable, Sendable {
   case null
   case int(Int)
   case bool(Bool)

@@ -10,7 +10,7 @@
 //
 //===----------------------------------------------------------------------===//
 
-public enum LocationsOrLocationLinksResponse: ResponseType, Hashable, Sendable {
+@frozen public enum LocationsOrLocationLinksResponse: ResponseType, Hashable, Sendable {
   case locations([Location])
   case locationLinks([LocationLink])
 

@@ -31,7 +31,7 @@ public struct NotebookDocumentFilter: Codable, Hashable, Sendable {
 /// A notebook cell text document filter denotes a cell text
 /// document by different properties.
 public struct NotebookCellTextDocumentFilter: Codable, Hashable, Sendable {
-  public enum NotebookFilter: Codable, Hashable, Sendable {
+  @frozen public enum NotebookFilter: Codable, Hashable, Sendable {
     case string(String)
     case notebookDocumentFilter(NotebookDocumentFilter)
 

@@ -10,7 +10,7 @@
 //
 //===----------------------------------------------------------------------===//
 
-public enum ProgressToken: Codable, Hashable, Sendable {
+@frozen public enum ProgressToken: Codable, Hashable, Sendable {
   case integer(Int)
   case string(String)
 

@@ -200,7 +200,7 @@ public struct ServerCapabilities: Codable, Hashable, Sendable {
   }
 }
 
-public enum ValueOrBool<ValueType: Codable>: Codable, Hashable where ValueType: Hashable {
+@frozen public enum ValueOrBool<ValueType: Codable>: Codable, Hashable where ValueType: Hashable {
   case bool(Bool)
   case value(ValueType)
 
@@ -240,7 +240,7 @@ public enum ValueOrBool<ValueType: Codable>: Codable, Hashable where ValueType:
 
 extension ValueOrBool: Sendable where ValueType: Sendable {}
 
-public enum TextDocumentSync: Codable, Hashable, Sendable {
+@frozen public enum TextDocumentSync: Codable, Hashable, Sendable {
   case options(TextDocumentSyncOptions)
   case kind(TextDocumentSyncKind)
 
@@ -342,7 +342,7 @@ public struct TextDocumentSyncOptions: Codable, Hashable, Sendable {
   }
 }
 
-public enum TextDocumentSyncKind: Int, Codable, Hashable, Sendable {
+@frozen public enum TextDocumentSyncKind: Int, Codable, Hashable, Sendable {
 
   /// Documents should not be synced at all.
   case none = 0
@@ -355,7 +355,7 @@ public enum TextDocumentSyncKind: Int, Codable, Hashable, Sendable {
   case incremental = 2
 }
 
-public enum NotebookFilter: Codable, Hashable, Sendable {
+@frozen public enum NotebookFilter: Codable, Hashable, Sendable {
   case string(String)
   case documentFilter(DocumentFilter)
 
@@ -748,7 +748,7 @@ public struct DocumentOnTypeFormattingOptions: Codable, Hashable, Sendable {
 /// Wrapper type for a server's CodeActions' capabilities.
 /// If the client supports CodeAction literals, the server can return specific information about
 /// how CodeActions will be sent. Otherwise, the server's capabilities are determined by a boolean.
-public enum CodeActionServerCapabilities: Codable, Hashable, Sendable {
+@frozen public enum CodeActionServerCapabilities: Codable, Hashable, Sendable {
 
   case supportsCodeActionRequests(Bool)
   case supportsCodeActionRequestsWithLiterals(CodeActionOptions)
@@ -1157,7 +1157,7 @@ public struct WorkspaceServerCapabilities: Codable, Hashable, Sendable {
     }
   }
 
-  public enum FileOperationPatternKind: String, Codable, Hashable {
+  @frozen public enum FileOperationPatternKind: String, Codable, Hashable {
     /// The pattern matches a file only.
     case file = "file"
     /// The pattern matches a folder only.

@@ -10,7 +10,7 @@
 //
 //===----------------------------------------------------------------------===//
 
-public enum StringOrMarkupContent: Codable, Hashable, Sendable {
+@frozen public enum StringOrMarkupContent: Codable, Hashable, Sendable {
   case string(String)
   case markupContent(MarkupContent)
 

@@ -14,7 +14,7 @@
 ///
 /// For an edit where the document is implied, use `TextEdit`.
 public struct TextDocumentEdit: Hashable, Codable, Sendable {
-  public enum Edit: Codable, Hashable, Sendable {
+  @frozen public enum Edit: Codable, Hashable, Sendable {
     case textEdit(TextEdit)
     case annotatedTextEdit(AnnotatedTextEdit)
 

@@ -10,7 +10,7 @@
 //
 //===----------------------------------------------------------------------===//
 
-public enum TextDocumentSaveReason: Int, Codable, Hashable, Sendable {
+@frozen public enum TextDocumentSaveReason: Int, Codable, Hashable, Sendable {
 
   case manual = 1