Azure / Azure/azure-functions-core-tools

Publish JSON schemas for v5 CLI configs to SchemaStore + aka.ms redirects

Open
#4,936 0 comments 0 reactions 0 assignees View on GitHub
v5 vnext
Dominant language
C#
Stars
1.5k
Forks
498
Avg merge
4d 20h
Merged PRs (30d)
14

Description

Tracks publishing the JSON schemas the v5 CLI references via `$schema`, and standing up the corresponding `aka.ms/func/*` redirects.

## Why

The v5 CLI writes/consumes several JSON config files that declare a versioned `$schema` URL. For editor IntelliSense and validation to work in VS Code / Visual Studio, each URL needs to:

1. Resolve (via `aka.ms`) to a real schema file.
2. Be registered in [SchemaStore](https://github.com/SchemaStore/schemastore) so editors auto-associate by filename.

We chose the **versioned URI** pattern (e.g. `/v1/schema.json`), so each breaking change ships under a new path and older CLIs/editors keep working unchanged.

## Schemas to publish

| Config | `$schema` URL | Tracked by |
|---|---|---|
| Workload manifest (`workloads.json`) | `https://aka.ms/func/workloads/v1/schema.json` | #4921 |
| Profiles | `https://aka.ms/func/profiles/v1/schema.json` | TBD |
| CLI config | `https://aka.ms/func/config/v1/schema.json` | TBD |

(Add new rows here as more configs land.)

## Per-schema checklist

For each schema above:

- [ ] Author the JSON Schema document (draft-07 or draft 2020-12, match SchemaStore convention).
- [ ] Open a PR against [SchemaStore/schemastore](https://github.com/SchemaStore/schemastore/tree/master/src/schemas/json) adding the file under `src/schemas/json/`.
- [ ] Add the catalog entry in `src/api/json/catalog.json` with the appropriate `fileMatch` glob.
- [ ] Create the `aka.ms/func//v1/schema.json` redirect pointing at the raw SchemaStore URL.
- [ ] Verify `$schema` resolves and validates a real config in VS Code.
- [ ] Cross-link the SchemaStore PR back to this issue.

## Conventions

- **Versioning lives in the URL path.** Bump `/v1/` → `/v2/` only on breaking shape changes. Additive changes evolve the v1 file in place.
- **No parallel `version` field in the document.** Single source of truth (per Fabio's guidance on PR #4921).
- **CLI loaders closed-set match** the `$schema` value and reject unknown versions with an actionable error.

Contributor guide

Open the contributing guide

Research direction

Start with the schema references and versioning conventions in this issue, then review the related workload manifest work in #4921. Author each listed JSON Schema, add its file and catalog entry under SchemaStore's src/schemas/json/ and src/api/json/catalog.json, and create the matching aka.ms/func redirect. Done means each URL resolves, a real config validates in VS Code, and the SchemaStore PR is cross-linked.

Written by the indexing model from the issue text.

Assessment

Tech stack
json
Domain
cli, tooling
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.