feat(compiler): Support explicit property optionality overrides

[Timothee Guerin (timotheeguerin)]

Optionality transforms currently inherit versioning history that can reject their output or undo it in older snapshots. Comparing source and result is insufficient: making an already-optional property optional still needs to override its historical requiredness.

This is the explicit structural-override prototype for #11592, an independent alternative to #11968, not a follow-up to merge alongside it.

Transforms express intent through an experimental compiler API:

import type { DecoratorContext, Model } from "@typespec/compiler";
import { unsafe_overridePropertyOptionality } from "@typespec/compiler/experimental";

export function $relaxed(context: DecoratorContext, target: Model) {
  for (const property of target.properties.values()) {
    unsafe_overridePropertyOptionality(property, true, context);
  }
}

OptionalProperties<T> adopts this contract. Versioning consults override provenance rather than recognizing helper names, so both @madeRequired and already-optional @madeOptional properties stay optional through is, spreads, and version snapshots. Required overrides work symmetrically. Unrelated history remains intact, and newly authored optionality annotations still apply and are validated.

Design trade-off: this adds compiler cloning and decorator-replay support instead of inferring intent from boolean differences. Custom transforms must adopt the API and decorators must pass their context; direct assignments do not record semantic overrides. This is an optionality-only experiment, not a general metadata-invalidation or derivation-replay framework.

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@typespec/compiler@11969

npm i https://pkg.pr.new/@typespec/versioning@11969

commit: 8b6b708

[github-actions]

All changed packages have been documented.

• ✅ @typespec/compiler
• ✅ @typespec/versioning

Show changes

@typespec/compiler - feature ✏️

Add experimental explicit optionality overrides for derived properties. Overrides retain same-value transform intent and inherited annotation provenance through compiler and typekit cloning.,> ,> ts,> import { unsafe_overridePropertyOptionality } from "@typespec/compiler/experimental";,> ,> // In a decorator, pass its context so cloning does not repeat the transform.,> unsafe_overridePropertyOptionality(derivedProperty, true, context);,>

@typespec/versioning - fix ✏️

Keep OptionalProperties properties optional in every version, including spreads and properties already made optional. Honor explicit structural overrides instead of inherited @madeRequired and @madeOptional history, while preserving presence, rename, and type history and validating newly authored annotations.