Upgrade Dev Proxy Sample

This skill guides upgrading existing Dev Proxy samples to a new version, ensuring all schemas, metadata, and documentation are properly updated.

Before Starting

Use Dev Proxy MCP tools to:

• •Get the current/target schema version
• •Check for any breaking changes in schemas
• •Understand new requirements

Files to Update

Every upgrade must update these locations:

1. •All config JSON files - Schema URLs
2. •assets/sample.json - PROXY VERSION and updateDateTime
3. •README.md - Badge and version history table

Step 1: Update Configuration Files

Find All Config Files

Dev Proxy config files are in .devproxy/ folder:

grep -r "dev-proxy/main/schemas" samples/{sample-name}/.devproxy/ --include="*.json"

Update Schema URLs

Change version in $schema URLs:

Before:

{
  "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v1.0.0/rc.schema.json"
}

After:

{
  "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v2.0.0/rc.schema.json"
}

Schema Types to Update

Different files use different schemas:

• •devproxyrc.json → rc.schema.json
• •Mock response files → mockresponseplugin.mocksfile.schema.json
• •Error files → genericrandomerrorplugin.errorsfile.schema.json
• •Plugin configs → {pluginname}.schema.json

Important: Match schema type to file purpose:

• •.schema.json = plugin configuration (has mocksFile, errorsFile properties)
• •.mocksfile.schema.json = actual mock data (has mocks array)
• •.errorsfile.schema.json = actual error data (has errors array)

Don't Forget Plugin Config Sections

Dev Proxy configs often have embedded plugin config sections with their own $schema:

{
  "$schema": ".../rc.schema.json",
  "plugins": [...],
  "languageModelFailurePlugin": {
    "$schema": ".../languagemodelfailureplugin.schema.json",  // ← Update this too!
    "failures": [...]
  }
}

Update ALL $schema URLs in the file, not just the top-level one.

Step 2: Update Metadata (assets/sample.json)

Update two fields:

{
  "metadata": [
    { "key": "PROXY VERSION", "value": "v2.0.0" }
  ],
  "updateDateTime": "2026-01-18"
}

Rules:

• •Date format: YYYY-MM-DD (not ISO timestamp)
• •Preserve all other formatting (use sed for surgical changes)
• •For pre-release samples (not yet merged), also update creationDateTime

Step 3: Update README.md

Update Compatibility Badge

Before:

![Dev Proxy v1.0.0](https://aka.ms/devproxy/badge/v1.0.0)

After:

![Dev Proxy v2.0.0](https://aka.ms/devproxy/badge/v2.0.0)

Update Version History Table

For samples already in main (add new version):

Version|Date|Comments
-------|----|--------
1.1|January 18, 2026|Updated to Dev Proxy v2.0.0
1.0|December 15, 2025|Initial release

For pre-release samples (update v1.0 date):

Version|Date|Comments
-------|----|--------
1.0|January 18, 2026|Initial release

Step 4: Validate Changes

Use the validate-devproxy-sample skill to verify:

• •All $schema URLs are valid
• •Plugin config sections have schemas
• •No schema validation errors
• •Dates are consistent

Batch Upgrade Multiple Samples

To upgrade all samples to a new version:

# Find all files with old schema version (in .devproxy folders)
grep -rl "schemas/v1.0.0" samples/*/.devproxy/ --include="*.json"

# Update schemas (example with sed)
find samples/*/.devproxy -name "*.json" -exec grep -l "schemas/v1.0.0" {} \; | \
  xargs sed -i '' 's|schemas/v1.0.0|schemas/v2.0.0|g'

Then manually update each sample's:

• •assets/sample.json dates and version
• •README.md badge and version history

Checklist

For each sample being upgraded:

• • All $schema URLs updated (including plugin config sections)
• • PROXY VERSION updated in assets/sample.json
• • updateDateTime updated (YYYY-MM-DD format)
• • README badge updated
• • Version history entry added/updated
• • Run validate-devproxy-sample skill to verify

Quick Reference

Schema URL Pattern

https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/{version}/{schema-file}

Common Schema Files