Implement array encoding for model properties by JialinHuang803 · Pull Request #3659 · Azure/autorest.typescript

JialinHuang803 · 2025-12-23T02:50:20Z

Resolve: #3604

Overview

This PR implements support for array encoding decorators @encode(ArrayEncoding.*) within TypeSpec model properties. Previously, array encoding was only supported for query and header parameters, but now it extends to model properties as well, enabling proper serialization and deserialization of array fields with different delimited formats. Currently only array of string type is supported for encoding.

What's included

Support 4 delimiters for encoding model properties of string array type, including ',', ' ', '|', and '\n'.

Added parsing helpers for CSV, SSV, pipe, and newline formats, and added serialization helper for newline format.
Updated the logic for serializing and deserializing array parameters and properties.
Refactored internal helpers for handling collection formats.
Introduced a new diagnostic warning (un-supported-array-encoding) that triggers when an array of an unsupported type is marked for encoding.

For example:

model Widget {
    @encode(ArrayEncoding.commaDelimited)
    requiredColors: string[];

    @encode(ArrayEncoding.spaceDelimited)
    optionalColors?: string[];
}

Serialization
string[] -> string, an empty array will be serialized as "".

export function widgetSerializer(item: Widget): any {
  return {
    requiredColors: buildCsvCollection(
      item["requiredColors"].map((p: any) => {
        return p;
      }),
    ),
    optionalColors: !item["optionalColors"]
      ? item["optionalColors"]
      : buildSsvCollection(
          item["optionalColors"].map((p: any) => {
            return p;
          }),
        ),
  };
}

Deserialization
string -> string[], an empty string "" will be deserialized as an empty array.

export function widgetDeserializer(item: any): Widget {
  return {
    requiredColors: parseCsvCollection(item["requiredColors"]),
    optionalColors:
      item["optionalColors"] === null || item["optionalColors"] === undefined
        ? item["optionalColors"]
        : parseSsvCollection(item["optionalColors"]),
  };
}

Impact on existing generated code

The generated code related to the collection format query and header parameter got changed if the parameter is optional, but its behavior should remain unchanged.
For example,
TypeSpec:

@get read(
  @path
  id: Widget.id,

  @query
  @encode(ArrayEncoding.pipeDelimited)
  colors?: string[],

  @header
  weights?: string[],
): Widget;

Before:

onst path = expandUrlTemplate(
  "/widgets/{id}{?colors}",
  {
    id: id,
    colors:
      options?.colors !== undefined
        ? buildPipeCollection(
            !options?.colors
              ? options?.colors
              : options?.colors.map((p: any) => {
                  return p;
                }),
          )
        : undefined,
  },
  {
    allowReserved: options?.requestOptions?.skipUrlEncoding,
  },
);
return context.path(path).get({
  ...operationOptionsToRequestParameters(options),
  headers: {
    ...(options?.weights !== undefined
      ? {
          weights:
            options?.weights !== undefined
              ? buildCsvCollection(
                  !options?.weights
                    ? options?.weights
                    : options?.weights.map((p: any) => {
                        return p;
                      }),
                )
              : undefined,
        }
      : {}),
    accept: "application/json",
    ...options.requestOptions?.headers,
  },
});

After:

const path = expandUrlTemplate(
  "/widgets/{id}{?colors}",
  {
    id: id,
    colors: !options?.colors
      ? options?.colors
      : buildPipeCollection(
          options?.colors.map((p: any) => {
            return p;
          }),
        ),
  },
  {
    allowReserved: options?.requestOptions?.skipUrlEncoding,
  },
);
return context.path(path).get({
  ...operationOptionsToRequestParameters(options),
  headers: {
    ...(options?.weights !== undefined
      ? {
          weights: !options?.weights
            ? options?.weights
            : buildCsvCollection(
                options?.weights.map((p: any) => {
                  return p;
                }),
              ),
        }
      : {}),
    accept: "application/json",
    ...options.requestOptions?.headers,
  },
});

Copilot

Pull request overview

This PR implements comprehensive support for array encoding decorators (@encode(ArrayEncoding.*)) for TypeSpec model properties, extending functionality that previously existed only for query and header parameters. The implementation adds support for four delimiter formats: comma-delimited (CSV), space-delimited (SSV), pipe-delimited, and newline-delimited for string array properties.

Key Changes:

Added parsing helpers for CSV, SSV, pipe, and newline-delimited formats to convert encoded strings back to arrays
Added a build helper for newline-delimited format to convert arrays to encoded strings
Refactored collection format handling logic to support model properties in addition to parameters
Introduced a new diagnostic warning for unsupported array encodings (non-string array types)

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
`packages/typespec-ts/static/static-helpers/serialization/parse-csv-collection.ts`	New helper to parse comma-delimited strings into string arrays
`packages/typespec-ts/static/static-helpers/serialization/parse-ssv-collection.ts`	New helper to parse space-delimited strings into string arrays
`packages/typespec-ts/static/static-helpers/serialization/parse-pipe-collection.ts`	New helper to parse pipe-delimited strings into string arrays
`packages/typespec-ts/static/static-helpers/serialization/parse-newline-collection.ts`	New helper to parse newline-delimited strings into string arrays
`packages/typespec-ts/static/static-helpers/serialization/build-newline-collection.ts`	New helper to build newline-delimited strings from arrays
`packages/typespec-ts/src/utils/operationUtil.ts`	Refactored collection format handling to support properties; added enum for known collection formats and helper functions
`packages/typespec-ts/src/modular/static-helpers-metadata.ts`	Registered new parse and build helpers for collection formats
`packages/typespec-ts/src/modular/helpers/operationHelpers.ts`	Updated serialization and deserialization logic to handle array encoding for model properties
`packages/typespec-ts/src/lib.ts`	Added new diagnostic warning for unsupported array encoding types
`packages/typespec-ts/test/modularUnit/scenarios/models/serialization/modelPropertyArrayEncoding.md`	New test scenarios demonstrating array encoding for model properties
`packages/typespec-ts/test/modularUnit/scenarios/models/deserialization/propertyType.md`	Fixed typo in property name from "propStringUnionOptioanl" to "propStringUnionOptional"
`packages/typespec-ts/test/modularUnit/scenarios/models/propertyFlatten/nameCollision.md`	Formatting updates adding trailing commas for consistency

MaryGao · 2025-12-24T07:00:08Z

+  property: SdkModelPropertyType
+): string | undefined {
+  if (property.encode && property.type.kind === "array") {
+    // Only arrays of string type can have collectionFormat encoding


where do we get the agreement on only supporting string?

I found the TypeSpec issue mentioned maybe only string[] is supported. I think we can support only string[] for now and consider adding other primitive types if requested by other service teams.

MaryGao · 2025-12-24T07:00:24Z

        default: paramMessage`Model name conflict detected: "${"modelName"}" exists in multiple namespaces: ${"namespaces"}. Please use @clientName to rename them.`
      }
+    },
+    "un-supported-array-encoding": {


do we have an UT for this?

…torest.typescript into array-encoding

MaryGao · 2025-12-24T07:22:46Z

+        return `${nullOrUndefinedPrefix}Object.fromEntries(Object.entries(${restValue}).map(([k, p]: [string, any]) => [k, ${elementNullOrUndefinedPrefix}p]))`;
      } else if (type.valueType) {
-        return `Object.fromEntries(Object.entries(${prefix}).map(([k, p]: [string, any]) => [k, ${elementNullOrUndefinedPrefix}${deserializeResponseValue(context, type.valueType, "p", getEncodeForType(type.valueType))}]))`;
+        return `${nullOrUndefinedPrefix}Object.fromEntries(Object.entries(${restValue}).map(([k, p]: [string, any]) => [k, ${elementNullOrUndefinedPrefix}${deserializeResponseValue(context, type.valueType, "p", true, getEncodeForType(type.valueType))}]))`;


why the requred value is fixed as true here? not devired from other values like prop.optional?

This is to keep the behavior consistent with before. In addition, whether the value p should have optional prefix is decided by elementNullOrUndefinedPrefix.

MaryGao · 2025-12-24T07:24:26Z

+                : "";
+            return `${optionalPrefixForString}${parseHelper}(${restValue})`;
+          } else {
+            throw `No supported collection format parse helper found for ${format}.`;


throw exeptions? does that mean the emitter will crash?

The exception is added here because the original getCollectionFormat method throws an exception if getCollectionFormatHelper doesn't return a helper:

const collectionInfo = getCollectionFormatHelper(param.kind, format ?? ""); if (!collectionInfo) { throw "Has collection format info but without helper function detected"; }

I remove the logic from that method here. It's fine if we don't want to throw exceptions here.

I remember we have some earlier discussion that emitters should not throw error (crash) on purpose instead we should reportDiagnostic #3064

Removed the exception.

Strange, the code diff doesn't show as removed. Also, is possible to report diagnostic warning?

MaryGao · 2025-12-24T07:28:14Z

+    requiredCsvColors: parseCsvCollection(item["requiredCsvColors"]),
+    requiredPipeColors: parsePipeCollection(item["requiredPipeColors"]),
+    optionalSsvColors:
+      item["optionalSsvColors"] == null


ususally we don't recommand to use "==" check, instead use "===" or more explicit expression.

Ok, I will update it to item["optionalSsvColors"] === null || item["optionalSsvColors"] === undefined.

MaryGao · 2025-12-24T07:32:06Z

@@ -0,0 +1,3 @@
+export function parseCsvCollection(value: string): string[] {
+  return value ? value.split(",") : [];


no need for the ? check since this is required?

The value ? here is to ensure [] is returned if the input value is "". If return value.split(",") directly, an array containing an empty string [""] will be returned which is not expected.

MaryGao · 2025-12-24T07:35:16Z

+): string | undefined {
+  if (property.encode && property.type.kind === "array") {
+    // Only arrays of string type can have collectionFormat encoding
+    if (property.type.valueType.kind !== "string") {


i wonder if the string-like type is supported like ("a" | "b")[]?

Great question. I tested it, and it's not supported since it's an array of enum type...

MaryGao · 2025-12-24T07:38:14Z

+    case "commaDelimited":
+      return KnownCollectionFormat.Csv;
+    case "newlineDelimited":
+      return KnownCollectionFormat.Newline;


No KnownCollectionFormat.Multi for model property?

No. ArrayEncoding only includes "pipeDelimited" | "spaceDelimited" | "commaDelimited" | "newlineDelimited".

qiaozha · 2025-12-26T03:04:05Z

+                : "";
+            return `${optionalPrefixForString}${parseHelper}(${restValue})`;
+          } else {
+            throw `No supported collection format parse helper found for ${format}.`;


I remember we have some earlier discussion that emitters should not throw error (crash) on purpose instead we should reportDiagnostic #3064

…torest.typescript into array-encoding

qiaozha

just a minor comment left, feel free to merge if it's resolved.

qiaozha · 2025-12-27T02:05:04Z

+                : "";
+            return `${optionalPrefixForString}${parseHelper}(${restValue})`;
+          } else {
+            throw `No supported collection format parse helper found for ${format}.`;


Strange, the code diff doesn't show as removed. Also, is possible to report diagnostic warning?

JialinHuang803 added 2 commits December 23, 2025 10:46

Implement array encoding

271493e

Refine code and update unit tests

f49d53b

JialinHuang803 marked this pull request as ready for review December 23, 2025 08:08

JialinHuang803 requested review from MaryGao, joheredi and qiaozha as code owners December 23, 2025 08:08

JialinHuang803 requested a review from Copilot December 23, 2025 09:08

Copilot started reviewing on behalf of JialinHuang803 December 23, 2025 09:08 View session

Copilot AI reviewed Dec 23, 2025

View reviewed changes

JialinHuang803 and others added 3 commits December 23, 2025 19:11

Refine code and update tests

eca307d

Tiny update

4e7d9ee

Merge branch 'main' into array-encoding

0e64fa8

MaryGao reviewed Dec 24, 2025

View reviewed changes

JialinHuang803 added 2 commits December 24, 2025 15:09

Update unit tests for query/header parameters with collection format

c03d5e1

Merge branch 'array-encoding' of https://github.com/JialinHuang803/au…

e2ae2e8

…torest.typescript into array-encoding

MaryGao reviewed Dec 24, 2025

View reviewed changes

qiaozha assigned MaryGao Dec 24, 2025

qiaozha added the p0 priority 0 label Dec 24, 2025

JialinHuang803 added 3 commits December 24, 2025 17:07

Add unit test for report diagnostic case

1c6edd3

Refine code

780f0fc

Add a unit test for query parameter

4c21083

qiaozha reviewed Dec 26, 2025

View reviewed changes

Comment thread ...s/typespec-ts/test/modularUnit/scenarios/operations/queryParam/queryParamCollectionFormat.md Outdated

JialinHuang803 and others added 2 commits December 26, 2025 11:11

Nit update

37640c2

Merge branch 'main' into array-encoding

4c74720

qiaozha reviewed Dec 26, 2025

View reviewed changes

JialinHuang803 added 2 commits December 26, 2025 15:45

Remove throwing exception

64d8b09

Merge branch 'array-encoding' of https://github.com/JialinHuang803/au…

549110e

…torest.typescript into array-encoding

qiaozha approved these changes Dec 27, 2025

View reviewed changes

JialinHuang803 and others added 2 commits January 4, 2026 09:08

Refine code

2a36630

Merge branch 'main' into array-encoding

9b102d3

JialinHuang803 enabled auto-merge (squash) January 4, 2026 01:09

JialinHuang803 merged commit 09452f5 into Azure:main Jan 4, 2026
16 checks passed

JialinHuang803 deleted the array-encoding branch January 4, 2026 02:24

Copilot AI mentioned this pull request Jan 5, 2026

Bump emitter versions: typespec-ts and rlc-common to 0.48.0, autorest.typescript to 6.0.55 #3671

Merged

11 tasks

qiaozha mentioned this pull request Jan 7, 2026

Review the current behavior of query and header parameters when encoded with collection format #3663

Open

		@@ -0,0 +1,3 @@
		export function parseCsvCollection(value: string): string[] {
		return value ? value.split(",") : [];

Conversation

JialinHuang803 commented Dec 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Overview

What's included

Impact on existing generated code

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Key Changes:

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

MaryGao Dec 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

qiaozha left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

JialinHuang803 commented Dec 23, 2025 •

edited

Loading

MaryGao Dec 24, 2025 •

edited

Loading