Azure / Azure/typespec-azure

Expose the service.yaml JSON Schema and types from typespec-autorest

Open Beginner friendly
#5,174 1 comment 0 reactions 0 assignees View on GitHub
design:proposed emitter:autorest feature
Dominant language
TypeScript
Stars
27
Forks
90
Avg merge
1d 22h
Merged PRs (30d)
156

Description

`typespec-autorest` already ships the `service.yaml` JSON Schema as `schema/dist/ServiceYaml.json`, and declares the `ServiceYaml` / `ServiceYamlVersion` interfaces in `src/types.ts`. Neither is reachable by a consumer:

- The JSON file is listed in `files`, but there is no matching entry in `exports`, so importing it throws:

```
ERR_PACKAGE_PATH_NOT_EXPORTED: Package subpath './schema/dist/ServiceYaml.json'
is not defined by "exports"
```

- `ServiceYaml` and `ServiceYamlVersion` live in `dist/src/types.d.ts`, which `index.d.ts` does not re-export (it re-exports `openapi2-document.js` but not `types.js`).

The practical consequence is in Azure/typespec-azure#4828, which asks the TSV rule to validate manifests as *schema-valid against the published JSON Schema*. The rule ([Azure/azure-rest-api-specs#45301](https://github.com/Azure/azure-rest-api-specs/pull/45301)) currently re-declares a minimal zod schema for the two fields it reads, because the alternatives are all bad:

- a deep path import is blocked by `exports`
- reaching into `node_modules/@azure-tools/typespec-autorest/schema/dist/ServiceYaml.json` by hand bypasses module resolution and breaks silently on layout changes
- taking a real dependency on the emitter drags `@typespec/compiler`, `@typespec/http` and the ARM libraries into a tool that runs on every PR in `azure-rest-api-specs`

That means the schema and its only enforcement point can drift apart, which is exactly what the schema is supposed to prevent.

### Proposal

Add a subpath export for the schema, so it can be consumed without pulling in the emitter runtime:

```jsonc
"exports": {
".": { /* ... */ },
"./testing": { /* ... */ },
"./schema/service-yaml.json": "./schema/dist/ServiceYaml.json"
}
```

And re-export the types from the package root:

```ts
export type { ServiceYaml, ServiceYamlVersion } from "./types.js";
```

A tiny `parseServiceYaml()` helper that validates and returns a typed manifest would be even better, and would let every consumer share one implementation — but the export alone unblocks #4828.

cc #4825

Contributor guide

Open the contributing guide

Research direction

Inspect the package exports in package.json, the declarations in src/types.ts and index.d.ts, and the existing schema at schema/dist/ServiceYaml.json. Verify that the proposed schema subpath resolves for consumers and that the package root exposes ServiceYaml and ServiceYamlVersion; done means both imports work without a deep node_modules path or emitter runtime dependency.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
tooling
Issue type
Feature
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
72/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.