Skip to content

Commit 34a448e

Browse files
priethorpriethor
authored
JSON Schemas: Add Options Pages schema (#270)
1 parent e3f9e67 commit 34a448e

File tree

4 files changed

+754
-0
lines changed

4 files changed

+754
-0
lines changed

‎schemas/ui-options-page.schema.json‎

Lines changed: 187 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
{
2+
"$schema": "http://json-schema.org/draft-07/schema#",
3+
"$id": "https://raw.githubusercontent.com/WordPress/secure-custom-fields/trunk/schemas/ui-options-page.schema.json",
4+
"title": "SCF UI Options Page(s)",
5+
"description": "Schema for Secure Custom Fields UI Options Page definitions - accepts single object or array. Properties marked '[SCF Export Only]' are preserved during export but not used functionally during import.",
6+
"oneOf": [
7+
{
8+
"description": "Single UI Options Page object",
9+
"$ref": "#/definitions/uiOptionsPage"
10+
},
11+
{
12+
"description": "Array of UI Options Page objects (export format)",
13+
"type": "array",
14+
"items": { "$ref": "#/definitions/uiOptionsPage" },
15+
"minItems": 1
16+
}
17+
],
18+
"definitions": {
19+
"uiOptionsPage": {
20+
"type": "object",
21+
"required": [ "key", "title", "menu_slug" ],
22+
"additionalProperties": false,
23+
"properties": {
24+
"key": {
25+
"type": "string",
26+
"pattern": "^ui_options_page_.+$",
27+
"minLength": 1,
28+
"description": "Unique identifier for the options page with ui_options_page_ prefix (e.g. 'ui_options_page_site_settings')"
29+
},
30+
"title": {
31+
"type": "string",
32+
"minLength": 1,
33+
"maxLength": 255,
34+
"description": "The title/name of the options page"
35+
},
36+
"menu_slug": {
37+
"type": "string",
38+
"pattern": "^[a-z0-9_-]+$",
39+
"minLength": 1,
40+
"description": "The menu slug used in the admin URL (e.g. 'site-settings'). Lowercase letters, numbers, underscores, and dashes only."
41+
},
42+
43+
"page_title": {
44+
"type": "string",
45+
"description": "The page title displayed in the browser tab and page heading"
46+
},
47+
"parent_slug": {
48+
"type": "string",
49+
"description": "The parent menu slug. Use 'none' for top-level menu, or a WordPress admin menu slug (e.g. 'options-general.php') for submenu."
50+
},
51+
"menu_title": {
52+
"type": "string",
53+
"description": "The title displayed in the admin menu"
54+
},
55+
56+
"active": {
57+
"type": "boolean",
58+
"default": true,
59+
"description": "[SCF] Whether this options page is active"
60+
},
61+
"advanced_configuration": {
62+
"type": [ "boolean", "integer" ],
63+
"default": false,
64+
"description": "[SCF Export Only] Whether advanced configuration options are enabled. Accepts boolean or integer (0/1)."
65+
},
66+
"import_source": {
67+
"type": "string",
68+
"description": "[SCF Export Only] Source of import if this options page was imported"
69+
},
70+
"import_date": {
71+
"type": "string",
72+
"description": "[SCF Export Only] Date when this options page was imported"
73+
},
74+
"modified": {
75+
"type": "integer",
76+
"minimum": 0,
77+
"description": "[SCF Export Only] Unix timestamp of last modification"
78+
},
79+
"menu_order": {
80+
"type": "integer",
81+
"minimum": 0,
82+
"default": 0,
83+
"description": "[SCF Export Only] The order of this options page in the admin menu"
84+
},
85+
86+
"icon_url": {
87+
"type": "string",
88+
"description": "[Legacy] Icon URL or dashicon class. Prefer menu_icon object format for new configurations."
89+
},
90+
"menu_icon": {
91+
"oneOf": [
92+
{
93+
"type": "string",
94+
"description": "Icon as string: Dashicon name (e.g. 'dashicons-admin-generic') or full URL to image file"
95+
},
96+
{
97+
"type": "object",
98+
"properties": {
99+
"type": {
100+
"type": "string",
101+
"enum": [ "dashicons", "url", "media_library" ],
102+
"description": "Icon source type: 'dashicons' for WordPress dashicons, 'url' for custom image URL, 'media_library' for media library attachment"
103+
},
104+
"value": {
105+
"type": [ "string", "integer" ],
106+
"description": "The icon value: dashicon class name, image URL, or media library attachment ID"
107+
}
108+
},
109+
"required": [ "type", "value" ],
110+
"additionalProperties": false,
111+
"description": "[SCF] SCF icon object format: {\"type\": \"dashicons\", \"value\": \"dashicons-admin-generic\"}"
112+
}
113+
],
114+
"description": "The menu icon. Can be a string (URL or dashicon name) or SCF object format with type and value properties."
115+
},
116+
"position": {
117+
"type": [ "integer", "string", "null" ],
118+
"description": "The position in the menu where this page should appear. SCF exports as empty string or null when not set, integer when set."
119+
},
120+
"redirect": {
121+
"type": "boolean",
122+
"default": true,
123+
"description": "When child pages exist for this parent page, whether to redirect to the first child page"
124+
},
125+
"description": {
126+
"type": "string",
127+
"description": "A descriptive summary of the options page"
128+
},
129+
130+
"update_button": {
131+
"type": "string",
132+
"description": "The label used for the submit button which updates the fields on the options page"
133+
},
134+
"updated_message": {
135+
"type": "string",
136+
"description": "The message displayed after successfully updating the options page"
137+
},
138+
139+
"capability": {
140+
"type": "string",
141+
"default": "edit_posts",
142+
"description": "The capability required for this menu to be displayed to the user"
143+
},
144+
"data_storage": {
145+
"type": "string",
146+
"enum": [ "options", "post_id" ],
147+
"default": "options",
148+
"description": "Where to store field data. 'options' uses the options table, 'post_id' uses custom storage."
149+
},
150+
"post_id": {
151+
"type": [ "string", "integer" ],
152+
"description": "Custom storage location when data_storage is 'post_id'. Can be a numeric post ID (123) or a string ('user_2')."
153+
},
154+
"autoload": {
155+
"type": "boolean",
156+
"default": false,
157+
"description": "Whether to autoload the options when WordPress loads. Improves performance for frequently accessed options."
158+
}
159+
}
160+
}
161+
},
162+
"examples": [
163+
{
164+
"key": "ui_options_page_site_settings",
165+
"title": "Site Settings",
166+
"menu_slug": "site-settings",
167+
"page_title": "Site Settings",
168+
"parent_slug": "none",
169+
"menu_title": "Site Settings",
170+
"active": true,
171+
"menu_order": 0,
172+
"advanced_configuration": false,
173+
"menu_icon": {
174+
"type": "dashicons",
175+
"value": "dashicons-admin-generic"
176+
},
177+
"position": 80,
178+
"redirect": true,
179+
"description": "Global site configuration options",
180+
"update_button": "Save Settings",
181+
"updated_message": "Settings saved successfully",
182+
"capability": "manage_options",
183+
"data_storage": "options",
184+
"autoload": true
185+
}
186+
]
187+
}

‎tests/php/fixtures/schemas/ui-options-pages/invalid/ui-options-page-wrong-format.json‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
{
2+
"key": "group_theme_settings_options_page",
3+
"title": "Theme Settings",
4+
"type": "options_page",
5+
"menu_slug": "theme-settings",
6+
"menu_title": "Theme Settings",
7+
"parent_slug": "",
8+
"position": "",
9+
"icon_url": "",
10+
"redirect": false,
11+
"post_id": "option",
12+
"autoload": false,
13+
"capability": "manage_options",
14+
"updated_at": "2025-12-03 00:00:00"
15+
}

‎tests/php/fixtures/schemas/ui-options-pages/valid/site-settings-export.json‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
{
2+
"key": "ui_options_page_682abc123def",
3+
"title": "Site Settings",
4+
"menu_order": 0,
5+
"active": true,
6+
"page_title": "Site Settings",
7+
"menu_slug": "site-settings",
8+
"parent_slug": "none",
9+
"advanced_configuration": 0,
10+
"import_source": "",
11+
"import_date": "",
12+
"icon_url": "",
13+
"menu_title": "Site Settings",
14+
"position": 80,
15+
"redirect": true,
16+
"description": "Global site configuration options",
17+
"menu_icon": {
18+
"type": "dashicons",
19+
"value": "dashicons-admin-generic"
20+
},
21+
"update_button": "Save Settings",
22+
"updated_message": "Settings saved successfully",
23+
"capability": "manage_options",
24+
"data_storage": "options",
25+
"post_id": "",
26+
"autoload": true
27+
}

0 commit comments

Comments
 (0)