[BUG](system) Model-constraint decorators return the class they decorate

[Seth Fitzsimmons (sethfitz)]

Description

The model-constraint decorators were annotated to return type[BaseModel], or Callable[[type[BaseModel]], type[BaseModel]] for the factories. pyright and ty honor a class decorator's return type, so every decorated model, Division and Names among them, became plain BaseModel and lost its fields in hover, completion and attribute access. mypy ignores class-decorator return types, so make check passed.

The fix reuses ModelT, the TypeVar create_model already declares, to carry the class through. ModelConstraint.decorate and no_extra_fields take and return type[ModelT]. require_if, forbid_if, require_any_of, require_any_true, radio_group and min_fields_set return Callable[[type[ModelT]], type[ModelT]]. create_model returns type[ModelT] for a type[ModelT] base, so decorate returns its result without a cast. Runtime behavior is unchanged.

@scoped in overture-schema-common is out of scope; #760 says why.

Reference

1. Closes [BUG](system) Model-constraint decorators erase the decorated class under pyright and ty #760.

Testing

test_decorator_types.py calls each decorator as a function under assert_type(..., type[Model]). mypy checks an ordinary call's return type even though it skips decorator syntax, so this puts all eight sites in front of the mypy gate. Against the old annotations it reports eight assert-type errors. It is the only added test.

pyright and ty are not in the tree. Revealed type of a field on a model decorated at each of the eight sites:

	before	after
pyright 1.1.414	Unknown, "Cannot access attribute"	the field's type
ty 0.0.81	Unknown, invalid-type-form	the field's type
mypy 2.3.1	the field's type; decorate() called as a function gave BaseModel	the field's type

On the published models, reveal_type(d.names) for d: Division goes from Unknown to Names under pyright.

Checklist

Checklist of tasks commonly-associated with schema pull requests. Please review the relevant checklists and ensure you do all the tasks that are required for the change you made.

1. Add relevant examples.
2. Add relevant counterexamples.
3. Update any counterexamples that became obsolete. For example, if a counterexample uses property A but is not intended to test property A's validity, and you made a schema change that invalidates property A in that counterexample, fix the counterexample to align it with your schema change.
4. Update in-schema documentation using plain English written in complete sentences, if an update is required.
5. Update Docusaurus documentation, if an update is required.
6. Review change with Overture technical writer to ensure any advanced documentation needs will be taken care of, unless the change is trivial and would not affect the documentation.

Documentation website

Update the hyperlink below to put the pull request number in.

[Docs preview for this PR.](https://dfhx9f55j8eg5.cloudfront.net/pr/<PUT THE PR # HERE>)

[github-actions]

🗺️ Schema reference docs preview is live!

🌍 Preview	https://staging.overturemaps.org/schema/pr/761/schema/index.html
🕐 Updated	Sep 23, 2026 22:50 UTC
📝 Commit	4c7fbac
🔧 env SCHEMA_PREVIEW	true

Note

♻️ This preview updates automatically with each push to this PR.

[Roel Bollens (RoelBollens-TomTom)]

I'd suggest reusing ModelT from create_model.py as type[ModelT] instead of a new M bound to type[BaseModel]. Same fix, matches Pydantic's way, and the cast in decorate becomes unnecessary because create_model already returns type[ModelT].

[Seth Fitzsimmons (sethfitz)]

Roel Bollens (@RoelBollens-TomTom) thanks for the pointer. Updated!