Declare json-schema metadata decorators with auto dec

[Timothee Guerin (timotheeguerin)]

Every metadata-only decorator in @typespec/json-schema carried the same JavaScript boilerplate: a
state symbol, a useStateMap pair, and a $dec function whose entire body was a set call. Fourteen
decorators, ~150 lines of plumbing that says nothing about the language.

auto dec (compiler 1.15, experimental) lets the compiler synthesize that implementation and lets
tspd generate typed accessors from the declaration. This makes @typespec/json-schema the first
stable library to adopt it — a real test of the feature beyond the internal markers in
@typespec/graphql.

-extern dec minContains(target: unknown[] | ModelProperty, value: valueof int32);
+auto dec minContains(target: unknown[] | ModelProperty, value: valueof int32);

-const [getMinContains, setMinContains] = createDataDecorator<MinContainsDecorator, number>(
-  JsonSchemaStateKeys["JsonSchema.minContains"],
-);
+// generated by tspd
+export function getMinContains(program: Program, target: Type | ModelProperty): number | undefined;
+export function setMinContains(program: Program, target: Type | ModelProperty, value: number): void;

Affects @baseUri, @id, @oneOf, @multipleOf, @contains, @minContains, @maxContains,
@uniqueItems, @minProperties, @maxProperties, @contentEncoding, @contentMediaType,
@contentSchema and @prefixItems. @jsonSchema, @extension and Private.@validatesRawJson do
real work and stay as they are.

Not breaking. The library opts itself into the feature through its own tspconfig.yaml, so
consumers need no configuration. Every previously exported $dec function and NameDecorator type
is kept as a deprecated shim delegating to the generated set* accessor. Accessors whose historical
signature was wider than the generated one (getBaseUri, isOneOf, getContentEncoding, ...) or
shaped differently (getUniqueItems must return true | undefined, not boolean, or the emitter
would start writing uniqueItems: false everywhere) keep their old signature via a thin wrapper.

One intentional behaviour change: applying one of these decorators twice on the same declaration now
reports a duplicate-decorator warning. createDataDecorator never validated that. Last write still
wins.

Stacked on #11813, which carries the two tspd fixes this migration needs:
loading the library's own tspconfig.yaml before compiling it, and giving generated accessors doc
comments so api-extractor accepts them. Those commits drop out of this branch once #11813 merges;
review them there.

The existing json-schema test suite passes unchanged, which is the behaviour contract here.

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@typespec/graphql@11812

npm i https://pkg.pr.new/@typespec/json-schema@11812

npm i https://pkg.pr.new/@typespec/tspd@11812

commit: 317484a

[github-actions]

All changed packages have been documented.

• ✅ @typespec/graphql
• ✅ @typespec/json-schema
• ✅ @typespec/tspd

Show changes

@typespec/graphql - internal ✏️

Regenerate the decorator signatures to pick up the doc comments now emitted for auto decorator,> accessors.

@typespec/json-schema - deprecation ✏️

The metadata-only decorators of this library are now declared as auto dec, so the compiler,> synthesizes their implementation and provides typed accessors. This affects @baseUri, @id,,> @oneOf, @multipleOf, @contains, @minContains, @maxContains, @uniqueItems,,> @minProperties, @maxProperties, @contentEncoding, @contentMediaType, @contentSchema and,> @prefixItems.,> ,> Nothing changes for TypeSpec authors. For JavaScript consumers, the $baseUri-style implementation,> functions and their BaseUriDecorator-style signature types are deprecated: they are no longer what,> the compiler invokes. Use the generated set* accessor to apply a decorator programmatically:,> ,> ts,> // Before,> context.call($minContains, target, 2);,> ,> // After,> import { setMinContains } from "@typespec/json-schema";,> setMinContains(program, target, 2);,> ,> ,> Applying one of these decorators twice on the same declaration now reports a duplicate-decorator,> warning. The last application still wins.

@typespec/tspd - fix ✏️

Document the generated auto decorator accessors with the description of the decorator they read or,> write, so libraries re-exporting them satisfy api-extractor's ae-undocumented rule.,> ,> ts,> /** Mark a model as a GraphQL input type in the emitted schema. */,> export function isInputType(program: Program, target: Model): boolean {,> return hasAutoDecorator(program, "TypeSpec.GraphQL.inputType", target);,> },>

@typespec/tspd - fix ✏️

Honor the library's own tspconfig.yaml when generating signatures and reference documentation, so,> libraries that opt into a compiler feature (such as auto-decorators) no longer report errors during,> gen-extern-signature and doc.

[azure-sdk-automation]

You can try these changes here

🛝 Playground	🌐 Website	🛝 VSCode Extension