mottobits.
DotNetGuides / Engineering brief

C#

Give your AI a contract, not just a JSON sample

Generate the first draft of your C# models. Then make the assumptions explicit before an AI turns them into application code.

2026-09-29DotNetGuides archive

A sample proves that a value appeared once. It cannot prove a field is required, an array is homogeneous, or an integer will stay small.

Start with a deliberately conservative model

Paste a representative response into JSON → C# models. The tool keeps JSON names with JsonPropertyName attributes and makes inferred properties nullable. That is a starting point for review, not a claim about the API's schema.

Collect examples for the successful response, an empty collection, a missing optional field, and an explicit null. If the API publishes an OpenAPI document or JSON Schema, use that as stronger evidence than a single response.

Ask the questions that change the code

  • Can this property be missing, null, or both? What should each case mean?
  • Is this number an identifier, count, measured value, or money? Does its range require long, decimal, or a string?
  • Is the timestamp guaranteed to include an offset? Keep it as a string until its format and semantics are known.
  • Can an array contain different shapes? Do not invent an inheritance hierarchy from one example.

Give the assistant acceptance criteria

A useful AI request asks for evidence and tests. It does not simply ask to make the generated classes more idiomatic. Include your real target runtime and serializer settings.

Review these transport models against the API contract.
List every assumption about required fields, nulls,
numeric precision, dates, and polymorphism.

Then add tests for:
1. The representative payload
2. Missing optional properties
3. Explicit null values
4. Unexpected enum or discriminator values

Do not change the public JSON field names.

Check the runtime behavior

C# nullable annotations and JSON property presence are different concerns. System.Text.Json exposes options for enforcing parts of these contracts, but missing members and explicit nulls need separate attention. Read the behavior for your runtime before enabling stricter deserialization.

Keep transport models at the boundary. Map them into application types where business invariants can be validated explicitly. A generated DTO should not silently become your domain model.

Sources