Skip to content

LastContractView - Restore Previous Names of Unknown Discriminator Models #12600

Open

Description

Clear and concise description of the problem

For every discriminated base model, the generator synthesizes a fallback model named Unknown{InputBaseModelName} (InputModelType.DiscriminatedSubtypes) and references it from the public base through [PersistableModelProxy(typeof(UnknownX))] (MrwSerializationTypeDefinition).

The unknown model is generated internal by default, but it is public when custom code declares it so (ModelProvider.BuildDeclarationModifiers takes accessibility from the custom code view). Either way its name is part of the checked contract:

  • When it is internal, the proxy attribute on the public base still exposes the name: azure-sdk-for-net enables ApiCompat's AttributesMustMatch rule (eng/Directory.Build.Common.targets) and does not exclude PersistableModelProxyAttribute. When the generated unknown model name differs from the shipped one, ApiCompat fails.
  • When it is public, renaming it is also a type removal.

The previous name generally cannot be recomputed from the current model. Shipped names usually derive from the original swagger schema name rather than the final C# base name, for example:

Base model Generated today Shipped (GA)
PipelineActivity UnknownPipelineActivity UnknownActivity
CopyActivitySource UnknownCopyActivitySource UnknownCopySource
DataBoxBasicJobDetails UnknownDataBoxBasicJobDetails UnknownJobDetails

Library authors currently restore each name by hand:

[CodeGenType("UnknownPipelineActivity")]
internal partial class UnknownActivity
{
}

As of azure-sdk-for-net main (6d623813cb9), TypeSpec-generated libraries contain 103 such renames across 23 libraries, 94 of which are empty partials that exist only to restore the name: MachineLearning (19), DataProtectionBackup (15), RecoveryServicesBackup (14), RecoveryServicesSiteRecovery (10), DataFactory (8), DataBox (6), Cdn (5), DataMigration (4), ServiceFabricManagedClusters (4), ServiceLinker (4), Avs (2), and one each in Azure.AI.Agents.Persistent, AlertsManagement, ScVmm, BotService, CognitiveServices, CosmosDB, EdgeOrder, EventHubs, MySql, Network, Quota and StorageMover.

Proposal

When naming an unknown discriminator model, use the name recorded in the last contract's PersistableModelProxyAttribute on the corresponding base model.

The attribute is the authoritative source: it is exactly the value ApiCompat compares, it is on a public type that LastContractView already loads, and NamedTypeSymbolProvider.BuildAttributes already exposes it. This is preferred over scanning the last contract for subtypes prefixed with Unknown, which would require enumerating every type (Roslyn has no derived-type index), would need internal-type lookups in the common case where the unknown model is internal (FindForTypeInLastContract excludes internal types), and would be ambiguous for real models whose names start with Unknown and for multi-level discriminator hierarchies.

Requirements

  1. For a model where IsUnknownDiscriminatorModel is true, read BaseModelProvider.LastContractView.Attributes, find System.ClientModel.Primitives.PersistableModelProxyAttribute, and use its typeof argument's type name as the unknown model's name.
  2. Apply the restored name only when all of the following hold:
    • The base model has a last-contract view and exactly one PersistableModelProxyAttribute with a resolvable type argument.
    • The proxy type is in the same namespace as the current unknown model.
    • The name is not already used by another type the generator emits (other than this unknown model) or by a custom type that is not a customization of this unknown model.
    • The restoration does not reference a type whose removal is accepted in the ApiCompat baseline.
  3. Apply per discriminated base, so each level of a multi-level hierarchy restores its own unknown model name independently.
  4. Resolve the name when the unknown model's name is built (not by updating it afterwards), so the proxy attribute, serialization, deserialization dispatch, model factory and ModelReaderWriterContext registrations all observe the same name. The base model's name and last-contract lookup must not depend on the unknown model's name, to avoid re-entrancy.
  5. Existing [CodeGenType("Unknown...")] customizations must continue to work unchanged, whether they target the previously generated name or the restored name.
  6. Emit an informational back-compat diagnostic when a name is restored, and a diagnostic explaining why when a candidate name is found but rejected by one of the guards above.
  7. When there is no last contract, or the base has no proxy attribute, behavior is unchanged.
  8. The restoration must work whether the unknown model is internal or public. Accessibility continues to come from custom code; restoring the accessibility of an unknown model that was public in the last contract but is no longer declared public is out of scope for this issue.
  9. Performance: at most one attribute lookup per discriminated base model; no scan of the last-contract assembly.

Success criteria

  • A library whose last contract has [PersistableModelProxy(typeof(UnknownActivity))] on PipelineActivity generates internal partial class UnknownActivity and [PersistableModelProxy(typeof(UnknownActivity))] with no custom code, and ApiCompat passes.
  • Deleting the empty CodeGenType rename partials listed above and regenerating produces no API changes and no ApiCompat errors (validate on at least DataFactory and MachineLearning).
  • Libraries that keep their existing CodeGenType rename partials regenerate identically.
  • Libraries without a last contract, and models without a last-contract proxy attribute, generate the same output as today.
  • Unit tests in the generator cover:
    • name restored from the last-contract proxy attribute;
    • name restored for an unknown model that custom code declares public;
    • multi-level discriminator hierarchy with distinct restored names per level;
    • restoration skipped when the name collides with another generated or custom type;
    • existing CodeGenType customization targeting the previously generated name still applies;
    • no last contract / no proxy attribute leaves the name unchanged.

Parent: #7241

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.

Activity

  1. github-actions commented on Nov 17, 2026

    @github-actions
    Contributor

    🎯 Issue Triage
    This feature request proposes restoring generated unknown discriminator model names from the previous contract's PersistableModelProxyAttribute.
    It would remove widespread manual CodeGenType rename customizations while preserving ApiCompat and generated-code consistency.
    Category: Feature Request
    Area: emitter:client:csharp

    🔍 Analysis

    The C# client emitter currently derives fallback names from the current base model name, but shipped contracts may expose an older schema-derived name through PersistableModelProxyAttribute. This affects unknown-model naming, proxy attributes, serialization/deserialization dispatch, model factories, and ModelReaderWriterContext registration.

    The proposed source of truth is technically appropriate because LastContractView already exposes attributes on the public base model and avoids scanning the previous assembly. Implementation must resolve the name during model construction, guard namespace/type collisions and accepted removals, preserve existing CodeGenType customizations, and cache the lookup per discriminated base. Multi-level hierarchies require independent restoration at each level.

    No strong duplicate was found. This is a specific child scenario of the broader back-compat tracking issue #7241.

    📝 Suggested next steps
    • Add focused unit tests for restoration, customization compatibility, hierarchy handling, collision guards, and unchanged fallback behavior.
    • Implement name resolution and diagnostics in the unknown discriminator model naming path.
    • Validate generated API compatibility for representative DataFactory and MachineLearning libraries.

    Generated by Agentic Triage

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Labels

emitter:client:csharpIssue for the C# client emitter: @typespec/http-client-csharpfeatureNew feature or request

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions