[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6BTDRCG0SXKPKCFWR75FY8T":3,"skill-same:01M6BTDRCG0SXKPKCFWR75FY8T":86},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":23,"publishedAt":52,"linkOnly":53,"markdownContent":54,"markdownBody":55,"frontMatter":56,"refName":57,"commitSha":58,"skillDirectory":59,"forksCount":60,"repositoryHtmlUrl":61,"repositoryHomepageUrl":6,"ownerHtmlUrl":62,"ownerBlogUrl":63,"ownerDescription":64,"updatedAt":65,"install":66,"resources":79},"01M6BTDRCG0SXKPKCFWR75FY8T","search-documents-typespec-validation",null,"TypeSpec validation skill for Azure.Search.Documents SDK. Performs a COMPLETE validation of ALL operations, ALL models, ALL enums, and ALL properties against the TypeSpec definition at any pinned commit. Works for any API version. Generates a full gap report: missing features, extra features, naming mismatches, and recommended fix location. WHEN: \"validate Azure.Search.Documents SDK against TypeSpec\", \"detect Azure.Search.Documents typespec feature gaps\", \"what is missing from the Azure.Search.Documents SDK\", \"compare Azure.Search.Documents SDK to spec\", \"full spec coverage audit for Azure.Search.Documents\". Do NOT use for version-to-version diff or regression detection — use search-documents-version-diff instead.","Azure\u002Fazure-sdk-for-net","Azure","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F6844498?v=4","01M6BT15ZBDTV4D9RM7HCC4D8A","Microsoft Azure","01M6BT163EEHB7Y52MKZJ322Q8",6072,"MIT","https:\u002F\u002Fgithub.com\u002FAzure\u002Fazure-sdk-for-net\u002Fblob\u002Fmain\u002Fsdk\u002Fsearch\u002FAzure.Search.Documents\u002F.github\u002Fskills\u002Fsearch-documents-typespec-validation\u002FSKILL.md",[18],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发","SCENARIO","使用场景",[24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51],"typespec","search documents","search documents typespec validation","search","validation","documents","at","full","api","do","features","api version","fix","coverage","extra","definition","when","regression","spec","detection","audit","report","azure","gap report","validate","commit","to spec","sdk","2026-11-10 10:12:30",false,"---\nname: search-documents-typespec-validation\ndescription: 'TypeSpec validation skill for Azure.Search.Documents SDK. Performs a COMPLETE validation of ALL operations, ALL models, ALL enums, and ALL properties against the TypeSpec definition at any pinned commit. Works for any API version. Generates a full gap report: missing features, extra features, naming mismatches, and recommended fix location. WHEN: \"validate Azure.Search.Documents SDK against TypeSpec\", \"detect Azure.Search.Documents typespec feature gaps\", \"what is missing from the Azure.Search.Documents SDK\", \"compare Azure.Search.Documents SDK to spec\", \"full spec coverage audit for Azure.Search.Documents\". Do NOT use for version-to-version diff or regression detection — use search-documents-version-diff instead.'\n---\n\n# Azure.Search.Documents — TypeSpec Validation Skill\n\n| Property | Value |\n|---|---|\n| Package | `Azure.Search.Documents` |\n| Root | `sdk\u002Fsearch\u002FAzure.Search.Documents\u002F` |\n| TypeSpec repo | `Azure\u002Fazure-rest-api-specs` |\n| TypeSpec path | `specification\u002Fsearch\u002Fdata-plane\u002FSearch` |\n| Pin file | `tsp-location.yaml` (contains commit SHA) |\n\n**Related skills:**\n- [search-documents](..\u002Fsearch-documents\u002FSKILL.md) — E2E workflow skill for full release cycles, spec updates, code changes, and customizations\n- [search-documents-version-diff](..\u002Fsearch-documents-version-diff\u002FSKILL.md) — diff public API surface between two versions to catch regressions\n\nFor TypeSpec decorator details and C# customization patterns referenced in this validation, see:\n- [customization.md](..\u002Fsearch-documents\u002Freferences\u002Fcustomization.md) — `@@clientName`, `@@access`, `[CodeGenMember]`, compound property wiring\n- [architecture.md](..\u002Fsearch-documents\u002Freferences\u002Farchitecture.md) — source layout, SearchOptions architecture, service version management\n\n---\n\n## Purpose\n\nPerform a **complete, exhaustive** comparison of the SDK's public API surface against the TypeSpec definition to produce a structured gap analysis report. The TypeSpec (main spec files + `client.tsp` overrides) is the **source of truth** for what the SDK should expose.\n\nThis skill validates:\n- **Every operation** on every client\n- **Every model** (class, struct, enum, union) and its properties\n- **Every enum\u002Funion value** to detect missing or extra members\n- **Every generated file** against the public API listing to ensure nothing is silently dropped or incorrectly internalized\n\nThe validation is **version-aware**: it reads the commit SHA from `tsp-location.yaml` and uses the TypeSpec `@added`\u002F`@removed` versioning decorators to determine which features should exist for the SDK's current target API version(s).\n\n---\n\n## Inputs\n\n| Input | Source | Required |\n|---|---|---|\n| TypeSpec commit SHA | `tsp-location.yaml` → `commit` field | Yes (auto-read) |\n| TypeSpec directory | `tsp-location.yaml` → `directory` field | Yes (auto-read) |\n| SDK public API listing | `api\u002FAzure.Search.Documents.netstandard2.0.cs` (preferred; fallback: `net10.0.cs`) | Yes (local file) |\n| Generated code | `src\u002FGenerated\u002F` directory (all `.cs` files) | Yes (local) |\n| Generated models | `src\u002FGenerated\u002FModels\u002F` directory (all `.cs` files) | Yes (local) |\n| Custom code | `src\u002F` (non-Generated files) | Yes (local) |\n| client.tsp | Fetched from azure-rest-api-specs at pinned SHA | Yes (remote) |\n| All TypeSpec model files | Fetched from azure-rest-api-specs routes\u002F and models\u002F dirs | Yes (remote) |\n\n---\n\n## Workflow\n\n### Step 1 — Gather Sources\n\n1. Read `tsp-location.yaml` to get the commit SHA and TypeSpec directory path.\n2. Determine the SDK's target API version(s) by reading `SearchClientOptions.ServiceVersion` enum from the API listing. The **latest** version is the one being validated.\n3. Fetch the TypeSpec files from GitHub at the pinned SHA:\n   - Entry point: `https:\u002F\u002Fraw.githubusercontent.com\u002FAzure\u002Fazure-rest-api-specs\u002F{SHA}\u002F{directory}\u002Fmain.tsp`\n   - Client customizations: `https:\u002F\u002Fraw.githubusercontent.com\u002FAzure\u002Fazure-rest-api-specs\u002F{SHA}\u002F{directory}\u002Fclient.tsp`\n   - Config: `https:\u002F\u002Fraw.githubusercontent.com\u002FAzure\u002Fazure-rest-api-specs\u002F{SHA}\u002F{directory}\u002Ftspconfig.yaml`\n   - **All route files**: Follow imports from `main.tsp` (e.g., `routes-service.tsp`, `routes-index.tsp`, `routes-knowledgebase.tsp`, etc.)\n   - **All model files**: Fetch everything in the `models\u002F` subdirectory if present, or follow imports\n4. Read the local SDK API listing: prefer `api\u002FAzure.Search.Documents.netstandard2.0.cs` (most inclusive); fall back to `api\u002FAzure.Search.Documents.net10.0.cs`\n5. List ALL files in `src\u002FGenerated\u002FModels\u002F` — this is the authoritative set of generated types\n6. Read custom partial classes: scan `src\u002F` for non-Generated `.cs` files\n\n**IMPORTANT**: Do NOT skip any TypeSpec files. The validation must cover the ENTIRE spec surface.\n\n### Step 2 — Extract TypeSpec Surface\n\nFrom the TypeSpec files, extract **ALL** of the following (no sampling, no shortcuts):\n\n1. **API Versions** — all `enum Versions { ... }` members. Identify which version is being added by this commit (compare to SDK's `ServiceVersion` enum to find the new one).\n2. **Operations** — all `op` declarations grouped by interface\u002Fnamespace (these become client methods). Note `@added(Versions.vXXX)` decorators.\n3. **Models** — ALL `model` declarations across ALL TypeSpec files (these become C# classes\u002Fstructs). For EACH model, record:\n   - Name\n   - Base type (if `extends` or `is`)\n   - All properties with types and optionality\n   - `@discriminator` if present\n   - `@added`\u002F`@removed` version annotations\n4. **Enums** — ALL `enum` declarations with all member values\n5. **Unions** — ALL `union` declarations (these become extensible structs in C#) with all member values\n6. **Discriminator hierarchies** — `@discriminator` decorators that create polymorphic type trees\n7. **Versioning** — `@added(Versions.vXXX)` and `@removed(Versions.vXXX)` decorators on types, properties, and operations. A feature is expected in the SDK if it was `@added` in any version ≤ the SDK's latest version and not `@removed`.\n8. **Routes** - ALL route declarations (e.g., `@route(\"\u002Findexes\")`) to verify correct client method placement and exposure. Ensure that new routes are exposed in the client.tsp and SDK as neeeded.\n\nFrom `client.tsp`, extract **ALL** overrides:\n\n1. **Renames** — every `@@clientName` augment (TypeSpec name → SDK name mapping)\n2. **Access changes** — every `@@access(\"internal\")` (types\u002Fmethods hidden from public API)\n3. **Suppressed methods** — `@@convenientAPI(op, false)` or `@@protocolAPI(op, false)`\n4. **Usage overrides** — `@@usage` forcing input\u002Foutput direction\n5. **Client restructuring** — `@client`, `@operationGroup`, `@@clientLocation`\n6. **Alternate types** — `@@alternateType` changing property types in the SDK\n7. **Client namespace** — `@@clientNamespace` moving types to different namespaces\n\n### Step 3 — Extract SDK Surface\n\nFrom the API listing file (`api\u002F*.cs`), extract:\n\n1. **Public types** — all `public partial class`, `public partial struct`, `public enum`, `public static class`, `public abstract partial class`\n2. **Public methods** — on ALL client types (search for classes ending in `Client`)\n3. **Public properties** — on ALL model types\n4. **Enum\u002Fstruct members** — all `public static` properties on extensible structs (union-derived types)\n5. **Factory methods** — on `SearchModelFactory`\n\nFrom the generated models directory (`src\u002FGenerated\u002FModels\u002F`), extract:\n\n6. **All generated files** — list every `.cs` file (excluding `.Serialization.cs`)\n7. **Access modifier of each generated type** — check if each is `public` or `internal`\n8. **Cross-reference**: every generated public type MUST appear in the API listing. If it doesn't, flag it.\n9. **Cross-reference**: every generated internal type must be explainable by a `client.tsp` `@@access(\"internal\")` override or by being a discriminator kind type.\n\nFrom custom code, note:\n\n10. **`[CodeGenSuppress]`** attributes — members actively hidden\n11. **`[CodeGenType]`** attributes — type name remappings\n12. **`[CodeGenMember]`** attributes — property name remappings\n13. **Hand-written types** — classes that exist only in custom code (e.g., `FieldBuilder`, `SearchFilter`, `SearchDocument`)\n\n### Step 3b — Exhaustive Generated Model Verification\n\nThis sub-step ensures NO model was silently dropped or incorrectly marked:\n\n1. For **every** file in `src\u002FGenerated\u002FModels\u002F*.cs` (excluding `*.Serialization.cs`):\n   - Read the type declaration line to get the type name and access modifier (`public` vs `internal`)\n   - If `public`: verify it appears in the API listing file\n   - If `internal`: verify there is a corresponding `@@access(\"internal\")` or `@@clientName` rename to `Internal*` in `client.tsp`, OR it is a discriminator kind type (naming pattern: `*Kind`, `*Type` used internally for polymorphism)\n2. Count totals: `{N} public, {M} internal, {0} unexplained`\n3. Any type that is public in generated code but missing from the API listing is a **CRITICAL** gap.\n4. Any type that is internal in generated code but has no explanation from `client.tsp` is a **WARNING** (may be intentional but needs verification).\n\n### Step 4 — Compare and Classify\n\n**This step MUST be exhaustive.** Do not sample or skip types. Every TypeSpec element must be accounted for.\n\n#### 4a — Version Filtering\n\nFirst, determine which API version is the SDK's **latest** (the default in `SearchClientOptions.ServiceVersion`). Then for each TypeSpec element:\n- If it has `@added(Versions.vX)` where `vX` ≤ latest SDK version → **expected in SDK**\n- If it has `@removed(Versions.vX)` where `vX` ≤ latest SDK version → **should NOT be in SDK**\n- If it has no version annotation → **expected in all versions**\n\n#### 4b — Operation Validation\n\nFor each TypeSpec operation, determine its expected SDK representation:\n\n| TypeSpec element | Expected in SDK as |\n|---|---|\n| `op doSomething(...)` on interface X | Method `DoSomething`\u002F`DoSomethingAsync` on client X |\n| `op` with `@@access(\"internal\")` in client.tsp | Should NOT appear in public API |\n| `op` with `@@convenientAPI(op, false)` | No convenience method (only protocol method if `@@protocolAPI` not also false) |\n\nVerify ALL operations on ALL clients.\n\n#### 4c — Model Validation (EXHAUSTIVE)\n\nFor **every** model in the TypeSpec:\n\n1. Determine its expected C# name (apply `@@clientName` if present)\n2. Determine its expected access (apply `@@access` if present)\n3. If expected public: verify it exists in the API listing with the correct name\n4. If expected internal: verify it does NOT appear in the public API listing\n5. For EACH property on the model:\n   - Determine expected C# name (PascalCase, or `@@clientName` override)\n   - Determine expected type (apply `@@alternateType` if present)\n   - Verify it exists on the SDK type with correct name and compatible type\n   - Check optionality: `?` in TypeSpec → nullable in SDK\n\n#### 4d — Enum\u002FUnion Validation (EXHAUSTIVE)\n\nFor **every** enum and union:\n\n1. Determine expected C# type:\n   - `enum` → C# `enum` or extensible struct (depends on usage)\n   - `union` with string base → extensible struct with `public static` members\n2. Verify all members\u002Fvalues are present in the SDK\n3. Flag any SDK values that don't exist in TypeSpec (could be backward-compat additions)\n\n#### 4e — Discriminator Hierarchy Validation\n\nFor each `@discriminator` in TypeSpec:\n\n1. Verify the base type exists as an abstract class in SDK\n2. Verify ALL derived types exist\n3. Verify the SDK has `Unknown*` fallback types for forward compatibility\n4. Cross-reference with `client.tsp` renames\n\n#### 4f — New Version Feature Validation\n\nFor the **specific API version being added** (the one in the TypeSpec commit that doesn't exist in the previous SDK release):\n\n1. Identify ALL types, properties, operations, and enum values annotated with `@added(Versions.vNEW)` where `vNEW` is the new version\n2. Verify EVERY one of these exists in the SDK\n3. This is the highest-priority check — these are the new features this commit introduces\n\nApply `client.tsp` transformations:\n- If `@@clientName(Foo, \"Bar\")` → expect `Bar` in SDK, not `Foo`\n- If `@@access(op, \"internal\")` → should NOT appear in public API\n- If `@@convenientAPI(op, false)` → no convenience method expected\n\n### Step 5 — Generate Report\n\nProduce a structured report with these sections:\n\n#### 5.1 — Missing Features (in TypeSpec, not in SDK)\n\nFor each missing element:\n```\n| TypeSpec Element | Expected SDK Name | Category | Recommended Fix |\n|---|---|---|---|\n| model FooBar | FooBar | Model | Regenerate or check [CodeGenSuppress] |\n| op getFoo | GetFoo\u002FGetFooAsync | Operation | Check client.tsp @@access or regenerate |\n| FooBar.bazProp | BazProp | Property | Check custom partial class |\n```\n\n**Recommended Fix** classification:\n- **Regenerate** — TypeSpec has it, generation should produce it, likely stale codegen\n- **Remove [CodeGenSuppress]** — SDK is actively suppressing it\n- **Add to client.tsp** — needs `@@usage` or `@@convenientAPI(op, true)` to generate\n- **SDK customization** — needs hand-written code (complex mapping, not 1:1)\n\n#### 5.2 — Extra Features (in SDK, not in TypeSpec)\n\nFor each extra element:\n```\n| SDK Element | Category | Source | Action Needed |\n|---|---|---|---|\n| SearchFilter | Utility class | Hand-written | None (SDK-only helper) |\n| FieldBuilder | Utility class | Hand-written | None (SDK-only helper) |\n| OldModel | Backward compat | Retained from prev GA | Verify still needed |\n```\n\n**Source** classification:\n- **Hand-written helper** — intentional SDK-only utility (no action)\n- **Backward compat retained type** — kept from a previous GA release for ApiCompat\n- **Stale customization** — was in old spec, removed from TypeSpec, should be evaluated\n- **client.tsp override** — exists due to `@@clientName` or restructuring\n\n#### 5.3 — Naming Mismatches\n\n```\n| TypeSpec Name | SDK Name | Source of Rename | Correct? |\n|---|---|---|---|\n| searchText | SearchText | Convention (PascalCase) | Yes |\n| fooBar | BazQux | client.tsp @@clientName | Verify intent |\n```\n\n#### 5.4 — Structural Differences\n\n- Operations on different clients than expected\n- Models in different namespaces\n- Properties with different types (e.g., `string` in TypeSpec vs `Uri` in SDK via customization)\n- Properties with different optionality (required in TypeSpec, optional in SDK or vice versa)\n\n#### 5.5 — Recommendations Summary\n\nPrioritized list of actions:\n1. **Critical** — public API gaps that affect functionality\n2. **Important** — naming\u002Fstructure issues that affect discoverability\n3. **Low** — cosmetic or documentation-only differences\n4. **No action** — intentional SDK-only additions or backward-compat retentions\n\nFor each recommendation, specify:\n- **Where to fix**: `client.tsp` | `src\u002F` customization | TypeSpec main spec (file a spec issue)\n- **How to fix**: specific decorator\u002Fattribute\u002Fpattern to use\n- **Risk**: breaking change? | backward compat impact?\n\n---\n\n## Fetching TypeSpec Files\n\nThe TypeSpec for this package lives in the external `Azure\u002Fazure-rest-api-specs` repo. To fetch:\n\n1. Read commit SHA from `tsp-location.yaml`\n2. Fetch `main.tsp` first — parse its `import` statements to discover all other files\n3. Fetch `client.tsp` — this contains ALL SDK-specific overrides\n4. Fetch `tspconfig.yaml` — this contains emitter options\n5. Recursively fetch ALL imported `.tsp` files (routes, models, etc.)\n6. Use raw GitHub URLs: `https:\u002F\u002Fraw.githubusercontent.com\u002FAzure\u002Fazure-rest-api-specs\u002F{SHA}\u002F{directory}\u002F{file}`\n7. The TypeSpec may import from `@azure-tools\u002Ftypespec-azure-core` and other packages — focus on the **local model and operation definitions**, not library imports.\n\n### Discovering TypeSpec Files\n\nParse `main.tsp` for lines like:\n```\nimport \".\u002Froutes-service.tsp\";\nimport \".\u002Froutes-index.tsp\";\nimport \".\u002Fmodels\u002Fcommon.tsp\";\n```\n\nEach imported file may itself import more files. Follow ALL local imports (starting with `.\u002F`). Skip package imports (starting with `@`).\n\n### Typical TypeSpec structure for this package:\n```\nspecification\u002Fsearch\u002Fdata-plane\u002FSearch\u002F\n├── main.tsp              # Entry point — defines service, API versions, imports routes\n├── client.tsp            # SDK customizations (clientName, access, usage, etc.)\n├── tspconfig.yaml        # Emitter configuration\n├── routes-*.tsp          # Operation definitions by resource area\n└── models (inline or in separate files imported by routes)\n```\n\n**Note**: The file structure may change between commits. Always discover files dynamically from `main.tsp` imports rather than assuming fixed paths.\n\n---\n\n## Handling Large TypeSpec Definitions\n\nThe Search service TypeSpec is large (400+ models, 50+ operations, 100+ enums\u002Funions). The validation MUST still be exhaustive. Use these strategies:\n\n1. **Automate the cross-reference** — use terminal commands to programmatically compare generated files against the API listing (see \"Automated Verification Commands\" below)\n2. **Fetch all TypeSpec files** — follow ALL imports from `main.tsp` recursively; fetch every `.tsp` file in the spec directory\n3. **Batch processing** — process files in batches but DO NOT skip any. Report progress: \"Checked 150\u002F400 models...\"\n4. **Focus on the new version first** — validate `@added(Versions.vNEW)` features with highest priority, then validate the full surface\n5. **Use subagents for parallel work** — delegate model validation to an Explore subagent if needed\n\n**NEVER skip types, NEVER sample, NEVER say \"and similar types follow the same pattern.\"** Every type must be individually verified.\n\n### Automated Verification Commands\n\nUse the `Validate-GeneratedModels.ps1` script to perform exhaustive cross-reference checks:\n\n```powershell\n# Full validation — cross-references all generated models against API listing\n.\u002F.github\u002Fskills\u002Fsearch-documents-typespec-validation\u002Fscripts\u002FValidate-GeneratedModels.ps1 -Format summary\n\n# Batch-check specific TypeSpec model names (after @@clientName renames) against the SDK\n.\u002F.github\u002Fskills\u002Fsearch-documents-typespec-validation\u002Fscripts\u002FValidate-GeneratedModels.ps1 -TypeNames @(\"SearchIndex\",\"SearchField\",\"SearchIndexer\")\n\n# JSON output for agent consumption\n.\u002F.github\u002Fskills\u002Fsearch-documents-typespec-validation\u002Fscripts\u002FValidate-GeneratedModels.ps1\n```\n\nThe script lives at [scripts\u002FValidate-GeneratedModels.ps1](scripts\u002FValidate-GeneratedModels.ps1). It resolves paths relative to the package root automatically.\n\n---\n\n## Known Intentional Differences\n\nThese differences are **expected** and should NOT be flagged as gaps:\n\n| SDK Element | Reason |\n|---|---|\n| `SearchDocument` (dynamic document) | SDK-only: enables `dynamic` and `Dictionary\u003Cstring,object>` patterns |\n| `FieldBuilder` | SDK-only: reflection-based field generation from C# model types |\n| `SearchFilter.Create()` | SDK-only: OData filter expression builder |\n| `SearchIndexingBufferedSender\u003CT>` | SDK-only: client-side batching with retry |\n| `SuggestOptions` \u002F `AutocompleteOptions` | May differ from raw TypeSpec due to property grouping |\n| `SemanticSearchOptions` \u002F `VectorSearchOptions` | SDK-only sub-objects that group `SearchOptions` properties |\n| Backward-compat retained types | Types from previous GA releases kept for ApiCompat |\n| `SearchModelFactory` extra methods | May have legacy overloads for backward compat |\n| Discriminator kind structs (e.g., `*Kind`, `*Type`) | Internal by design — used for polymorphic deserialization |\n| `Unknown*` types | Internal forward-compat fallback types for polymorphic hierarchies |\n| Types with `@@access(\"internal\")` in client.tsp | Intentionally hidden — verify they're internal, not missing |\n\n---\n\n## Output Format\n\nPresent the report as a markdown table-based summary. Always include:\n\n1. **Scope summary**: \"Validated against TypeSpec commit `{SHA}`, API version `{version}`, {N} total TypeSpec models, {M} operations, {K} enums\u002Funions\"\n2. **Automated cross-reference results**: \"Generated models: {X} public (all in API), {Y} internal (all explained), {Z} unexplained\"\n3. **Gap counts**: X missing, Y extra, Z mismatches\n4. **Critical items first** (blocking or high-impact gaps)\n5. **Full type listing for new version features** — every `@added(Versions.vNEW)` type\u002Foperation explicitly confirmed or flagged\n6. **Actionable recommendations** with specific file paths and patterns\n\nUse collapsible sections (`\u003Cdetails>`) for large sub-lists (>20 items), but ALWAYS report the full data — never truncate or summarize.\n\n---\n\n## Constraints\n\n- **DO NOT** modify any files during validation — this is a read-only analysis\n- **DO NOT** flag backward-compat retained types as \"extra\" without checking git tags\n- **DO NOT** flag hand-written helpers (FieldBuilder, SearchFilter, etc.) as issues\n- **DO NOT** skip any types, operations, or enums — the analysis MUST be exhaustive\n- **DO NOT** sample or summarize — report exact counts and exact names\n- **DO NOT** hardcode API version names — read them dynamically from `main.tsp` and the SDK's `ServiceVersion` enum\n- **DO** account for client.tsp transformations before flagging mismatches\n- **DO** note when a gap might be intentional (e.g., `@@access(\"internal\")`)\n- **DO** distinguish between \"missing from public API\" and \"present but internal\"\n- **DO** run the automated verification commands (Step 3b) to catch every generated model\n- **DO** verify enum\u002Funion member counts match between TypeSpec and SDK\n- **DO** explicitly confirm the new API version's `ServiceVersion` enum value exists and is set as default\n\n## Completeness Checklist\n\nBefore reporting results, confirm ALL of the following:\n\n- [ ] All TypeSpec files fetched (main.tsp + all imports + client.tsp)\n- [ ] Every generated model file cross-referenced against API listing\n- [ ] Every operation on every client verified\n- [ ] Every `@@clientName` rename verified in SDK\n- [ ] Every `@@access(\"internal\")` verified as internal in SDK\n- [ ] New API version's `ServiceVersion` value present and set as default\n- [ ] All new-version `@added` features individually verified\n- [ ] Enum\u002Funion member counts validated\n- [ ] Discriminator hierarchies validated (base + all derived + Unknown* fallback)\n- [ ] Summary counts reported: types checked, operations checked, gaps found","# Azure.Search.Documents — TypeSpec Validation Skill\n\n| Property | Value |\n|---|---|\n| Package | `Azure.Search.Documents` |\n| Root | `sdk\u002Fsearch\u002FAzure.Search.Documents\u002F` |\n| TypeSpec repo | `Azure\u002Fazure-rest-api-specs` |\n| TypeSpec path | `specification\u002Fsearch\u002Fdata-plane\u002FSearch` |\n| Pin file | `tsp-location.yaml` (contains commit SHA) |\n\n**Related skills:**\n- [search-documents](..\u002Fsearch-documents\u002FSKILL.md) — E2E workflow skill for full release cycles, spec updates, code changes, and customizations\n- [search-documents-version-diff](..\u002Fsearch-documents-version-diff\u002FSKILL.md) — diff public API surface between two versions to catch regressions\n\nFor TypeSpec decorator details and C# customization patterns referenced in this validation, see:\n- [customization.md](..\u002Fsearch-documents\u002Freferences\u002Fcustomization.md) — `@@clientName`, `@@access`, `[CodeGenMember]`, compound property wiring\n- [architecture.md](..\u002Fsearch-documents\u002Freferences\u002Farchitecture.md) — source layout, SearchOptions architecture, service version management\n\n---\n\n## Purpose\n\nPerform a **complete, exhaustive** comparison of the SDK's public API surface against the TypeSpec definition to produce a structured gap analysis report. The TypeSpec (main spec files + `client.tsp` overrides) is the **source of truth** for what the SDK should expose.\n\nThis skill validates:\n- **Every operation** on every client\n- **Every model** (class, struct, enum, union) and its properties\n- **Every enum\u002Funion value** to detect missing or extra members\n- **Every generated file** against the public API listing to ensure nothing is silently dropped or incorrectly internalized\n\nThe validation is **version-aware**: it reads the commit SHA from `tsp-location.yaml` and uses the TypeSpec `@added`\u002F`@removed` versioning decorators to determine which features should exist for the SDK's current target API version(s).\n\n---\n\n## Inputs\n\n| Input | Source | Required |\n|---|---|---|\n| TypeSpec commit SHA | `tsp-location.yaml` → `commit` field | Yes (auto-read) |\n| TypeSpec directory | `tsp-location.yaml` → `directory` field | Yes (auto-read) |\n| SDK public API listing | `api\u002FAzure.Search.Documents.netstandard2.0.cs` (preferred; fallback: `net10.0.cs`) | Yes (local file) |\n| Generated code | `src\u002FGenerated\u002F` directory (all `.cs` files) | Yes (local) |\n| Generated models | `src\u002FGenerated\u002FModels\u002F` directory (all `.cs` files) | Yes (local) |\n| Custom code | `src\u002F` (non-Generated files) | Yes (local) |\n| client.tsp | Fetched from azure-rest-api-specs at pinned SHA | Yes (remote) |\n| All TypeSpec model files | Fetched from azure-rest-api-specs routes\u002F and models\u002F dirs | Yes (remote) |\n\n---\n\n## Workflow\n\n### Step 1 — Gather Sources\n\n1. Read `tsp-location.yaml` to get the commit SHA and TypeSpec directory path.\n2. Determine the SDK's target API version(s) by reading `SearchClientOptions.ServiceVersion` enum from the API listing. The **latest** version is the one being validated.\n3. Fetch the TypeSpec files from GitHub at the pinned SHA:\n   - Entry point: `https:\u002F\u002Fraw.githubusercontent.com\u002FAzure\u002Fazure-rest-api-specs\u002F{SHA}\u002F{directory}\u002Fmain.tsp`\n   - Client customizations: `https:\u002F\u002Fraw.githubusercontent.com\u002FAzure\u002Fazure-rest-api-specs\u002F{SHA}\u002F{directory}\u002Fclient.tsp`\n   - Config: `https:\u002F\u002Fraw.githubusercontent.com\u002FAzure\u002Fazure-rest-api-specs\u002F{SHA}\u002F{directory}\u002Ftspconfig.yaml`\n   - **All route files**: Follow imports from `main.tsp` (e.g., `routes-service.tsp`, `routes-index.tsp`, `routes-knowledgebase.tsp`, etc.)\n   - **All model files**: Fetch everything in the `models\u002F` subdirectory if present, or follow imports\n4. Read the local SDK API listing: prefer `api\u002FAzure.Search.Documents.netstandard2.0.cs` (most inclusive); fall back to `api\u002FAzure.Search.Documents.net10.0.cs`\n5. List ALL files in `src\u002FGenerated\u002FModels\u002F` — this is the authoritative set of generated types\n6. Read custom partial classes: scan `src\u002F` for non-Generated `.cs` files\n\n**IMPORTANT**: Do NOT skip any TypeSpec files. The validation must cover the ENTIRE spec surface.\n\n### Step 2 — Extract TypeSpec Surface\n\nFrom the TypeSpec files, extract **ALL** of the following (no sampling, no shortcuts):\n\n1. **API Versions** — all `enum Versions { ... }` members. Identify which version is being added by this commit (compare to SDK's `ServiceVersion` enum to find the new one).\n2. **Operations** — all `op` declarations grouped by interface\u002Fnamespace (these become client methods). Note `@added(Versions.vXXX)` decorators.\n3. **Models** — ALL `model` declarations across ALL TypeSpec files (these become C# classes\u002Fstructs). For EACH model, record:\n   - Name\n   - Base type (if `extends` or `is`)\n   - All properties with types and optionality\n   - `@discriminator` if present\n   - `@added`\u002F`@removed` version annotations\n4. **Enums** — ALL `enum` declarations with all member values\n5. **Unions** — ALL `union` declarations (these become extensible structs in C#) with all member values\n6. **Discriminator hierarchies** — `@discriminator` decorators that create polymorphic type trees\n7. **Versioning** — `@added(Versions.vXXX)` and `@removed(Versions.vXXX)` decorators on types, properties, and operations. A feature is expected in the SDK if it was `@added` in any version ≤ the SDK's latest version and not `@removed`.\n8. **Routes** - ALL route declarations (e.g., `@route(\"\u002Findexes\")`) to verify correct client method placement and exposure. Ensure that new routes are exposed in the client.tsp and SDK as neeeded.\n\nFrom `client.tsp`, extract **ALL** overrides:\n\n1. **Renames** — every `@@clientName` augment (TypeSpec name → SDK name mapping)\n2. **Access changes** — every `@@access(\"internal\")` (types\u002Fmethods hidden from public API)\n3. **Suppressed methods** — `@@convenientAPI(op, false)` or `@@protocolAPI(op, false)`\n4. **Usage overrides** — `@@usage` forcing input\u002Foutput direction\n5. **Client restructuring** — `@client`, `@operationGroup`, `@@clientLocation`\n6. **Alternate types** — `@@alternateType` changing property types in the SDK\n7. **Client namespace** — `@@clientNamespace` moving types to different namespaces\n\n### Step 3 — Extract SDK Surface\n\nFrom the API listing file (`api\u002F*.cs`), extract:\n\n1. **Public types** — all `public partial class`, `public partial struct`, `public enum`, `public static class`, `public abstract partial class`\n2. **Public methods** — on ALL client types (search for classes ending in `Client`)\n3. **Public properties** — on ALL model types\n4. **Enum\u002Fstruct members** — all `public static` properties on extensible structs (union-derived types)\n5. **Factory methods** — on `SearchModelFactory`\n\nFrom the generated models directory (`src\u002FGenerated\u002FModels\u002F`), extract:\n\n6. **All generated files** — list every `.cs` file (excluding `.Serialization.cs`)\n7. **Access modifier of each generated type** — check if each is `public` or `internal`\n8. **Cross-reference**: every generated public type MUST appear in the API listing. If it doesn't, flag it.\n9. **Cross-reference**: every generated internal type must be explainable by a `client.tsp` `@@access(\"internal\")` override or by being a discriminator kind type.\n\nFrom custom code, note:\n\n10. **`[CodeGenSuppress]`** attributes — members actively hidden\n11. **`[CodeGenType]`** attributes — type name remappings\n12. **`[CodeGenMember]`** attributes — property name remappings\n13. **Hand-written types** — classes that exist only in custom code (e.g., `FieldBuilder`, `SearchFilter`, `SearchDocument`)\n\n### Step 3b — Exhaustive Generated Model Verification\n\nThis sub-step ensures NO model was silently dropped or incorrectly marked:\n\n1. For **every** file in `src\u002FGenerated\u002FModels\u002F*.cs` (excluding `*.Serialization.cs`):\n   - Read the type declaration line to get the type name and access modifier (`public` vs `internal`)\n   - If `public`: verify it appears in the API listing file\n   - If `internal`: verify there is a corresponding `@@access(\"internal\")` or `@@clientName` rename to `Internal*` in `client.tsp`, OR it is a discriminator kind type (naming pattern: `*Kind`, `*Type` used internally for polymorphism)\n2. Count totals: `{N} public, {M} internal, {0} unexplained`\n3. Any type that is public in generated code but missing from the API listing is a **CRITICAL** gap.\n4. Any type that is internal in generated code but has no explanation from `client.tsp` is a **WARNING** (may be intentional but needs verification).\n\n### Step 4 — Compare and Classify\n\n**This step MUST be exhaustive.** Do not sample or skip types. Every TypeSpec element must be accounted for.\n\n#### 4a — Version Filtering\n\nFirst, determine which API version is the SDK's **latest** (the default in `SearchClientOptions.ServiceVersion`). Then for each TypeSpec element:\n- If it has `@added(Versions.vX)` where `vX` ≤ latest SDK version → **expected in SDK**\n- If it has `@removed(Versions.vX)` where `vX` ≤ latest SDK version → **should NOT be in SDK**\n- If it has no version annotation → **expected in all versions**\n\n#### 4b — Operation Validation\n\nFor each TypeSpec operation, determine its expected SDK representation:\n\n| TypeSpec element | Expected in SDK as |\n|---|---|\n| `op doSomething(...)` on interface X | Method `DoSomething`\u002F`DoSomethingAsync` on client X |\n| `op` with `@@access(\"internal\")` in client.tsp | Should NOT appear in public API |\n| `op` with `@@convenientAPI(op, false)` | No convenience method (only protocol method if `@@protocolAPI` not also false) |\n\nVerify ALL operations on ALL clients.\n\n#### 4c — Model Validation (EXHAUSTIVE)\n\nFor **every** model in the TypeSpec:\n\n1. Determine its expected C# name (apply `@@clientName` if present)\n2. Determine its expected access (apply `@@access` if present)\n3. If expected public: verify it exists in the API listing with the correct name\n4. If expected internal: verify it does NOT appear in the public API listing\n5. For EACH property on the model:\n   - Determine expected C# name (PascalCase, or `@@clientName` override)\n   - Determine expected type (apply `@@alternateType` if present)\n   - Verify it exists on the SDK type with correct name and compatible type\n   - Check optionality: `?` in TypeSpec → nullable in SDK\n\n#### 4d — Enum\u002FUnion Validation (EXHAUSTIVE)\n\nFor **every** enum and union:\n\n1. Determine expected C# type:\n   - `enum` → C# `enum` or extensible struct (depends on usage)\n   - `union` with string base → extensible struct with `public static` members\n2. Verify all members\u002Fvalues are present in the SDK\n3. Flag any SDK values that don't exist in TypeSpec (could be backward-compat additions)\n\n#### 4e — Discriminator Hierarchy Validation\n\nFor each `@discriminator` in TypeSpec:\n\n1. Verify the base type exists as an abstract class in SDK\n2. Verify ALL derived types exist\n3. Verify the SDK has `Unknown*` fallback types for forward compatibility\n4. Cross-reference with `client.tsp` renames\n\n#### 4f — New Version Feature Validation\n\nFor the **specific API version being added** (the one in the TypeSpec commit that doesn't exist in the previous SDK release):\n\n1. Identify ALL types, properties, operations, and enum values annotated with `@added(Versions.vNEW)` where `vNEW` is the new version\n2. Verify EVERY one of these exists in the SDK\n3. This is the highest-priority check — these are the new features this commit introduces\n\nApply `client.tsp` transformations:\n- If `@@clientName(Foo, \"Bar\")` → expect `Bar` in SDK, not `Foo`\n- If `@@access(op, \"internal\")` → should NOT appear in public API\n- If `@@convenientAPI(op, false)` → no convenience method expected\n\n### Step 5 — Generate Report\n\nProduce a structured report with these sections:\n\n#### 5.1 — Missing Features (in TypeSpec, not in SDK)\n\nFor each missing element:\n```\n| TypeSpec Element | Expected SDK Name | Category | Recommended Fix |\n|---|---|---|---|\n| model FooBar | FooBar | Model | Regenerate or check [CodeGenSuppress] |\n| op getFoo | GetFoo\u002FGetFooAsync | Operation | Check client.tsp @@access or regenerate |\n| FooBar.bazProp | BazProp | Property | Check custom partial class |\n```\n\n**Recommended Fix** classification:\n- **Regenerate** — TypeSpec has it, generation should produce it, likely stale codegen\n- **Remove [CodeGenSuppress]** — SDK is actively suppressing it\n- **Add to client.tsp** — needs `@@usage` or `@@convenientAPI(op, true)` to generate\n- **SDK customization** — needs hand-written code (complex mapping, not 1:1)\n\n#### 5.2 — Extra Features (in SDK, not in TypeSpec)\n\nFor each extra element:\n```\n| SDK Element | Category | Source | Action Needed |\n|---|---|---|---|\n| SearchFilter | Utility class | Hand-written | None (SDK-only helper) |\n| FieldBuilder | Utility class | Hand-written | None (SDK-only helper) |\n| OldModel | Backward compat | Retained from prev GA | Verify still needed |\n```\n\n**Source** classification:\n- **Hand-written helper** — intentional SDK-only utility (no action)\n- **Backward compat retained type** — kept from a previous GA release for ApiCompat\n- **Stale customization** — was in old spec, removed from TypeSpec, should be evaluated\n- **client.tsp override** — exists due to `@@clientName` or restructuring\n\n#### 5.3 — Naming Mismatches\n\n```\n| TypeSpec Name | SDK Name | Source of Rename | Correct? |\n|---|---|---|---|\n| searchText | SearchText | Convention (PascalCase) | Yes |\n| fooBar | BazQux | client.tsp @@clientName | Verify intent |\n```\n\n#### 5.4 — Structural Differences\n\n- Operations on different clients than expected\n- Models in different namespaces\n- Properties with different types (e.g., `string` in TypeSpec vs `Uri` in SDK via customization)\n- Properties with different optionality (required in TypeSpec, optional in SDK or vice versa)\n\n#### 5.5 — Recommendations Summary\n\nPrioritized list of actions:\n1. **Critical** — public API gaps that affect functionality\n2. **Important** — naming\u002Fstructure issues that affect discoverability\n3. **Low** — cosmetic or documentation-only differences\n4. **No action** — intentional SDK-only additions or backward-compat retentions\n\nFor each recommendation, specify:\n- **Where to fix**: `client.tsp` | `src\u002F` customization | TypeSpec main spec (file a spec issue)\n- **How to fix**: specific decorator\u002Fattribute\u002Fpattern to use\n- **Risk**: breaking change? | backward compat impact?\n\n---\n\n## Fetching TypeSpec Files\n\nThe TypeSpec for this package lives in the external `Azure\u002Fazure-rest-api-specs` repo. To fetch:\n\n1. Read commit SHA from `tsp-location.yaml`\n2. Fetch `main.tsp` first — parse its `import` statements to discover all other files\n3. Fetch `client.tsp` — this contains ALL SDK-specific overrides\n4. Fetch `tspconfig.yaml` — this contains emitter options\n5. Recursively fetch ALL imported `.tsp` files (routes, models, etc.)\n6. Use raw GitHub URLs: `https:\u002F\u002Fraw.githubusercontent.com\u002FAzure\u002Fazure-rest-api-specs\u002F{SHA}\u002F{directory}\u002F{file}`\n7. The TypeSpec may import from `@azure-tools\u002Ftypespec-azure-core` and other packages — focus on the **local model and operation definitions**, not library imports.\n\n### Discovering TypeSpec Files\n\nParse `main.tsp` for lines like:\n```\nimport \".\u002Froutes-service.tsp\";\nimport \".\u002Froutes-index.tsp\";\nimport \".\u002Fmodels\u002Fcommon.tsp\";\n```\n\nEach imported file may itself import more files. Follow ALL local imports (starting with `.\u002F`). Skip package imports (starting with `@`).\n\n### Typical TypeSpec structure for this package:\n```\nspecification\u002Fsearch\u002Fdata-plane\u002FSearch\u002F\n├── main.tsp              # Entry point — defines service, API versions, imports routes\n├── client.tsp            # SDK customizations (clientName, access, usage, etc.)\n├── tspconfig.yaml        # Emitter configuration\n├── routes-*.tsp          # Operation definitions by resource area\n└── models (inline or in separate files imported by routes)\n```\n\n**Note**: The file structure may change between commits. Always discover files dynamically from `main.tsp` imports rather than assuming fixed paths.\n\n---\n\n## Handling Large TypeSpec Definitions\n\nThe Search service TypeSpec is large (400+ models, 50+ operations, 100+ enums\u002Funions). The validation MUST still be exhaustive. Use these strategies:\n\n1. **Automate the cross-reference** — use terminal commands to programmatically compare generated files against the API listing (see \"Automated Verification Commands\" below)\n2. **Fetch all TypeSpec files** — follow ALL imports from `main.tsp` recursively; fetch every `.tsp` file in the spec directory\n3. **Batch processing** — process files in batches but DO NOT skip any. Report progress: \"Checked 150\u002F400 models...\"\n4. **Focus on the new version first** — validate `@added(Versions.vNEW)` features with highest priority, then validate the full surface\n5. **Use subagents for parallel work** — delegate model validation to an Explore subagent if needed\n\n**NEVER skip types, NEVER sample, NEVER say \"and similar types follow the same pattern.\"** Every type must be individually verified.\n\n### Automated Verification Commands\n\nUse the `Validate-GeneratedModels.ps1` script to perform exhaustive cross-reference checks:\n\n```powershell\n# Full validation — cross-references all generated models against API listing\n.\u002F.github\u002Fskills\u002Fsearch-documents-typespec-validation\u002Fscripts\u002FValidate-GeneratedModels.ps1 -Format summary\n\n# Batch-check specific TypeSpec model names (after @@clientName renames) against the SDK\n.\u002F.github\u002Fskills\u002Fsearch-documents-typespec-validation\u002Fscripts\u002FValidate-GeneratedModels.ps1 -TypeNames @(\"SearchIndex\",\"SearchField\",\"SearchIndexer\")\n\n# JSON output for agent consumption\n.\u002F.github\u002Fskills\u002Fsearch-documents-typespec-validation\u002Fscripts\u002FValidate-GeneratedModels.ps1\n```\n\nThe script lives at [scripts\u002FValidate-GeneratedModels.ps1](scripts\u002FValidate-GeneratedModels.ps1). It resolves paths relative to the package root automatically.\n\n---\n\n## Known Intentional Differences\n\nThese differences are **expected** and should NOT be flagged as gaps:\n\n| SDK Element | Reason |\n|---|---|\n| `SearchDocument` (dynamic document) | SDK-only: enables `dynamic` and `Dictionary\u003Cstring,object>` patterns |\n| `FieldBuilder` | SDK-only: reflection-based field generation from C# model types |\n| `SearchFilter.Create()` | SDK-only: OData filter expression builder |\n| `SearchIndexingBufferedSender\u003CT>` | SDK-only: client-side batching with retry |\n| `SuggestOptions` \u002F `AutocompleteOptions` | May differ from raw TypeSpec due to property grouping |\n| `SemanticSearchOptions` \u002F `VectorSearchOptions` | SDK-only sub-objects that group `SearchOptions` properties |\n| Backward-compat retained types | Types from previous GA releases kept for ApiCompat |\n| `SearchModelFactory` extra methods | May have legacy overloads for backward compat |\n| Discriminator kind structs (e.g., `*Kind`, `*Type`) | Internal by design — used for polymorphic deserialization |\n| `Unknown*` types | Internal forward-compat fallback types for polymorphic hierarchies |\n| Types with `@@access(\"internal\")` in client.tsp | Intentionally hidden — verify they're internal, not missing |\n\n---\n\n## Output Format\n\nPresent the report as a markdown table-based summary. Always include:\n\n1. **Scope summary**: \"Validated against TypeSpec commit `{SHA}`, API version `{version}`, {N} total TypeSpec models, {M} operations, {K} enums\u002Funions\"\n2. **Automated cross-reference results**: \"Generated models: {X} public (all in API), {Y} internal (all explained), {Z} unexplained\"\n3. **Gap counts**: X missing, Y extra, Z mismatches\n4. **Critical items first** (blocking or high-impact gaps)\n5. **Full type listing for new version features** — every `@added(Versions.vNEW)` type\u002Foperation explicitly confirmed or flagged\n6. **Actionable recommendations** with specific file paths and patterns\n\nUse collapsible sections (`\u003Cdetails>`) for large sub-lists (>20 items), but ALWAYS report the full data — never truncate or summarize.\n\n---\n\n## Constraints\n\n- **DO NOT** modify any files during validation — this is a read-only analysis\n- **DO NOT** flag backward-compat retained types as \"extra\" without checking git tags\n- **DO NOT** flag hand-written helpers (FieldBuilder, SearchFilter, etc.) as issues\n- **DO NOT** skip any types, operations, or enums — the analysis MUST be exhaustive\n- **DO NOT** sample or summarize — report exact counts and exact names\n- **DO NOT** hardcode API version names — read them dynamically from `main.tsp` and the SDK's `ServiceVersion` enum\n- **DO** account for client.tsp transformations before flagging mismatches\n- **DO** note when a gap might be intentional (e.g., `@@access(\"internal\")`)\n- **DO** distinguish between \"missing from public API\" and \"present but internal\"\n- **DO** run the automated verification commands (Step 3b) to catch every generated model\n- **DO** verify enum\u002Funion member counts match between TypeSpec and SDK\n- **DO** explicitly confirm the new API version's `ServiceVersion` enum value exists and is set as default\n\n## Completeness Checklist\n\nBefore reporting results, confirm ALL of the following:\n\n- [ ] All TypeSpec files fetched (main.tsp + all imports + client.tsp)\n- [ ] Every generated model file cross-referenced against API listing\n- [ ] Every operation on every client verified\n- [ ] Every `@@clientName` rename verified in SDK\n- [ ] Every `@@access(\"internal\")` verified as internal in SDK\n- [ ] New API version's `ServiceVersion` value present and set as default\n- [ ] All new-version `@added` features individually verified\n- [ ] Enum\u002Funion member counts validated\n- [ ] Discriminator hierarchies validated (base + all derived + Unknown* fallback)\n- [ ] Summary counts reported: types checked, operations checked, gaps found",{"name":5,"description":7},"main","dbc5eb654c3492137a4fbeeb6776c804f0042063","sdk\u002Fsearch\u002FAzure.Search.Documents\u002F.github\u002Fskills\u002Fsearch-documents-typespec-validation",5228,"https:\u002F\u002Fgithub.com\u002FAzure\u002Fazure-sdk-for-net","https:\u002F\u002Fgithub.com\u002FAzure","https:\u002F\u002Fdocs.microsoft.com\u002Fen-us\u002Fazure\u002F","APIs, SDKs and open source projects from Microsoft Azure","2026-11-14 22:39:26",{"source":8,"skillName":5,"commands":67,"prompt":77,"zipAvailable":78},[68,71,74],{"tool":69,"command":70},"npx","npx skills add Azure\u002Fazure-sdk-for-net --skill search-documents-typespec-validation",{"tool":72,"command":73},"bunx","bunx skills add Azure\u002Fazure-sdk-for-net --skill search-documents-typespec-validation",{"tool":75,"command":76},"pnpm","pnpm dlx skills add Azure\u002Fazure-sdk-for-net --skill search-documents-typespec-validation","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FAzure\u002Fazure-sdk-for-net\u002Fblob\u002Fmain\u002Fsdk\u002Fsearch\u002FAzure.Search.Documents\u002F.github\u002Fskills\u002Fsearch-documents-typespec-validation\u002FSKILL.md",true,[80],{"path":81,"resourceType":82,"resourceTypeDesc":83,"sizeBytes":84,"sourceHtmlUrl":85},"scripts\u002FValidate-GeneratedModels.ps1","SCRIPT","脚本",5659,"https:\u002F\u002Fgithub.com\u002FAzure\u002Fazure-sdk-for-net\u002Fblob\u002Fmain\u002Fsdk\u002Fsearch\u002FAzure.Search.Documents\u002F.github\u002Fskills\u002Fsearch-documents-typespec-validation\u002Fscripts\u002FValidate-GeneratedModels.ps1",[87,112,140,160,176,184],{"skillNo":88,"name":89,"nameZh":6,"description":90,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":91,"categories":92,"keywords":101,"publishedAt":52},"01M6BTE1QTJPYDAN115GS2EHDQ","update-chat-api","Use when: updating, exporting, refreshing, or validating the public API baseline for Azure.Messaging.WebPubSub.Chat after a public API change.","https:\u002F\u002Fgithub.com\u002FAzure\u002Fazure-sdk-for-net\u002Fblob\u002Fmain\u002Fsdk\u002Fwebpubsub\u002F.github\u002Fskills\u002Fupdate-chat-api\u002FSKILL.md",[93,96],{"categoryNo":94,"categoryName":95,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000010","后端与接口",{"categoryNo":97,"categoryName":98,"taxonomyType":99,"taxonomyTypeDesc":100},"01JBSEEDCAT000000000000030","开发工程师","PROFESSION","适用职业",[102,32,103,104,40,105,106,107,108,109,110,46,111],"update","update chat api","chat","for","public api","use","public","baseline","messaging","change",{"skillNo":113,"name":114,"nameZh":6,"description":115,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":116,"categories":117,"keywords":123,"publishedAt":52},"01M6BTDYJS2RSGZR2T2BTJJ6YC","search-documents","E2E workflow skill for Azure.Search.Documents SDK (TypeSpec + heavy customization). Handles full release cycles and partial updates: SHA update; code generation; build; customization fixes; ServiceVersion sync; testing; API export; changelog; version; samples; formatting; release metadata. WHEN: create new package version for Azure.Search.Documents; regenerate Azure.Search.Documents; fix Azure.Search.Documents bug; release Azure.Search.Documents; update Azure.Search.Documents spec. Do not use for Azure.ResourceManager.Search or Azure.Provisioning.Search.","https:\u002F\u002Fgithub.com\u002FAzure\u002Fazure-sdk-for-net\u002Fblob\u002Fmain\u002Fsdk\u002Fsearch\u002FAzure.Search.Documents\u002F.github\u002Fskills\u002Fsearch-documents\u002FSKILL.md",[118,121,122],{"categoryNo":119,"categoryName":120,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000008","测试与质量",{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":97,"categoryName":98,"taxonomyType":99,"taxonomyTypeDesc":100},[27,25,29,124,125,51,126,127,128,129,130,46,131,102,24,132,133,40,134,135,136,137,36,32,138,139,42],"release","Code Generation","workflow","sync","package","changelog","create","code","new","e2e","new package","updates","workflow skill","bug","provisioning","testing",{"skillNo":141,"name":142,"nameZh":6,"description":143,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":144,"categories":145,"keywords":146,"publishedAt":52},"01M6BTDVJGZ0N7F7DXR5Z7E0QH","search-documents-version-diff","Diff the current Azure.Search.Documents public API surface against a previous published version and detect preview-to-preview regressions where the SDK customization layer was not bubbled up after a TypeSpec change. Use whenever the user asks to compare Azure.Search.Documents betas, verify no Azure.Search.Documents preview features dropped, regression audit between Azure.Search.Documents versions, sanity-check a release branch for Azure.Search.Documents, or investigate a missing Azure.Search.Documents preview feature — even if they don't say the word \"diff\". Specifically catches dropped wrappers (QueryAnswer\u002FQueryCaption\u002FQueryRewrites style), lost SearchOptions aggregator redirectors, `@@access(\"internal\")` flips, deleted-instead-of-gated `#if AZURE_SEARCH_PREVIEW` blocks, dropped `ServiceVersion` enum values, and convenience-to-protocol downgrades.","https:\u002F\u002Fgithub.com\u002FAzure\u002Fazure-sdk-for-net\u002Fblob\u002Fmain\u002Fsdk\u002Fsearch\u002FAzure.Search.Documents\u002F.github\u002Fskills\u002Fsearch-documents-version-diff\u002FSKILL.md",[],[27,147,25,29,148,149,111,51,46,41,34,150,151,106,152,153,154,155,156,157,158,32,44,159,124,24],"search documents version diff","version","diff","layer","sanity","aggregator","preview","up","branch","access","investigate","verify","protocol",{"skillNo":161,"name":162,"nameZh":6,"description":163,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":164,"categories":165,"keywords":166,"publishedAt":52},"01M6BTDP9JS9KNT1H9ED8AGZF5","test-skill_file","Roll dice using a random number generator.","https:\u002F\u002Fgithub.com\u002FAzure\u002Fazure-sdk-for-net\u002Fblob\u002Fmain\u002Fsdk\u002Fai\u002FAzure.AI.Projects.Agents\u002Ftests\u002FTestData\u002Froll-dice\u002FSKILL.md",[],[167,168,169,170,171,172,173,174,175],"test skill file","file","Test Skill","test","number","generator","random","dice","roll dice",{"skillNo":177,"name":178,"nameZh":6,"description":179,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":180,"categories":181,"keywords":182,"publishedAt":52},"01M6BTDMF2VK2CM53SSHZNWX7T","roll-dice","Roll dice using a random number generator. Use when asked to roll a die (d6, d20, etc.), roll dice, or generate a random dice roll.","https:\u002F\u002Fgithub.com\u002FAzure\u002Fazure-sdk-for-net\u002Fblob\u002Fmain\u002Fsdk\u002Fai\u002FAzure.AI.Projects.Agents\u002Ftests\u002FSamples\u002Froll-dice\u002FSKILL.md",[],[174,175,172,40,171,173,107,183],"generate",{"skillNo":185,"name":178,"nameZh":6,"description":179,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":186,"categories":187,"keywords":188,"publishedAt":52},"01M6BTDJSRPS3FYZ5HD7K1HGQP","https:\u002F\u002Fgithub.com\u002FAzure\u002Fazure-sdk-for-net\u002Fblob\u002Fmain\u002Fsdk\u002Fai\u002FAzure.AI.Extensions.OpenAI\u002Ftests\u002FSamples\u002FAssets\u002Froll-dice\u002FSKILL.md",[],[175,174,183,40,171,172,173,107]]