API Contracts

AI-ready schemas from your .NET assemblies — built for agents, tooling, and documentation.

Why API Contracts?

Deterministic Hashing

Every build produces the same schema for the same API surface. Detect changes instantly via apiHash (SHA-256) — no more silent breaking changes.

AI-Ready Metadata

All public types are captured automatically with their XML documentation, JSON contracts, and full type signatures. LLMs and agents consume data files natively.

Cryptographic Signatures

Optional RSA-SHA256 signatures ensure schema integrity and provenance. Verify that schemas haven’t been tampered with.

Zero Runtime Cost

Powered by a Roslyn incremental source generator — all schema work happens at compile time. No reflection, no runtime overhead.

How it works

Install the source generator NuGet package

1
<PackageReference Include="ApiContracts.Generator"
2
                  OutputItemType="Analyzer"
3
                  ReferenceOutputAssembly="false" />

Annotate your types (optional — all public types are captured automatically)

1
// All public types are included implicitly.
2
// Use [ApiContract(Ignore = true)] to exclude a type:
3
[ApiContract(Ignore = true)]
4
public class InternalHelper { }

Build — the generator walks all public types, extracts XML docs, models JSON serialization, and emits deterministic data files
Terminal window
```
dotnet build
```

Consume the schema in documentation, AI agents, or tooling

1
var result = SchemaVerifier.ValidateSchema(schemaJson);
2
Console.WriteLine($"Valid: {result.IsValid}, Hash: {result.ApiHash}");

What gets captured?

Every public class, struct, record, interface, enum, and delegate — including all public members with full signatures, parameters, return types, and modifiers.

1
{
2
  "name": "Customer",
3
  "fullName": "SampleApi.Customer",
4
  "kind": "class",
5
  "members": [
6
    {
7
      "name": "FullName",
8
      "kind": "property",
9
      "returnType": "string",
10
      "signature": "string Customer.FullName"
11
    }
12
  ]
13
}

All XML documentation is normalized and captured: summaries, remarks, parameter descriptions, return docs, <example> blocks, and <seealso> references.

1
{
2
  "docs": {
3
    "summary": "Service for managing customers.",
4
    "remarks": "Provides CRUD operations and search capabilities.",
5
    "parameters": {
6
      "id": "The customer identifier."
7
    },
8
    "returns": "The customer if found; otherwise, null."
9
  }
10
}

System.Text.Json serialization behavior is captured per type — property names, types, required/nullable/ignored flags, and JSON type mappings.

1
{
2
  "json": {
3
    "contractType": "object",
4
    "useCamelCase": true,
5
    "properties": [
6
      {
7
        "clrName": "FullName",
8
        "jsonName": "fullName",
9
        "jsonType": "string",
10
        "required": true
11
      }
12
    ]
13
  }
14
}

Explore further

Quick Start Guide Get up and running in under 5 minutes.

Sample Schema See a real-world schema generated from the SampleApi project.

Schema Format Understand the assembly schema structure in detail.

Configuration Customize output paths, signing, and which types are included.