[ApiView] Add JSON schema diff tracking for ConfigurationSchema.json (JsonSchemaSegment)
- Dominant language
- C#
- Stars
- 135
- Forks
- 260
- Avg merge
- 1d 22h
- Merged PRs (30d)
- 115
Description
## Background
Azure SDK packages now ship `ConfigurationSchema.json` files via the MSBuild **JsonSchemaSegment** mechanism. These schema fragments provide JSON IntelliSense and validation for `appsettings.json` when configuring SDK clients — the same approach used by .NET Aspire, YARP, and AWS SDK .NET.
**System.ClientModel 1.10.0** is the first package to ship with this schema (see [design proposal](https://gist.github.com/m-nash/54dc33e269485118b8da8d8cfa8759d0)), and all Azure SDK libraries will follow. The schema defines configuration surfaces like credential sources, pipeline options, logging settings, retry policies, and more.
These schema files are **public API surface** — customers write `appsettings.json` configuration against them, and breaking changes (renamed properties, removed required fields, changed types, altered conditionals) would break customer applications.
## Problem
ApiView currently tracks only the .NET assembly API surface (public types, methods, properties extracted from DLLs). It does **not** inspect or diff the `ConfigurationSchema.json` files embedded in NuGet packages.
This means:
- Breaking changes to schema properties, types, or structure go **completely undetected**
- There is no API review gate for schema changes
- Architects cannot review or comment on schema surface changes the way they can for code API changes
## Requirements
ApiView should extract `ConfigurationSchema.json` from NuGet packages and render the schema as structured, reviewable API surface elements — with full diff support between versions.
### Schema elements to track
The following JSON Schema keywords should be parsed and rendered as reviewable lines:
| Category | Keywords |
|----------|----------|
| **Core structure** | `properties`, `type`, `description`, `default`, `title` |
| **Validation** | `required`, `enum`, `const` |
| **Composition** | `allOf`, `anyOf`, `oneOf`, `not` |
| **Conditionals** | `if`, `then`, `else` |
| **References** | `$ref`, `$defs` (definitions) |
| **Object constraints** | `additionalProperties`, `patternProperties`, `minProperties`, `maxProperties` |
| **String constraints** | `format`, `pattern`, `minLength`, `maxLength` |
| **Numeric constraints** | `minimum`, `maximum`, `exclusiveMinimum`, `exclusiveMaximum`, `multipleOf` |
| **Array constraints** | `items`, `minItems`, `maxItems`, `uniqueItems` |
| **Metadata** | `$schema`, `$id`, `deprecated` |
### Diff behavior
Breaking changes should be detectable, for example:
- Property removed or renamed
- `type` changed (e.g., `string` → `number`)
- Property added to `required` array
- `enum` value removed
- Conditional logic (`if/then/else`) altered
- `additionalProperties` changed from `true` to `false`
## Suggested implementation approach
> These are suggestions based on the current ApiView architecture, not prescriptive requirements.
1. **Extract schema from .nupkg** — The C# NuGet parser (`tools/apiview/parsers/csharp-api-parser/CSharpAPIParser/Program.cs`) already unpacks NuGet packages. Extend it to locate `ConfigurationSchema.json` files (shipped via `JsonSchemaSegment` build targets in the package's `build/` or `buildTransitive/` folder).
2. **Parse JSON Schema into ReviewLine tokens** — Convert the schema into the existing `ReviewLine` / `ReviewToken` tree structure. Each schema property could become a `ReviewLine` with children for nested objects. Keywords like `type`, `required`, `enum`, `if/then/else` would be rendered as tokens with appropriate `TokenKind` values.
3. **Leverage existing diff infrastructure** — ApiView already diffs `ReviewLine` trees between package versions. By representing schema elements with stable `LineId` values (e.g., based on JSON pointer paths like `/properties/Clients/properties/NetworkTimeout`), the existing diff engine should detect additions, removals, and modifications.
4. **Render in the API review UI** — Schema surface could appear as a separate section in the review (e.g., "Configuration Schema") below the assembly API surface, with the same commenting and approval workflow.
## Context
- **Parent issue:** Azure/azure-sdk-for-net#55538
- **Design proposal:** https://gist.github.com/m-nash/54dc33e269485118b8da8d8cfa8759d0
- **First package with schema:** System.ClientModel 1.10.0
- **Prototype branch:** [`temp/json-schema-segment-test`](https://github.com/Azure/azure-sdk-for-net/tree/temp/json-schema-segment-test/sdk/core/Azure.Core/src/schemas/examples/segment-test)
Contributor guide
Research direction
Start with tools/apiview/parsers/csharp-api-parser/CSharpAPIParser/Program.cs to trace NuGet extraction, then read the existing ReviewLine/ReviewToken and diff infrastructure. Use the prototype branch and design proposal for context; done means ConfigurationSchema.json is rendered as reviewable surface and schema changes are detected between package versions.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- csharp
- Domain
- api, tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100