Azure / Azure/azure-sdk-tools

[ApiView] Add JSON schema diff tracking for ConfigurationSchema.json (JsonSchemaSegment)

Open
#14,701 0 comments 0 reactions 0 assignees View on GitHub
.NET APIView
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.