fix(@typespec/http): `@head` response with body wrongly flags content type by Copilot · Pull Request #9869 · microsoft/typespec

Copilot · 2026-03-02T19:26:03Z

Release 1.9.1 introduced treatContentTypeAsHeader: verb === "head" which caused content-type properties in HEAD responses to always be classified as HTTP headers. When a HEAD response model had body properties alongside a content-type header, the content-type was moved to headers while the body silently used the wrong default content-type (application/json).

Example — previously produced wrong OpenAPI (content-type as header + wrong application/json body):

@head
op listHead(): OkResponse | Error;

@error
model Error {
  @header
  contentType: "application/problem+json";
  type: string;
}

Changes

New head-no-body warning — emitted when a @head response contains a body (HTTP spec: "head request must not return a message-body in the response"). Warning fires after void/status-code resolution so void return types don't trigger it spuriously.
Content-type classification — treatContentTypeAsHeader: verb === "head" is retained as the single mechanism for HEAD responses. Content-type properties are treated as regular HTTP headers for all HEAD responses, which correctly suppresses the content-type-ignored diagnostic and places them in the response headers.
OpenAPI3 round-trip tests — updated to remove HEAD-with-body scenarios from test inputs rather than expecting the new warning, keeping the generated TypeSpec valid.

Original prompt

This section details on the original issue you should resolve

<issue_title>@head request with a body wrongly flags the content type</issue_title>
<issue_description>

Release 1.9.1 of @typespec/http updated so that the content-type header present in

Playground Link

I don't know if it is valid or not to do that with HEAD but the resulting openapi seems wrong as it now include the content type as header and the response has the wrong one

import "@typespec/http";

using Http;

@head
op listHead(): OkResponse | Error;

@error
model Error {
  @header
  contentType: "application/problem+json";

  type: string;
}

          headers:
            content-type:
              required: true
              schema:
                type: string
                enum:
                  - application/problem+json
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
```</issue_description>

<agent_instructions>We should emit a warning when this happen but also fix it so that we still respect the content type depsite it being against the HTTP spec. This means we probably need to move the logic where we decide if content-type should be a type: contentType or a header in the http property</agent_instructions>

## Comments on the Issue (you are @copilot in this section)

<comments>
<comment_new><author>@timotheeguerin</author><body>
Http spec explicitly disallow this https://www.rfc-editor.org/rfc/rfc2616#page-54

So I believe we should add a diagnostic here. Now the question is do we want to police this or just it be a warning
1. Make it an error, doesn't matter what the regression was because it can't compile
2. Make it a warning, what do we do here:
  a. Drop the response body
  b. Act like any other verb and treat the content type as the one of the response</body></comment_new>
</comments>

Fixes @head request with a body wrongly flags the content type #9832

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

…erb-body warning Co-authored-by: timotheeguerin <1031227+timotheeguerin@users.noreply.github.com>

…est.ts, improve changeset Co-authored-by: timotheeguerin <1031227+timotheeguerin@users.noreply.github.com>

packages/openapi3/test/tsp-openapi3/utils/tsp-for-openapi3.ts

packages/http/src/lib.ts

packages/http/src/payload.ts

…treatContentTypeAsHeader, revert tsp-for-openapi3.ts Co-authored-by: timotheeguerin <1031227+timotheeguerin@users.noreply.github.com>

pkg-pr-new · 2026-03-04T19:31:08Z

Open in StackBlitz

npm i https://pkg.pr.new/@typespec/http@9869

npm i https://pkg.pr.new/@typespec/openapi3@9869

commit: 5ac4332

markcowl · 2026-03-04T21:47:58Z

packages/http/src/lib.ts

        default: "`Content-Type` header ignored because there is no body.",
      },
    },
+    "head-no-body": {


Suggested change

"head-no-body": {

"head-operation-no-body": {

A little morbid otherwise.

markcowl · 2026-03-04T21:48:22Z

packages/http/src/responses.ts

+  if (verb === "head" && resolvedBody !== undefined) {
+    diagnostics.add(
+      createDiagnostic({
+        code: "head-no-body",


Suggested change

code: "head-no-body",

code: "head-operation-no-body",

markcowl · 2026-03-04T21:48:42Z

packages/http/test/responses.test.ts

+
+  expectDiagnostics(diagnostics, [
+    {
+      code: "@typespec/http/head-no-body",


Suggested change

code: "@typespec/http/head-no-body",

code: "@typespec/http/head-operation-no-body",

markcowl · 2026-03-04T21:49:10Z

packages/http/test/responses.test.ts

+  // Should get warning about body in HEAD response
+  expectDiagnostics(diagnostics, [
+    {
+      code: "@typespec/http/head-no-body",


Suggested change

code: "@typespec/http/head-no-body",

code: "@typespec/http/head-operation-no-body",

markcowl · 2026-03-04T21:49:35Z

packages/http/test/verbs.test.ts

+    expect(routes[0].verb).toBe("head");
+  });
+
+  it("@head with body emits head-no-body warning", async () => {


Suggested change

it("@head with body emits head-no-body warning", async () => {

it("@head with body emits head-operation-no-body warning", async () => {

markcowl · 2026-03-04T21:49:47Z

packages/http/test/verbs.test.ts

+
+  it("@head with body emits head-no-body warning", async () => {
+    const diagnostics = await diagnoseOperations(`@head op test(): string;`);
+    expectDiagnostics(diagnostics, [{ code: "@typespec/http/head-no-body", severity: "warning" }]);


Suggested change

expectDiagnostics(diagnostics, [{ code: "@typespec/http/head-no-body", severity: "warning" }]);

expectDiagnostics(diagnostics, [{ code: "@typespec/http/head-operation-no-body", severity: "warning" }]);

Initial plan

0737d66

Copilot AI assigned Copilot and timotheeguerin Mar 2, 2026

Copilot started work on behalf of timotheeguerin March 2, 2026 19:26 View session

fix: @Head request with body wrongly flags content type - emit head-v…

d4a3b1f

…erb-body warning Co-authored-by: timotheeguerin <1031227+timotheeguerin@users.noreply.github.com>

microsoft-github-policy-service bot added lib:http emitter:openapi3 Issues for @typespec/openapi3 emitter labels Mar 2, 2026

fix: address code review - add head-verb-body warning test in verbs.t…

40877dc

…est.ts, improve changeset Co-authored-by: timotheeguerin <1031227+timotheeguerin@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] Fix content type flagging for HEAD requests~~ fix(@typespec/http): @head response with body uses wrong content-type and missing warning Mar 2, 2026

Copilot finished work on behalf of timotheeguerin March 2, 2026 19:58

timotheeguerin reviewed Mar 3, 2026

View reviewed changes

packages/openapi3/test/tsp-openapi3/utils/tsp-for-openapi3.ts Show resolved Hide resolved

packages/http/src/lib.ts Outdated Show resolved Hide resolved

packages/http/src/lib.ts Outdated Show resolved Hide resolved

packages/http/src/payload.ts Outdated Show resolved Hide resolved

Copilot started work on behalf of timotheeguerin March 3, 2026 00:21 View session

fix: address reviewer feedback - rename to head-no-body, simplify to …

a24fe2f

…treatContentTypeAsHeader, revert tsp-for-openapi3.ts Co-authored-by: timotheeguerin <1031227+timotheeguerin@users.noreply.github.com>

Copilot AI changed the title ~~fix(@typespec/http): @head response with body uses wrong content-type and missing warning~~ fix(@typespec/http): @head response with body wrongly flags content type Mar 3, 2026

Copilot finished work on behalf of timotheeguerin March 3, 2026 00:35

markcowl reviewed Mar 4, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix(@typespec/http): `@head` response with body wrongly flags content type#9869

fix(@typespec/http): `@head` response with body wrongly flags content type#9869
Copilot wants to merge 4 commits intomainfrom
copilot/fix-head-request-content-type

Copilot AI commented Mar 2, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

pkg-pr-new bot commented Mar 4, 2026

Uh oh!

markcowl Mar 4, 2026

Uh oh!

markcowl Mar 4, 2026

Uh oh!

markcowl Mar 4, 2026

Uh oh!

markcowl Mar 4, 2026

Uh oh!

markcowl Mar 4, 2026

Uh oh!

markcowl Mar 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	code: "@typespec/http/head-no-body",
	code: "@typespec/http/head-operation-no-body",

	it("@head with body emits head-no-body warning", async () => {
	it("@head with body emits head-operation-no-body warning", async () => {

	expectDiagnostics(diagnostics, [{ code: "@typespec/http/head-no-body", severity: "warning" }]);
	expectDiagnostics(diagnostics, [{ code: "@typespec/http/head-operation-no-body", severity: "warning" }]);

Conversation

Copilot AI commented Mar 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

pkg-pr-new bot commented Mar 4, 2026

Uh oh!

markcowl Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

markcowl Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

markcowl Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

markcowl Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

markcowl Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

markcowl Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Mar 2, 2026 •

edited

Loading