Spec Ingestion

Overview

This skill describes how to ingest the latest OpenAI TypeSpec specification (from the upstream microsoft/openai-openapi-pr repository) into the openai-dotnet SDK, area by area.

The process involves:

1. Copying updated base specs from upstream
2. Reporting any compile errors in the base TSP
3. Fixing compile errors in the client TSP layer
4. Preserving custom C# code (renames, stubs)
5. Running code generation
6. Verifying the output

Skill Documents

This skill is split across multiple files for easier navigation:

Document	Description
steps.md	Step-by-step process — the full 9-step workflow from copying spec to post-generation verification
file-locations.md	Key file locations — quick reference for all upstream and local paths, area mappings
patterns-and-gotchas.md	Common patterns & gotchas — lessons learned, pitfalls, and conventions to follow
checklist.md	Checklist — a task-by-task checklist for tracking progress during an ingestion
references.md	Reference PRs — detailed notes on past ingestion PRs with lessons learned

Quick Start

1. Review references.md for examples of past ingestions in your area
2. Read file-locations.md to understand the repo layout
3. Follow steps.md for the full ingestion workflow
4. Use checklist.md to track your progress
5. Consult patterns-and-gotchas.md when you hit issues

Available Areas

Areas that can be ingested independently:

administration · assistants · audio · batch · chat · containers · conversations · embeddings · evals · files · fine-tuning · graders · images · models · moderations · realtime · responses · runs · threads · vector-stores · videos

Key Rules

1. Always add @@clientLocation for every operation in the client TSP (the latest spec no longer uses interface blocks)
2. Update [CodeGenType] stubs in src/Custom/{Area}/Internal/GeneratorStubs.cs for any renamed types
3. Defer complex features — suggest them as follow-up items rather than implementing in the same ingestion
4. Run ./scripts/Invoke-CodeGen.ps1 to generate code (warnings are OK. Errors are not), then dotnet build to verify (Should be no warnings or errors)
5. Work locally only — do NOT create PRs or file issues. Instead, suggest a list of issues that may need to be filed upstream