Expose the service.yaml JSON Schema and types from typespec-autorest
- 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
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