Code model deserialization cannot resolve references first defined inside decorator arguments

[ArcturusZhang]

Description

Reference-preserving code-model JSON can fail to deserialize when a shared object is first serialized inside a decorator argument and referenced later from the main code-model graph.

For example, the serialized shape can effectively contain:

{
  "decorators": [
    {
      "name": "example",
      "arguments": {
        "value": {
          "$id": "2463",
          "name": "SharedModel"
        }
      }
    }
  ],
  "models": [
    {
      "$ref": "2463"
    }
  ]
}

The C# code-model reader currently captures decorator arguments as opaque JSON/BinaryData. Because those nested values are not deserialized through the shared TypeSpec reference resolver, $id: 2463 is never registered. Deserialization later reaches $ref: 2463 in the ordinary model graph and fails with an error similar to:

System.Text.Json.JsonException: cannot resolve reference 2463

We encountered this while upgrading the Azure management-plane C# generator. The immediate SDK-side mitigation removes model-valued arguments from known decorators before serializing the code model, but this is fragile: new decorators can reintroduce the same graph shape, and consumers may legitimately need those arguments.

Suggested change

Decorator arguments should participate in the same reference-resolution pass as the rest of the code model. Possible approaches include:

1. Deserialize decorator argument values through the shared TypeSpecReferenceResolver rather than capturing their raw JSON directly.
2. Pre-scan the complete JSON document to register all $id nodes before resolving $ref nodes, including IDs nested under opaque or extensibility properties.
3. Preserve raw decorator JSON only after reference metadata has been registered or normalized, so opaque payload handling cannot hide graph identities from the resolver.

The desired behavior is that a $ref remains resolvable regardless of where the corresponding $id first appears in the serialized document.

Impact

This failure blocked regeneration of multiple Azure management SDK libraries after a dependency upgrade. Sanitizing decorator arguments avoids the immediate exception but loses metadata and does not address the underlying deserializer behavior.

[github-actions]

🎯 Issue Triage
The C# code-model reader cannot resolve a shared object when its $id first appears inside an opaque decorator argument and a later $ref appears in the main model graph. This blocks SDK regeneration and the current mitigation discards decorator metadata.
Category: Bug
Area: emitter:client:csharp

⚠️ No reproduction provided. A minimal repro would help diagnose this issue.

🔍 Analysis

Decorator argument values are retained as raw JSON/BinaryData rather than traversed by the shared TypeSpecReferenceResolver. Consequently, reference identities nested there are not registered before ordinary code-model deserialization encounters references to them. The affected component is the C# code-model deserialization/reference-preservation path; searches found no existing issue describing this same failure mode.

📝 Suggested next steps

• Add a focused deserialization test with an $id under a decorator argument and a later $ref in the model collection.
• Ensure opaque decorator payloads register or normalize reference metadata without losing their original content.
• Verify references resolve regardless of whether the first object occurrence is in decorator metadata or the main graph.

Generated by Agentic Triage