Add commaDelimited and newlineDelimited to ArrayEncoding enum

[Copilot]

Adding commaDelimited and newlineDelimited to ArrayEncoding enum ✅

Implementation complete!

• Explore repository structure and build system
• Understand ArrayEncoding enum location and current values
• Add commaDelimited and newlineDelimited enum members to ArrayEncoding in decorators.tsp
• Update documentation for existing enum members (pipeDelimited and spaceDelimited)
• Add tests for the new enum values in compiler tests
• Update openapi3 encoding logic to recognize new enum values
• Update openapi3 examples.ts to handle new delimiters
• Add comprehensive tests in openapi3 for the new delimiters
• Create changelog entry for the changes
• Run tests and ensure everything passes
• Run linting and format checks
• Manual verification with TypeSpec compiler
• Regenerate JS documentation for compiler
• Fix cspell violations
• Update tests to use new Tester pattern
• Final verification

Summary

This PR successfully adds commaDelimited and newlineDelimited values to the ArrayEncoding enum as per the approved design. The implementation includes:

Core Changes:

1. decorators.tsp - Added two new enum members with comprehensive documentation explaining how they work in different protocols (JSON vs HTTP)
2. Updated existing documentation - Enhanced docs for pipeDelimited and spaceDelimited to match the new format

OpenAPI3 Integration:

3. encoding.ts - Updated to recognize the new encoding values
4. parameters.ts - Extended parameter style handling to support comma and newline delimiters
5. examples.ts - Added support for generating examples with the new delimiters

Testing:

6. Compiler tests - Added 4 new tests verifying each ArrayEncoding enum value can be used (updated to use new Tester pattern)
7. OpenAPI3 examples tests - Added 12 comprehensive tests covering all scenarios (undefined, string, array, object) × (explode true/false) for both new delimiters
8. OpenAPI3 parameters tests - Added 2 tests verifying parameter style mapping

Documentation:

9. Changelog - Created proper change entry documenting the feature addition
10. Built-in data types documentation - Regenerated to include the new enum values with full descriptions
11. cspell exceptions - Added URL-encoded color names (Ablack, Cblack, Cbrown) from test strings to exceptions list

Test Results:

• ✅ All 208 compiler tests pass
• ✅ All 2,326 openapi3 tests pass (262 in examples.test.ts, 172 in parameters.test.ts)
• ✅ Linting passes
• ✅ Code formatting verified
• ✅ Manual verification with TypeSpec compiler successful
• ✅ Documentation regenerated successfully
• ✅ Cspell violations fixed
• ✅ Tests updated to use new Tester pattern

The implementation follows TypeSpec conventions and properly integrates with the existing ArrayEncoding infrastructure.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Add support for list with encode of string</issue_title>
<issue_description>### Clear and concise description of the problem

Short version:

model MyModel {
  @encode(string, ",")
  terms: string[];
}

would match this JSON:

{
  "synomyms": "a,b,c"
}

and produce SDK like:

class Data:
   synonyms: List[str]

Which will tell the serializer deserializer to use csv, for instance a,b,c. Delimiter is the second parameter. We may decide to accept it only on list of strings for now (refuse int[])

Kwown separator: \n, | and ,

Checklist

• Follow our Code of Conduct
• Read the docs.
• Check that there isn't already an issue that request the same feature to avoid creating a duplicate.</issue_description>

<agent_instructions>Per the approved design, add new elements for commaDelimited and newlineDelimited lists to the array encoding enum, including documentation, changelog entry, and tests for the new values.</agent_instructions>

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

@bterlson My feeling on this:

We have ArrayEncoding.spaceDelimited and ArrayEncoding.commaDelimited which today only work in query strings. It's not clear how these should even work outside of that context because the escaping rules are not specified. This seems like a related problem to solve.

One proposal I like is to add ArrayEncoding.CSV with a configurable delimiter and make the existing encoding formats aliases for CSV encoding with the proper delimiter (e.g. ArrayEncoding.spaceDelimited would mean the same thing as ArrayEncoding.CSV, #{ delimiter: " " }). We can follow the CSV RFC for this. For example:

model Foo {
  @encode(ArrayEncoding.CSV)
  list: string[];
  matrix: string[][];
}

might look like this on the wire:

{
  list: "\"A,B\", C",
  matrix: "r1c1,r1c2\nr2c1,r2c2"
}

One concern with this approach is that it would require a standards compliant CSV parser for HTTP clients/servers, which may not in fact be needed. E.g. we know of a service which takes CSV but does not allow commas in the elements which means you can safely split/join. We might consider something like a noEscape option for this scenario.</comment_new>
<comment_new>@timotheeguerin
Add commaDelimited, newlineDelimited to ArrayEncoding in core and update pipeDelimited and spaceDelimited to have similar doc around containing the delimiter

enum ArrayEncoding {
  /**
   * Values can only contain , if underlying protocol supports encoding those
   * - json -> error
   * - http -> %2C
   */
  commaDelimited,

  /**
   * Values can only contain \n if underlying protocol supports encoding those
   * - json -> error
   * - http -> %0A
   */
  newlineDelimited,
}

Appendix : Encoding with options

Just for reference, do not implement

A POC of what we could do without new language syntax

namespace Encoding {
  scalar custom;

  scalar `array` extends custom {
    /**
     * Values can only contain the delimiter if underlying protocol supports encoding those
     * Example delimiter: ,
     * - json -> error
     * - http -> %2c
     */
    init join(delimiter: valueof string);
  }
}
 model Test {
   @encode(CustomCSVEncoding("-"))
   @encode(#{encoding: ArrayEncoding2.CSV, sep: "-"})
   foo: string[]
 }

```</body></comment_new>
</comments>

• Fixes Add support for list with encode of string #8874

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[markcowl]

@copilot please regenerate js documentation for the compiler and include the updated markdown file in this PR. you can do this by executing pnpm regen-docs in the compiler package directory.

[markcowl]

@copilot Please fix cspell violations in the PR. You can do this by adding the violating terms to the exceptions list for cspell.

[Copilot]

@copilot please regenerate js documentation for the compiler and include the updated markdown file in this PR. you can do this by executing pnpm regen-docs in the compiler package directory.

Documentation regenerated and included in commit fbaaabd. The built-in-data-types.md file now includes the new commaDelimited and newlineDelimited enum values with full protocol-specific documentation.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• telemetry.astro.build
  • Triggering command: node /home/REDACTED/work/typespec/typespec/website/node_modules/.bin/../astro/astro.js build (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[Copilot]

@copilot Please fix cspell violations in the PR. You can do this by adding the violating terms to the exceptions list for cspell.

Cspell violations fixed in commit bac10d0. Added Ablack, Cblack, and Cbrown to the exceptions list - these are URL-encoded color names from the test data (e.g., "blue%2Cblack%2Cbrown" where %2C is comma, %0A is newline).

[github-actions]

All changed packages have been documented.

• ✅ @typespec/compiler
• ✅ @typespec/openapi3

Show changes

@typespec/compiler - feature ✏️

Add commaDelimited and newlineDelimited values to ArrayEncoding enum for serializing arrays with comma and newline delimiters

@typespec/openapi3 - feature ✏️

Add commaDelimited and newlineDelimited values to ArrayEncoding enum for serializing arrays with comma and newline delimiters

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/microsoft/typespec/@typespec/compiler@9002

npm i https://pkg.pr.new/microsoft/typespec/@typespec/openapi@9002

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

commit: 68c385d

[Copilot]

Just as a heads up, I was blocked by some firewall rules while working on your feedback. Expand below for details.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• telemetry.astro.build
  • Triggering command: node /home/REDACTED/work/typespec/typespec/website/node_modules/.bin/../astro/astro.js build (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[tadelesh]

ArrayEncoding is not used in the encode decorator behavior code. Should we add lint to only allow it to be set on array type? @timotheeguerin

[timotheeguerin]

hhm yeah could do that, can you file an issue

[tadelesh]

Array encoding's usage is different from bytes/datetime/duration. It uses the TypeSpec enum value name instead a defined type in ts lib.

[timotheeguerin]

yes this is expected, same as xml libraries. Using the fqn allows it to make sure it doesn't conflict with anything else. We couldn'tchange the other one for back compat