[`ruff`] Update schemars to v1 #20942

TaKO8Ki · 2025-10-17T15:41:56Z

Summary

FIxes #19173

Update schemars to v1

I’ve verified that the fundamentals of ruff.schema.json and ty.schema.json remain unchanged following the Schemars upgrade.

The migration is based on https://graham.cool/schemars/migrating.

Shared Changes

~~Upgraded both schemas to JSON Schema draft 2020-12 andmigrated shared types into $defs, with all $ref paths now using #/$defs/....~~
Added reusable helpers such as $defs/string (and array helpers like Array_of_string) to avoid duplicating scalar/collection shapes.
Reformatted descriptions with consistent newline breaks. [Schemars 1.0] — since v1.0.0-alpha.3, Schemars stops collapsing doc-comment whitespace; multi-line Rust docs flow through to description verbatim. ref: Handling of newline in RustDoc GREsau/schemars#120
Kept existing deprecated flags but moved them earlier within each property object to match the new formatting.

ty.schema.json

Introduced $defs entries for path-related types (RelativePathBuf, SystemPathBuf) and updated path properties to reference them.
Redirected overrides to a new OverridesOptions array definition with expanded multi-line documentation and examples, while maintaining the original rule descriptions under the updated formatting.

Test Plan

Check if existing tests pass.

github-actions · 2025-10-17T15:47:53Z

Diagnostic diff on typing conformance tests

No changes detected when running ty on typing conformance tests ✅

github-actions · 2025-10-17T15:48:44Z

`mypy_primer` results

No ecosystem changes detected ✅
No memory usage changes detected ✅

github-actions · 2025-10-17T16:11:04Z

`ruff-ecosystem` results

Linter (stable)

✅ ecosystem check detected no linter changes.

Linter (preview)

✅ ecosystem check detected no linter changes.

Formatter (stable)

✅ ecosystem check detected no format changes.

Formatter (preview)

✅ ecosystem check detected no format changes.

TaKO8Ki · 2025-10-17T18:10:23Z

ruff.schema.json

@@ -1415,7 +1405,7 @@
            "null"
          ],
          "items": {
-            "type": "string"
+            "$ref": "#/$defs/string"


These changes looks weird, but they refer to Name struct, which means String in schemars. That is why they use defs/string instead of string.

ruff/crates/ruff_workspace/src/options.rs

Lines 1970 to 1977 in c424007

/// Additional names to ignore when considering `flake8-self` violations,

/// in addition to those included in [`ignore-names`](#lint_flake8-self_ignore-names).

#[option(

default = r#"[]"#,

value_type = "list[str]",

example = r#"extend-ignore-names = ["_base_manager", "_default_manager", "_meta"]"#

)]

pub extend_ignore_names: Option<Vec<Name>>,

ruff/crates/ruff_workspace/src/options.rs

Lines 1960 to 1968 in c424007

/// A list of names to ignore when considering `flake8-self` violations.

#[option(

default = r#"["_make", "_asdict", "_replace", "_fields", "_field_defaults", "_name_", "_value_"]"#,

value_type = "list[str]",

example = r#"

ignore-names = ["_new"]

"#

)]

pub ignore_names: Option<Vec<Name>>,

ruff/crates/ruff_python_ast/src/name.rs

Lines 204 to 227 in c424007

#[cfg(feature = "schemars")]

impl schemars::JsonSchema for Name {

fn is_referenceable() -> bool {

String::is_referenceable()

}

fn schema_name() -> String {

String::schema_name()

}

fn schema_id() -> std::borrow::Cow<'static, str> {

String::schema_id()

}

fn json_schema(generator: &mut schemars::r#gen::SchemaGenerator) -> schemars::schema::Schema {

String::json_schema(generator)

}

fn _schemars_private_non_optional_json_schema(

generator: &mut schemars::r#gen::SchemaGenerator,

) -> schemars::schema::Schema {

String::_schemars_private_non_optional_json_schema(generator)

}

TaKO8Ki · 2025-10-17T18:11:35Z

ruff.schema.json

@@ -1185,7 +1175,7 @@
            "null"
          ],
          "items": {
-            "type": "string"
+            "$ref": "#/$defs/string"


Same as below.

#20942 (comment)

TaKO8Ki · 2025-10-17T18:12:06Z

ty.schema.json

+    "string": {
+      "type": "string"


This is related to #20942 (comment)

TaKO8Ki · 2025-10-17T18:13:03Z

ruff.schema.json

        }
      ]
+    },
+    "string": {
+      "type": "string"


This is related to #20942 (comment).

TaKO8Ki · 2025-10-17T18:25:53Z

ty.schema.json

+          "description": "The root of the project, used for finding first-party modules.\n\nIf left unspecified, ty will try to detect common project layouts and initialize `src.root` accordingly:\n\n* if a `./src` directory exists, include `.` and `./src` in the first party search path (src layout or flat)\n* if a `./<project-name>/<project-name>` directory exists, include `.` and `./<project-name>` in the first party search path\n* otherwise, default to `.` (flat layout)\n\nBesides, if a `./tests` directory exists and is not a package (i.e. it does not contain an `__init__.py` file),\nit will also be included in the first party search path.",
+          "anyOf": [
+            {
+              "$ref": "#/$defs/RelativePathBuf"


With Schemars 1.0 (defaulting to JSON Schema 2020-12), named newtypes are emitted as reusable $refs in #/$defs by default, even when #[serde(transparent)] makes their schema equal to the inner field. This preserves type identity and deduplicates shared shapes.

ruff/crates/ty_project/src/metadata/value.rs

Lines 330 to 332 in c424007

#[serde(transparent)]

#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]

pub struct RelativePathBuf(RangedValue<SystemPathBuf>);

TaKO8Ki · 2025-10-17T18:26:39Z

ty.schema.json

+    "SystemPathBuf": {
+      "description": "An owned, mutable path on [`System`](`super::System`) (akin to [`String`]).\n\nThe path is guaranteed to be valid UTF-8.",
+      "type": "string"
+    },


This is related to #20942 (comment).

MichaReiser · 2025-10-19T10:25:25Z

ty.schema.json

        {
          "type": "string",
-          "pattern": "^\\d+\\.\\d+$"
+          "pattern": "^\\\\d+\\\\.\\\\d+$"


The escaping here looks incorrect to me

MichaReiser · 2025-10-19T10:34:26Z

crates/ruff_python_ast/src/name.rs

-
-    fn schema_name() -> String {
-        String::schema_name()
+    fn schema_name() -> std::borrow::Cow<'static, str> {


I think we could replace this with

#[cfg_attr( feature = "serde", derive(serde::Serialize, serde::Deserialize), serde(transparent) )] #[cfg_attr(feature = "cache", derive(ruff_macros::CacheKey))] #[cfg_attr(feature = "salsa", derive(salsa::Update))] #[cfg_attr(feature = "get-size", derive(get_size2::GetSize))] #[cfg_attr( feature = "schemars", derive(schemars::JsonSchema), schemars(with = "String") )]

(serde(transparent) and schemars(with="String"))

MichaReiser · 2025-10-19T10:35:34Z

crates/ruff_python_ast/src/python_version.rs

+            let string_with_pattern = schemars::json_schema!({
+                "type": "string",
+                "pattern": r"^\\d+\\.\\d+$",
+            });
+
+            let mut any_of: Vec<Value> = Vec::new();
+            any_of.push(string_with_pattern.into());


Nit

Suggested change

let string_with_pattern = schemars::json_schema!({

"type": "string",

"pattern": r"^\\d+\\.\\d+$",

});

let mut any_of: Vec<Value> = Vec::new();

any_of.push(string_with_pattern.into());

let mut any_of: Vec<Value> = vec![

schemars::json_schema!({

"type": "string",

"pattern": r"^\\d+\\.\\d+$",

})

];

MichaReiser · 2025-10-19T10:37:35Z

crates/ruff_workspace/src/options.rs

+    per_file_ignores: Option<BTreeMap<String, Vec<RuleSelector>>>,
+    extend_per_file_ignores: Option<BTreeMap<String, Vec<RuleSelector>>>,


What's the reason for changing those fields to a BTreeMap?

MichaReiser · 2025-10-19T10:38:18Z

crates/ty_project/src/metadata/options.rs

    }
 }

+#[cfg(feature = "schemars")]


Nit: I'd prefer to keep this in its own mod (and in the same position, it makes attributing changes with git easier)

What I want to do is implementing JsonSchema for Rules instead of schemars(with = "schema::Rules"), so I will keep the mod and implement it inside the module.

MichaReiser · 2025-10-19T10:39:43Z

crates/ty_python_semantic/src/python_platform.rs

-                        // Promote well-known values for better auto-completion.
-                        // Using `const` over `enumValues` as recommended [here](https://github.com/SchemaStore/schemastore/blob/master/CONTRIBUTING.md#documenting-enums).


Can we preserve this comment

MichaReiser · 2025-10-19T10:41:53Z

ruff.schema.json

@@ -1,15 +1,15 @@
 {
-  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",


SchemaStore's recommendation is to still use draft-07 because many editors lack support for newer drafts, see

We recommend using the draft-07 JSON schema version. Later versions of JSON Schema are not yet recommended for use in SchemaStore until IDE and language support improves for those versions.

https://github.com/SchemaStore/schemastore/blob/master/CONTRIBUTING.md#best-practices

That's why I think we should not change the schema version as part of this PR

Ok. It's also possible to continue to use draft-07. I will replace the schema version.

MichaReiser

Thank you. This looks great overall. My only concern is the bump of the schema version. SchemaStore recommends draft-07 for best editor compatibility. I suggest we defer the schema version bump as it requires extensive testing across editors.

update ty schema

TaKO8Ki · 2025-10-20T06:54:43Z

@MichaReiser Thank you for the review. I have addressed your comments!

MichaReiser · 2025-10-20T06:58:36Z

This is great. Thank you so much!

TaKO8Ki force-pushed the schemars-v1-upgrade branch from 128d5b2 to 2ce146a Compare October 17, 2025 15:45

TaKO8Ki force-pushed the schemars-v1-upgrade branch from 2ce146a to 66af9fe Compare October 17, 2025 15:53

TaKO8Ki force-pushed the schemars-v1-upgrade branch from 66af9fe to 2244ab2 Compare October 17, 2025 17:39

TaKO8Ki commented Oct 17, 2025

View reviewed changes

TaKO8Ki marked this pull request as ready for review October 17, 2025 18:27

TaKO8Ki requested review from AlexWaygood, MichaReiser, carljm, dcreager and sharkdp as code owners October 17, 2025 18:27

AlexWaygood removed their request for review October 17, 2025 18:36

TaKO8Ki force-pushed the schemars-v1-upgrade branch 2 times, most recently from 4cabd1e to 7c5b4d4 Compare October 18, 2025 16:20

MichaReiser reviewed Oct 19, 2025

View reviewed changes

MichaReiser added the internal An internal refactor or improvement label Oct 19, 2025

TaKO8Ki added 4 commits October 20, 2025 15:39

update schemars to v1

8e67af9

update ty schema

use draft07

e84a8f0

preserve a comment

8b53c95

remove unnecessary attrs

7711a64

TaKO8Ki force-pushed the schemars-v1-upgrade branch from 065b5e4 to 7711a64 Compare October 20, 2025 06:47

MichaReiser merged commit 48b5012 into astral-sh:main Oct 20, 2025
39 of 42 checks passed

TaKO8Ki deleted the schemars-v1-upgrade branch October 20, 2025 07:00

	/// Additional names to ignore when considering `flake8-self` violations,
	/// in addition to those included in [`ignore-names`](#lint_flake8-self_ignore-names).
	#[option(
	default = r#"[]"#,
	value_type = "list[str]",
	example = r#"extend-ignore-names = ["_base_manager", "_default_manager", "_meta"]"#
	)]
	pub extend_ignore_names: Option<Vec<Name>>,

	/// A list of names to ignore when considering `flake8-self` violations.
	#[option(
	default = r#"["_make", "_asdict", "_replace", "_fields", "_field_defaults", "_name_", "_value_"]"#,
	value_type = "list[str]",
	example = r#"
	ignore-names = ["_new"]
	"#
	)]
	pub ignore_names: Option<Vec<Name>>,

	#[cfg(feature = "schemars")]
	impl schemars::JsonSchema for Name {
	fn is_referenceable() -> bool {
	String::is_referenceable()
	}

	fn schema_name() -> String {
	String::schema_name()
	}

	fn schema_id() -> std::borrow::Cow<'static, str> {
	String::schema_id()
	}

	fn json_schema(generator: &mut schemars::r#gen::SchemaGenerator) -> schemars::schema::Schema {
	String::json_schema(generator)
	}

	fn _schemars_private_non_optional_json_schema(
	generator: &mut schemars::r#gen::SchemaGenerator,
	) -> schemars::schema::Schema {
	String::_schemars_private_non_optional_json_schema(generator)
	}

	#[serde(transparent)]
	#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
	pub struct RelativePathBuf(RangedValue<SystemPathBuf>);

		per_file_ignores: Option<BTreeMap<String, Vec<RuleSelector>>>,
		extend_per_file_ignores: Option<BTreeMap<String, Vec<RuleSelector>>>,

		// Promote well-known values for better auto-completion.
		// Using `const` over `enumValues` as recommended [here](https://github.com/SchemaStore/schemastore/blob/master/CONTRIBUTING.md#documenting-enums).

[ruff] Update schemars to v1 #20942

[ruff] Update schemars to v1 #20942

Conversation

TaKO8Ki commented Oct 17, 2025 • edited by MichaReiser Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Shared Changes

ty.schema.json

Test Plan

Uh oh!

github-actions bot commented Oct 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Diagnostic diff on typing conformance tests

Uh oh!

github-actions bot commented Oct 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

mypy_primer results

Uh oh!

github-actions bot commented Oct 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

ruff-ecosystem results

Linter (stable)

Linter (preview)

Formatter (stable)

Formatter (preview)

Uh oh!

TaKO8Ki Oct 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

TaKO8Ki Oct 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

TaKO8Ki Oct 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

TaKO8Ki Oct 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

TaKO8Ki Oct 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

MichaReiser left a comment

Choose a reason for hiding this comment

Uh oh!

TaKO8Ki commented Oct 20, 2025

Uh oh!

MichaReiser commented Oct 20, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

[`ruff`] Update schemars to v1 #20942

[`ruff`] Update schemars to v1 #20942

TaKO8Ki commented Oct 17, 2025 •

edited by MichaReiser

Loading

github-actions bot commented Oct 17, 2025 •

edited

Loading

github-actions bot commented Oct 17, 2025 •

edited

Loading

`mypy_primer` results

github-actions bot commented Oct 17, 2025 •

edited

Loading

`ruff-ecosystem` results

TaKO8Ki Oct 17, 2025 •

edited

Loading

TaKO8Ki Oct 17, 2025 •

edited

Loading

TaKO8Ki Oct 17, 2025 •

edited

Loading

TaKO8Ki Oct 17, 2025 •

edited

Loading

TaKO8Ki Oct 17, 2025 •

edited

Loading