jsonschema_schema/extensions/
taplo.rs

1use alloc::collections::BTreeMap;
2
3use serde::{Deserialize, Serialize};
4use serde_json::Value;
5
6/// [Taplo] JSON Schema extension (`x-taplo`).
7///
8/// Controls editor behavior in the Taplo TOML language server: documentation
9/// text, completion links, hidden fields, and plugins. Serialized as a
10/// single nested JSON object under the `x-taplo` key.
11///
12/// Compatible with [`taplo-common`'s `SchemaExt`][taplo-ext].
13///
14/// # Example
15///
16/// ```json
17/// {
18///   "x-taplo": {
19///     "hidden": true,
20///     "docs": { "main": "Override description" },
21///     "links": { "key": "https://example.com" }
22///   }
23/// }
24/// ```
25///
26/// [Taplo]: https://taplo.tamasfe.dev
27/// [taplo-ext]: https://github.com/tamasfe/taplo/blob/main/crates/taplo-common/src/schema/ext.rs
28#[derive(
29    Debug, Default, Clone, Serialize, Deserialize, PartialEq, Eq, Hash, schemars::JsonSchema,
30)]
31#[serde(rename_all = "camelCase")]
32pub struct TaploSchemaExt {
33    /// When `true`, the property is hidden from completion suggestions.
34    #[serde(skip_serializing_if = "Option::is_none")]
35    pub hidden: Option<bool>,
36
37    /// Navigation link targets shown as clickable references in the editor.
38    #[serde(skip_serializing_if = "Option::is_none")]
39    pub links: Option<ExtLinks>,
40
41    /// Documentation text overrides for hover popups and completion details.
42    #[serde(skip_serializing_if = "Option::is_none")]
43    pub docs: Option<ExtDocs>,
44
45    /// Keys to insert when creating a new table from this schema.
46    #[serde(skip_serializing_if = "Option::is_none")]
47    pub init_keys: Option<Vec<String>>,
48
49    /// Taplo plugin names to activate when this schema is in use.
50    #[serde(default, skip_serializing_if = "Vec::is_empty")]
51    pub plugins: Vec<String>,
52    #[serde(flatten)]
53    pub extra: BTreeMap<String, Value>,
54}
55
56/// Documentation text overrides for [Taplo](TaploSchemaExt) hover and
57/// completion.
58///
59/// Each field replaces the corresponding auto-generated documentation
60/// that Taplo would otherwise derive from the schema.
61#[derive(
62    Debug, Default, Clone, Serialize, Deserialize, PartialEq, Eq, Hash, schemars::JsonSchema,
63)]
64#[serde(rename_all = "camelCase")]
65pub struct ExtDocs {
66    /// Primary documentation text, replacing the schema `description`.
67    #[serde(skip_serializing_if = "Option::is_none")]
68    pub main: Option<String>,
69
70    /// Documentation for the `const` value.
71    #[serde(skip_serializing_if = "Option::is_none")]
72    pub const_value: Option<String>,
73
74    /// Documentation for the `default` value.
75    #[serde(skip_serializing_if = "Option::is_none")]
76    pub default_value: Option<String>,
77
78    /// Per-enum-value documentation strings (positional, matching the
79    /// `enum` array). `None` entries leave the default text unchanged.
80    #[serde(skip_serializing_if = "Option::is_none")]
81    pub enum_values: Option<Vec<Option<String>>>,
82}
83
84/// Link targets for [Taplo](TaploSchemaExt) navigation.
85///
86/// Provides clickable URLs in the editor for the property key and
87/// individual enum values.
88#[derive(
89    Debug, Default, Clone, Serialize, Deserialize, PartialEq, Eq, Hash, schemars::JsonSchema,
90)]
91#[serde(rename_all = "camelCase")]
92pub struct ExtLinks {
93    /// URL to navigate to when clicking the property key.
94    #[serde(skip_serializing_if = "Option::is_none")]
95    pub key: Option<String>,
96
97    /// Per-enum-value link URLs (positional, matching the `enum` array).
98    /// `None` entries have no link.
99    #[serde(skip_serializing_if = "Option::is_none")]
100    pub enum_values: Option<Vec<Option<String>>>,
101}
102
103/// [Taplo] schema catalog metadata (`x-taplo-info`).
104///
105/// Embeds file-association patterns, authorship, and version information
106/// directly inside a schema file. Used by Taplo's built-in catalog to
107/// match schemas to TOML files without a separate catalog entry.
108///
109/// Compatible with [`taplo-common`'s `SchemaExtraInfo`][taplo-info].
110///
111/// # Example
112///
113/// ```json
114/// {
115///   "x-taplo-info": {
116///     "authors": ["Alice (https://example.com)"],
117///     "version": "1.0.0",
118///     "patterns": ["^pyproject\\.toml$"]
119///   }
120/// }
121/// ```
122///
123/// [Taplo]: https://taplo.tamasfe.dev
124/// [taplo-info]: https://github.com/tamasfe/taplo/blob/main/crates/taplo-common/src/schema/ext.rs
125#[derive(Debug, Default, Clone, PartialEq, Eq, Serialize, Deserialize, schemars::JsonSchema)]
126pub struct TaploInfoSchemaExt {
127    /// Schema author credits, typically `"Name (url)"`.
128    #[serde(default, skip_serializing_if = "Vec::is_empty")]
129    pub authors: Vec<String>,
130
131    /// Semver version of the schema or the tool it describes.
132    #[serde(skip_serializing_if = "Option::is_none")]
133    pub version: Option<String>,
134
135    /// Regex patterns matching file paths this schema applies to.
136    #[serde(default, skip_serializing_if = "Vec::is_empty")]
137    pub patterns: Vec<String>,
138}
jsonschema_schema/extensions/taplo.rs

jsonschema_schema/extensions/
taplo.rs
