azure/azure-sdk-for-java/union-type-wrappers

Union Type Wrappers for Generated Java Models

When the Java codegen encounters a TypeSpec union type (e.g. string | SomeModel), it emits the property as BinaryData. This skill replaces public BinaryData accessors with typed setters and getters for each union variant, following the same pattern established for PromptAgentDefinition.toolChoice.

Preconditions

• You must be in a Java SDK module directory containing tsp-location.yaml and pom.xml.
• TypeSpec sources must be available in TempTypeSpecFiles/. If missing, run tsp-client sync first.
• The project must compile before starting.

Important: BinaryData.writeTo(JsonWriter) semantics

Understanding how BinaryData writes to JSON is critical for choosing the correct factory method:

Key: JacksonAdapter has special handling for JsonSerializable types — BinaryData.fromObject() and BinaryData.toObject() both work correctly with Azure JsonSerializable models.

Setter factory method rules

Getter deserialization rules

Workflow

1. Scan for BinaryData properties

Find all BinaryData fields in generated model classes:

grep -rn "private\s\+\(final\s\+\)\?BinaryData\s\+" src/main/java/ --include="*.java"

Exclude List<BinaryData> and Map<..., BinaryData> from this pass — those are collection-of-union patterns that require separate handling.

2. Cross-reference against TypeSpec

For each BinaryData property found, determine whether it comes from a union type or an `unknown` type:

# Search for the property name (use the wire name, e.g. tool_choice, not toolChoice)
grep -rn "<wire_name>" TempTypeSpecFiles/ --include="*.tsp"

• Union type (type_a | type_b): Proceed with this skill.
• `unknown` type: Leave as BinaryData — this is the correct representation.

Also check client.tsp for any @@changePropertyType overrides that may have already flattened the union to string (like tool_choice).

3. Identify the union variants

For each union type, determine what types the property can hold. Sources:

1. Local TSP files — look at the type definition in TempTypeSpecFiles/.
2. Stainless SDK JAR — if the union comes from OpenAI.*, inspect the Stainless types:

``bash jar tf ~/.m2/repository/com/openai/openai-java-core/<version>/openai-java-core-<version>.jar | grep "<TypeName>" javap -cp <jar> "com.openai.models.responses.<OuterClass>\$<InnerUnion>" ``

1. Generated Azure models — check if the Azure SDK already generates the variant model classes (e.g. AutoCodeInterpreterToolParam, McpToolFilter).

4. Apply changes to the model class

For each union-typed BinaryData property, apply the following pattern:

4a. Leave the property field as-is

Do not modify the property declaration. Keep @Generated, the block comment, and the visibility exactly as the codegen produced them. The field is already private — there is nothing to change.

/*
 * Original generated block comment.
 */
@Generated
private BinaryData myField;

4b. Make the existing getter and setter package-private

• Remove @Generated.
• Change visibility to package-private (no access modifier). This keeps them hidden from SDK consumers but accessible to unit tests in the same package.
• Keep the original method name — do NOT rename to *Internal.
• Keep the original javadoc intact.
• Add // AI Tooling: union type as the first line inside the method body.

/**
 * Get the myField property: original description.
 *
 * @return the myField value.
 */
BinaryData getMyField() {
    // AI Tooling: union type
    return this.myField;
}
 
/**
 * Set the myField property: original description.
 *
 * @param myField the myField value to set.
 * @return the MyClass object itself.
 */
MyClass setMyField(BinaryData myField) {
    // AI Tooling: union type
    this.myField = myField;
    return this;
}

For `@Immutable` classes (value is a constructor param):

• Change the BinaryData constructor visibility to package-private (keep for fromJson deserialization).
• Add public constructor overloads for each variant.
• Make the BinaryData getter private.

/**
 * Creates an instance of MyFilter class.
 *
 * @param type the type value to set.
 * @param key the key value to set.
 * @param value the value value to set.
 */
MyFilter(MyFilterType type, String key, BinaryData value) {
    // AI Tooling: union type
    this.type = type;
    this.key = key;
    this.value = value;
}
 
public MyFilter(MyFilterType type, String key, String value) {
    this.type = type;
    this.key = key;
    this.value = BinaryData.fromObject(value);
}

4c. Add typed setters (one per union variant)

Naming convention: `set<PropertyName>(<VariantType> value)` — use method overloading.

Copy the javadoc from the original generated setter, adapting the @param description to the specific variant type. Add // AI Tooling: union type as the first line inside the method body.

/**
 * Set the myField property: original description.
 *
 * @param myField the string value to set.
 * @return the MyClass object itself.
 */
public MyClass setMyField(String myField) {
    // AI Tooling: union type
    this.myField = BinaryData.fromString(myField);
    return this;
}
 
/**
 * Set the myField property: original description.
 *
 * @param myField the SomeModel value to set.
 * @return the MyClass object itself.
 */
public MyClass setMyField(SomeModel myField) {
    // AI Tooling: union type
    this.myField = BinaryData.fromObject(myField);
    return this;
}

When overloading isn't possible (e.g. two different String meanings), disambiguate with parameter names and javadoc.

For List<String> variants:

/**
 * Set the allowedTools property: original description.
 *
 * @param allowedTools the list of tool name strings to set.
 * @return the McpTool object itself.
 */
public McpTool setAllowedTools(List<String> allowedTools) {
    // AI Tooling: union type
    this.allowedTools = BinaryData.fromObject(allowedTools);
    return this;
}

4d. Add typed getters (one per union variant)

Naming convention: `get<PropertyName>As<TypeName>()`

Copy the javadoc from the original generated getter, adapting the @return description. Add // AI Tooling: union type as the first line inside the method body.

/**
 * Get the myField property as a String: original description.
 *
 * @return the myField value as a String.
 */
public String getMyFieldAsString() {
    // AI Tooling: union type
    if (this.myField == null) {
        return null;
    }
    return this.myField.toObject(String.class);
}
 
/**
 * Get the myField property as a {@link SomeModel}: original description.
 *
 * @return the myField value as a SomeModel.
 */
public SomeModel getMyFieldAsSomeModel() {
    // AI Tooling: union type
    if (this.myField == null) {
        return null;
    }
    return this.myField.toObject(SomeModel.class);
}

For List<String> variants:

/**
 * Get the allowedTools property as a list of tool name strings: original description.
 *
 * @return the allowedTools value as a list of Strings.
 */
@SuppressWarnings("unchecked")
public List<String> getAllowedToolsAsStringList() {
    // AI Tooling: union type
    if (this.allowedTools == null) {
        return null;
    }
    return this.allowedTools.toObject(List.class);
}

5. Update callers

Search for existing code that uses the old BinaryData API:

grep -rn "\.setMyField(BinaryData\|\.getMyField()" src/ --include="*.java"

Update samples, tests, and internal code to use the new typed API. Remove unused BinaryData imports where applicable.

6. Write unit tests

Create a test class per model under src/test/java/.../models/<ModelName>SerializationTests.java.

Each test class must include:

1. Serialization tests — one per union variant. Construct the model with the typed setter, serialize to JSON, assert the JSON contains the expected field and value.
2. Deserialization tests — one per union variant. Parse a JSON string, assert the typed getter returns the correct value.
3. Null/absent tests — verify getters return null when the field is not set or absent from JSON.
4. Round-trip tests — serialize → deserialize → assert values match.

Use these helpers:

private String serializeToJson(MyModel model) throws IOException {
    ByteArrayOutputStream outputStream = new ByteArrayOutputStream();
    try (JsonWriter jsonWriter = JsonProviders.createWriter(outputStream)) {
        model.toJson(jsonWriter);
    }
    return outputStream.toString("UTF-8");
}
 
private MyModel deserializeFromJson(String json) throws IOException {
    try (JsonReader jsonReader = JsonProviders.createReader(json)) {
        return MyModel.fromJson(jsonReader);
    }
}

7. Compile and run tests

mvn compile -Dbuildhelper.addtestsource.skip=true -Dbuildhelper.addtestresource.skip=true \
    -Dcodesnippet.skip=true -Dcheckstyle.skip=true -Dspotless.check.skip=true
 
mvn "-Dtest=*SerializationTests" test \
    -Dcodesnippet.skip=true -Dcheckstyle.skip=true -Dspotless.check.skip=true

All tests must pass before finishing.

Checklist

Before reporting completion, verify:

• [ ] Every BinaryData property was classified as union or unknown
• [ ] Property fields left exactly as generated (no modifications)
• [ ] Original BinaryData getter/setter made package-private, name kept, @Generated removed, javadoc preserved
• [ ] // AI Tooling: union type placed inside the body of every modified or added getter/setter
• [ ] Typed setters added for each union variant with javadoc copied from original
• [ ] Typed getters added for each union variant (get*As*()) with javadoc copied from original
• [ ] All callers (samples, tests, internal code) updated to use new API
• [ ] Unused BinaryData imports removed from callers
• [ ] Unit tests written and passing for serialization, deserialization, null, and round-trip
• [ ] Full compilation succeeds (main + test + samples)

Troubleshooting