feat(codegen): support non-conforming OpenAPI property keys in generated models

[davidkallesen]

Summary

Generated models normalize OpenAPI property keys to PascalCase C# names. When the original key
does not round-trip through the default camelCase naming policy, System.Text.Json binding
silently breaks — properties deserialize as null with no error at compile time or runtime.

This affects any spec using underscores, dots or custom acronym casing in property keys. The
Eloverblik API in sample/ThridParty-Typed-Clients/EloverblikThirdPartyApiClient is a
real-world example:

OpenAPI key	Generated name	Bound before
MyEnergyData_MarketDocument	MyEnergyDataMarketDocument	❌
sender_MarketParticipant.name	SenderMarketParticipantName	❌
sender_MarketParticipant.mRID	SenderMarketParticipantMRid	❌
period.timeInterval	PeriodTimeInterval	❌
measurement_Unit.name	MeasurementUnitName	❌
out_Quantity.quantity	OutQuantityQuantity	❌
mRID	MRid	❌
createdDateTime	CreatedDateTime	✅

The fix emits [property: JsonPropertyName("<original key>")] whenever the original key does not
match the default convention, leaving conforming keys untouched so existing output is unchanged.

Changes

Detection — new JsonPropertyNameHelper decides whether a property needs an explicit
attribute: false on an exact ordinal match or when the key equals the camelCased property name,
true otherwise.

Emission — wired into all five record extraction paths: ExtractGenericPaginatedRecord,
ExtractRecordFromSchema and ExtractRecordFromSchemaWithInlineEnums in SchemaExtractor, plus
both entry points in InlineSchemaExtractor via a shared BuildAttributes helper. The
JsonPropertyName attribute is placed first so validation attributes append cleanly.

Using directives — resolved independently by the two generation paths, so both needed
updating:

• Source-generator path: SchemaExtractor.BuildHeaderContent
• CLI / file-based path: CodeGenerationService.GenerateModels via a new
  UsingStatementHelper.RecordUsesJsonPropertyName

The second was a genuine latent bug — CLI-generated models referenced JsonPropertyName without
importing it and failed to compile. It was only surfaced by writing the integration test.

Example output

public sealed record MyEnergyDataMarketDocument(
    [property: JsonPropertyName("mRID")] string? MRid,
    string? CreatedDateTime,
    [property: JsonPropertyName("sender_MarketParticipant.name")] string? SenderMarketParticipantName,
    [property: JsonPropertyName("sender_MarketParticipant.mRID")] EIC SenderMarketParticipantMRid,
    [property: JsonPropertyName("period.timeInterval")] PeriodtimeInterval PeriodTimeInterval,
    List<TimeSeries>? TimeSeries);

Testing

Layer	Coverage
JsonPropertyNameHelperTests	Naming rules: exact match, camelCase equivalence, underscore/dot keys, leading-lowercase acronyms, null/empty guards
GenerateContentForRecordsTests	Atc.CodeGeneration.CSharp renders property-targeted attributes, alone and combined with validation attributes
SchemaExtractorJsonPropertyNameTests, InlineSchemaExtractorTests	Attribute emission and ordering across every extraction path
JsonPropertyNameGenerationTests	End-to-end CodeGenerationService.GenerateModels output, including RequiredUsings
RecordSerializationTests	The generated contract actually serializes and deserializes
MeterDataGetTimeSeriesPayloadTests	Real production payload regression guard

The last one is the strongest guard. It uses an actual response body from
POST /thirdpartyapi/api/meterdata/gettimeseries/{dateFrom}/{dateTo}/{aggregation} — a five-level
object graph with 96 quarter-hour data points. GeneratedModels_CanMapEveryPropertyKeyInRealPayload
runs SchemaExtractor over the real api-1.yaml, derives the set of bindable keys from the emitted
attributes, recursively collects every key in the payload and asserts none are left unmapped. This
ties the fixture directly to generator output rather than to hand-written mirrors, so it will fail
if the generator ever regresses.

Full suite green. Sample EloverblikThirdPartyApiClient builds with 0 warnings and emits the
expected attributes.

Backwards compatibility

No change for specs whose property keys already follow camelCase or PascalCase conventions — the
helper returns false and no attribute is emitted. Specs that previously produced silently broken
models will now produce correct ones, changing generated output but only where it was already wrong.

Commits

Commit	Scope
17ccdf95	feat(codegen): add JsonPropertyNameHelper
3ebf9036	feat(codegen): emit the attribute across extraction paths
a00319d6	fix(codegen): System.Text.Json.Serialization using on the file-based path
86c541f2	test(codegen): round-trip verification
e40dfbec	test(codegen): real Eloverblik payload guard