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.

This relies on the two tspd fixes from #11813 (now merged): loading the library's own
tspconfig.yaml before compiling it, and giving generated accessors doc comments so api-extractor
accepts them.

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/json-schema@11812

commit: 4ab02ad

[github-actions]

All changed packages have been documented.

• ✅ @typespec/json-schema

Show changes

@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.

[azure-sdk-automation]

You can try these changes here

🛝 Playground	🌐 Website	🛝 VSCode Extension