Allow @encode(string) on boolean, define case-insensitive true|false string semantics, and add Spector coverage + generic string matcher support (#10875)

`@encode(string)` was restricted to numeric targets, blocking APIs that
model booleans as strings (for example `"true"` / `"false"` in payloads
or query values). This change extends support to boolean targets,
clarifies the docs contract, and adds http-specs Spector coverage.

- **Compiler validation**
- Relaxed `@encode` validation so the implicit string encoding path
(`@encode(string)`) is valid for `boolean` in addition to `numeric`.
- Updated related diagnostic wording to reflect numeric-or-boolean
applicability.

- **Standard library/docs contract**
- Updated `@encode` decorator docs to state boolean string encoding uses
case-insensitive `true` / `false` values.
  - Added a boolean-focused `@encode(string)` example.
- Removed parsing-specific wording from the boolean string semantics
text.

- **Coverage**
- Added a focused compiler decorator test that validates
`@encode(string)` on a boolean model property.
- Updated the non-supported-type expectation to match the new allowed
target set.
- Added/updated Spector coverage in
`packages/http-specs/specs/encode/boolean` with matching mock API and
regenerated `packages/http-specs/spec-summary.md`.
  - Boolean property scenarios now cover multiple casings/values via:
    - `/encode/boolean/property/true-lower`
    - `/encode/boolean/property/false-lower`
    - `/encode/boolean/property/true-upper`
    - `/encode/boolean/property/false-mixed`
- Updated boolean mock API request validation to use a standard matcher
so request boolean-string values are accepted case-insensitively
(`true`/`false`), while still returning varied response casings for
coverage.

- **Spector standard matcher support**
- Added a built-in generic string matcher in `@typespec/spec-api`:
`match.string.caseInsensitive(string)`.
- Replaced the encode/boolean scenario’s local custom matcher with this
shared matcher (`match.string.caseInsensitive(String(requestValue))`).
- Added matcher unit tests under
`packages/spec-api/test/matchers/string.test.ts`.

```tsp
model FeatureFlags {
  @encode(string)
  enabled: boolean;
}
```

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: timotheeguerin <1031227+timotheeguerin@users.noreply.github.com>
Co-authored-by: Timothee Guerin <tiguerin@microsoft.com>

Author: Copilot

.chronus/changes/copilot-encode-string-boolean-changelog-2026-6-5-17-25-0.md

@@ -0,0 +1,16 @@
+---
+changeKind: feature
+packages:
+  - "@typespec/compiler"
+  - "@typespec/spec-api"
+  - "@typespec/http-specs"
+---
+
+Allow `@encode(string)` on boolean targets, define case-insensitive `true`/`false` string semantics, and add shared case-insensitive string matcher support with encode/boolean Spector coverage.
+
+```tsp
+model FeatureFlags {
+  @encode(string)
+  enabled: boolean;
+}
+```

packages/compiler/generated-defs/TypeSpec.ts

@@ -77,7 +77,7 @@ export type MediaTypeHintDecorator = (
 /**
  * Specify how to encode the target type.
  *
- * @param encodingOrEncodeAs Known name of an encoding or a scalar type to encode as(Only for numeric types to encode as string).
+ * @param encodingOrEncodeAs Known name of an encoding or a scalar type to encode as(Only for numeric and boolean types to encode as string).
  * @param encodedAs What target type is this being encoded as. Default to string.
  * @example offsetDateTime encoded with rfc7231
  *
@@ -98,6 +98,15 @@ export type MediaTypeHintDecorator = (
  *   @encode(string) id: int64;
  * }
  * ```
+ * @example encode boolean type to string
+ *
+ * `@encode(string)` on boolean uses case-insensitive `true` / `false` values.
+ *
+ * ```tsp
+ * model FeatureFlags {
+ *   @encode(string) enabled: boolean;
+ * }
+ * ```
  */
 export type EncodeDecorator = (
   context: DecoratorContext,

packages/compiler/lib/std/decorators.tsp

@@ -566,7 +566,7 @@ enum ArrayEncoding {
 
 /**
  * Specify how to encode the target type.
- * @param encodingOrEncodeAs Known name of an encoding or a scalar type to encode as(Only for numeric types to encode as string).
+ * @param encodingOrEncodeAs Known name of an encoding or a scalar type to encode as(Only for numeric and boolean types to encode as string).
  * @param encodedAs What target type is this being encoded as. Default to string.
  *
  * @example offsetDateTime encoded with rfc7231
@@ -590,6 +590,16 @@ enum ArrayEncoding {
  *   @encode(string) id: int64;
  * }
  * ```
+ *
+ * @example encode boolean type to string
+ *
+ * `@encode(string)` on boolean uses case-insensitive `true` / `false` values.
+ *
+ * ```tsp
+ * model FeatureFlags {
+ *   @encode(string) enabled: boolean;
+ * }
+ * ```
  */
 extern dec encode(
   target: Scalar | ModelProperty,

packages/compiler/src/core/messages.ts

@@ -951,7 +951,7 @@ const diagnostics = {
       wrongType: paramMessage`Encoding '${"encoding"}' cannot be used on type '${"type"}'. Expected: ${"expected"}.`,
       wrongEncodingType: paramMessage`Encoding '${"encoding"}' on type '${"type"}' is expected to be serialized as '${"expected"}' but got '${"actual"}'.`,
       wrongNumericEncodingType: paramMessage`Encoding '${"encoding"}' on type '${"type"}' is expected to be serialized as '${"expected"}' but got '${"actual"}'. Set '@encode' 2nd parameter to be of type ${"expected"}. e.g. '@encode("${"encoding"}", int32)'`,
-      firstArg: `First argument of "@encode" must be the encoding name or the string type when encoding numeric types.`,
+      firstArg: `First argument of "@encode" must be the encoding name or the string type when encoding numeric or boolean types.`,
     },
   },
 

packages/compiler/src/lib/decorators.ts

@@ -873,7 +873,9 @@ export type BytesKnownEncoding = "base64" | "base64url";
 export interface EncodeData {
   /**
    * Known encoding key.
-   * Can be undefined when `@encode(string)` is used on a numeric type. In that case it just means using the base10 decimal representation of the number.
+   * Can be undefined when `@encode(string)` is used on a numeric or boolean type.
+   * For numeric this means using the base10 decimal representation of the number.
+   * For boolean this means using `true` or `false`.
    */
   encoding?: DateTimeKnownEncoding | DurationKnownEncoding | BytesKnownEncoding | string;
   type: Scalar;
@@ -995,7 +997,7 @@ function validateEncodeData(context: DecoratorContext, target: Type, encodeData:
     case "base64url":
       return check(["bytes"], ["string"]);
     case undefined:
-      return check(["numeric"], ["string"]);
+      return check(["numeric", "boolean"], ["string"]);
   }
 }
 

packages/compiler/test/decorators/decorators.test.ts

@@ -665,6 +665,20 @@ describe("compiler: built-in decorators", () => {
           strictEqual(encodeData.encoding, undefined);
           strictEqual(encodeData.type.name, "string");
         });
+
+        it(`@encode(string) on boolean model property`, async () => {
+          const { prop, program } = await Tester.compile(t.code`
+            model Foo {
+              @encode(string)
+              ${t.modelProperty("prop")}: boolean;
+            }
+          `);
+
+          const encodeData = getEncode(program, prop);
+          ok(encodeData);
+          strictEqual(encodeData.encoding, undefined);
+          strictEqual(encodeData.type.name, "string");
+        });
       });
       describe("invalid", () => {
         invalidCases.forEach(([target, encoding, encodeAs, expectedCode, expectedMessage]) => {
@@ -693,7 +707,7 @@ describe("compiler: built-in decorators", () => {
           expectDiagnostics(diagnostics, {
             code: "invalid-encode",
             severity: "error",
-            message: "Encoding 'string' cannot be used on type 's'. Expected: numeric.",
+            message: "Encoding 'string' cannot be used on type 's'. Expected: numeric, boolean.",
           });
         });
       });

packages/http-specs/spec-summary.md

@@ -369,6 +369,90 @@ Expected response body:
 }
 ```
 
+### Encode_Boolean_Property_falseLower
+
+- Endpoint: `post /encode/boolean/property/false-lower`
+
+Test operation with request and response model containing a property of boolean type with string encode.
+Expected request body:
+
+```json
+{
+  "value": "false"
+}
+```
+
+Expected response body:
+
+```json
+{
+  "value": "false"
+}
+```
+
+### Encode_Boolean_Property_falseMixed
+
+- Endpoint: `post /encode/boolean/property/false-mixed`
+
+Test operation with request and response model containing a property of boolean type with string encode.
+Expected request body:
+
+```json
+{
+  "value": "FaLsE"
+}
+```
+
+Expected response body:
+
+```json
+{
+  "value": "FaLsE"
+}
+```
+
+### Encode_Boolean_Property_trueLower
+
+- Endpoint: `post /encode/boolean/property/true-lower`
+
+Test operation with request and response model containing a property of boolean type with string encode.
+Expected request body:
+
+```json
+{
+  "value": "true"
+}
+```
+
+Expected response body:
+
+```json
+{
+  "value": "true"
+}
+```
+
+### Encode_Boolean_Property_trueUpper
+
+- Endpoint: `post /encode/boolean/property/true-upper`
+
+Test operation with request and response model containing a property of boolean type with string encode.
+Expected request body:
+
+```json
+{
+  "value": "TRUE"
+}
+```
+
+Expected response body:
+
+```json
+{
+  "value": "TRUE"
+}
+```
+
 ### Encode_Bytes_Header_base64
 
 - Endpoint: `get /encode/bytes/header/base64`

packages/http-specs/specs/encode/boolean/main.tsp

@@ -0,0 +1,63 @@
+import "@typespec/http";
+import "@typespec/spector";
+
+using Http;
+using Spector;
+
+/** Test for encode decorator on boolean. */
+@scenarioService("/encode/boolean")
+namespace Encode.Boolean;
+
+@route("/property")
+namespace Property {
+  model BoolAsStringProperty {
+    @encode(string)
+    value: boolean;
+  }
+
+  alias SendBoolTrueLower = SendBoolAsString<"true">;
+
+  @route("/true-lower")
+  op trueLower is SendBoolTrueLower.sendBoolAsString;
+
+  alias SendBoolFalseLower = SendBoolAsString<"false">;
+
+  @route("/false-lower")
+  op falseLower is SendBoolFalseLower.sendBoolAsString;
+
+  alias SendBoolTrueUpper = SendBoolAsString<"TRUE">;
+
+  @route("/true-upper")
+  op trueUpper is SendBoolTrueUpper.sendBoolAsString;
+
+  alias SendBoolFalseMixed = SendBoolAsString<"FaLsE">;
+
+  @route("/false-mixed")
+  op falseMixed is SendBoolFalseMixed.sendBoolAsString;
+
+  interface SendBoolAsString<StringValue extends string> {
+    @scenario
+    @scenarioDoc(
+      """
+        Test operation with request and response model containing a property of boolean type with string encode.
+        Expected request body:
+        ```json
+        {
+          "value": "{value}"
+        }
+        ```
+        Expected response body:
+        ```json
+        {
+          "value": "{value}"
+        }
+        ```
+        """,
+      {
+        value: StringValue,
+      }
+    )
+    @post
+    sendBoolAsString(@body value: BoolAsStringProperty): BoolAsStringProperty;
+  }
+}

packages/http-specs/specs/encode/boolean/mockapi.ts

@@ -0,0 +1,43 @@
+import { json, match, passOnSuccess, ScenarioMockApi } from "@typespec/spec-api";
+
+export const Scenarios: Record<string, ScenarioMockApi> = {};
+
+function createBodyServerTests(uri: string, responseValue: string, requestValue: boolean) {
+  return passOnSuccess({
+    uri,
+    method: "post",
+    request: {
+      body: json({
+        value: match.string.caseInsensitive(String(requestValue)),
+      }),
+    },
+    response: {
+      status: 200,
+      body: json({
+        value: responseValue,
+      }),
+    },
+    kind: "MockApiDefinition",
+  });
+}
+
+Scenarios.Encode_Boolean_Property_trueLower = createBodyServerTests(
+  "/encode/boolean/property/true-lower",
+  "true",
+  true,
+);
+Scenarios.Encode_Boolean_Property_falseLower = createBodyServerTests(
+  "/encode/boolean/property/false-lower",
+  "false",
+  false,
+);
+Scenarios.Encode_Boolean_Property_trueUpper = createBodyServerTests(
+  "/encode/boolean/property/true-upper",
+  "TRUE",
+  true,
+);
+Scenarios.Encode_Boolean_Property_falseMixed = createBodyServerTests(
+  "/encode/boolean/property/false-mixed",
+  "FaLsE",
+  false,
+);

packages/spec-api/src/matchers/index.ts

@@ -1,5 +1,6 @@
 import { dateTimeMatcher } from "./datetime.js";
 import { baseUrlMatcher } from "./local-url.js";
+import { stringMatcher } from "./string.js";
 
 export {
   createMatcher,
@@ -18,6 +19,9 @@ export { dateTimeMatcher } from "./datetime.js";
  * Namespace for built-in matchers.
  */
 export const match = {
+  /** Matchers for comparing string values. */
+  string: stringMatcher,
+
   /**
    * Matchers for comparing datetime values semantically.
    * Validates that the actual value is in the correct format and represents