Validate Dev Proxy Sample

This skill guides validation of Dev Proxy samples to catch common mistakes before submission. Run through these checks to ensure the sample meets repository standards.

⚠️ MANDATORY: You MUST run jsonck to validate all JSON files against their schemas. Do NOT skip this step or rely on VS Code's JSON validation alone — it misses errors that Dev Proxy will catch at runtime. Install jsonck first: npm install -g jsonck

Quick Validation Command

jsonck reads the $schema property from JSON files automatically, downloads remote schemas, and validates in one step — no temp files or manual schema wrangling needed.

# Validate all standalone config files at once
sample="samples/{sample-name}"
jsonck "$sample"/.devproxy/*.json

For structured output (useful in CI or scripts), add --json:

jsonck "$sample"/.devproxy/*.json --json

Note: Install jsonck first with npm install -g jsonck. Requires Node.js >= 20.

Validating Plugin Config Sections

Dev Proxy configs have embedded plugin config sections with their own $schema. Extract each section with jq and pipe to jsonck — it picks up the $schema from the piped JSON automatically:

sample="samples/{sample-name}"
f="$sample/.devproxy/devproxyrc.json"

# Find all config sections that have a $schema and validate each
jq -r '[keys[] as $k | select((.[$k] | type) == "object" and (.[$k]["$schema"] // null) != null) | $k] | .[]' "$f" | while read -r section; do
  echo "Validating $section..."
  jq ".\"$section\"" "$f" | jsonck - || echo "❌ FAILED: $section"
done

Validation Checklist

1. Directory Structure

Verify required files exist:

samples/{sample-name}/
├── .devproxy/
│   ├── devproxyrc.json                  ✓
│   └── [mocks.json, errors.json, etc.]  (if needed)
├── README.md                            ✓
└── assets/
    └── sample.json                      ✓

Important: All Dev Proxy config files go in .devproxy/ folder.

2. Schema Validation

Check: Every Dev Proxy config file has a $schema defined.

Required schemas:

• •Main config file (devproxyrc.json) must have $schema
• •Each plugin config section must have its own $schema
• •Standalone data files (mocks, errors) must have $schema

Exception: CRUD API data files don't require schemas.

Example of proper schema coverage:

{
  "$schema": ".../rc.schema.json",           // ✓ Main config schema
  "plugins": [...],
  "mockResponsePlugin": {
    "$schema": ".../mockresponseplugin.schema.json",  // ✓ Plugin config schema
    "mocksFile": "mocks.json"
  }
}

Check: All $schema URLs validate against their schemas. Run jsonck on all files and plugin config sections.

Common issues:

• •Missing $schema on main config file
• •Missing $schema on plugin config sections
• •Wrong schema version (use MCP to get current)
• •Wrong schema type:
  • •mockresponseplugin.schema.json = plugin config (needs mocksFile)
  • •mockresponseplugin.mocksfile.schema.json = mock data (needs mocks array)
• •body: null not allowed (use body: "")
• •Missing required fields

3. Metadata Validation (assets/sample.json)

4. PRESET Metadata

Check: Is PRESET value correct?

• •"Yes" = Sample is reusable for other APIs (generic config)
• •"No" = Sample is specific to a particular API or scenario

Common mistake: Setting PRESET to "Yes" just because it has a config file. Most samples should be "No".

5. README Validation

6. Startup Command Validation

Check: Is the startup command correct?

Default config locations (just use devproxy):

• •devproxyrc.json
• •devproxyrc.jsonc
• •.devproxy/devproxyrc.json
• •.devproxy/devproxyrc.jsonc

Custom config (use devproxy --config-file custom.json):

• •Any other filename or location

Common mistake: Using devproxy --config-file devproxyrc.json — unnecessary!

7. Date Consistency

Check: Dates match between files.

Both should represent the same date.

8. curl Command Validation

Check: All curl commands route through Dev Proxy.

Correct:

curl -ikx http://127.0.0.1:8000 https://api.example.com/endpoint

Incorrect:

curl https://api.example.com/endpoint  # Bypasses Dev Proxy!

Flags explained:

• •-i = Include response headers
• •-k = Allow insecure (for SSL issues)
• •-x http://127.0.0.1:8000 = Route through proxy

9. Demo App vs curl

Check: For scenarios requiring multiple requests, is there a demo app?

Use demo app when:

• •Rate limiting (needs many requests)
• •Retry logic testing
• •Throttling scenarios
• •Any behavior requiring loops

Acceptable curl when:

• •Single request/response
• •Quick verification

10. URL Domain Validation

Check: Do URLs use proxy-friendly domains?

Avoid these TLDs — they're often excluded from system proxy settings:

• •.local — Reserved for mDNS/Bonjour, typically bypasses proxy
• •.localhost — Loopback, excluded by most systems
• •.internal — Often excluded in enterprise environments
• •.test — Reserved TLD, may have issues

Use instead:

• •.contoso.com — Microsoft's example domain (safe, won't resolve)
• •.example.com — IANA reserved for documentation
• •.fabrikam.com — Another Microsoft example domain
• •Real API domains you're mocking

Why this matters: When browsers/apps detect .local domains, they often skip the proxy entirely, making Dev Proxy unable to intercept requests.

Check in files:

• •urlsToWatch in devproxyrc.json
• •baseUrl in CRUD API files
• •API URLs in frontend code (JavaScript, HTML)
• •Mock response URLs

Common Mistakes Summary

Validation Script

Run this to check common issues:

sample="samples/{sample-name}"

# Check required files
echo "=== Required Files ==="
[ -d "$sample/.devproxy" ] && echo "✓ .devproxy/" || echo "✗ .devproxy/ folder missing"
[ -f "$sample/.devproxy/devproxyrc.json" ] && echo "✓ .devproxy/devproxyrc.json" || echo "✗ .devproxy/devproxyrc.json missing"
[ -f "$sample/README.md" ] && echo "✓ README.md" || echo "✗ README.md missing"
[ -f "$sample/assets/sample.json" ] && echo "✓ assets/sample.json" || echo "✗ assets/sample.json missing"

# Check metadata name matches folder
echo -e "\n=== Metadata Check ==="
folder=$(basename "$sample")
name=$(grep -o '"name": "[^"]*"' "$sample/assets/sample.json" | head -1 | cut -d'"' -f4)
expected="pnp-devproxy-$folder"
[ "$name" = "$expected" ] && echo "✓ name matches folder" || echo "✗ name '$name' should be '$expected'"

# Check date format
echo -e "\n=== Date Format ==="
grep -E '"(creation|update)DateTime"' "$sample/assets/sample.json" | grep -qE '[0-9]{4}-[0-9]{2}-[0-9]{2}' && echo "✓ Date format OK" || echo "✗ Check date format"

# Check shortDescription equals longDescription
echo -e "\n=== Description Match ==="
short=$(grep '"shortDescription"' "$sample/assets/sample.json" | cut -d'"' -f4)
long=$(grep -A1 '"longDescription"' "$sample/assets/sample.json" | tail -1 | tr -d '[]"' | xargs)
[ "$short" = "$long" ] && echo "✓ Descriptions match" || echo "✗ shortDescription ≠ longDescription[0]"

# Check tracking pixel
echo -e "\n=== Tracking Pixel ==="
grep -q "m365-visitor-stats.azurewebsites.net/SamplesGallery/pnp-devproxy-$folder" "$sample/README.md" && echo "✓ Tracking pixel OK" || echo "✗ Missing/wrong tracking pixel"

# Check badge URL uses aka.ms
echo -e "\n=== Badge URL ==="
grep -q "https://aka.ms/devproxy/badge/" "$sample/README.md" && echo "✓ Badge uses aka.ms" || echo "✗ Badge should use https://aka.ms/devproxy/badge/vX.X.X"

Pre-Submission Final Check

Before creating a PR:

1. • Run jsonck validation on ALL JSON files (mandatory — don't skip!)
2. • Dev Proxy config files are in .devproxy/ folder
3. • All JSON files pass schema validation
4. • Metadata name = pnp-devproxy-{folder-name}
5. • Descriptions match (short = long[0])
6. • Dates are in correct format and match
7. • PRESET is correct (usually "No")
8. • Startup command is correct
9. • curl commands include proxy flag
10. • README has tracking pixel
11. • Badge uses https://aka.ms/devproxy/badge/vX.X.X
12. • Badge version matches PROXY VERSION
13. • URLs don't use .local or other excluded TLDs
14. • VS Code shows no Problems