Skip to content

Commit 5989e98

Browse files
nickpeihlnickpeihl
committed
Add descriptions to schemas
1 parent d264710 commit 5989e98

File tree

3 files changed

+113
-70
lines changed

3 files changed

+113
-70
lines changed

‎src/platform/packages/shared/kbn-es-query-server/index.ts‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,6 @@ export type {
2424
SimpleFilterCondition,
2525
FilterGroup,
2626
RawDSLFilter,
27-
FilterOperator,
2827
FilterValue,
2928
RangeValue,
3029
StoredFilterState,

‎src/platform/packages/shared/kbn-es-query-server/src/filter/simplified_filter.ts‎

Lines changed: 113 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -10,10 +10,7 @@
1010
/**
1111
* Validation Schemas for Simplified Filter Interface
1212
*
13-
* This module provides @kbn/config-schema validation schemas that correspond
14-
* to the TypeScript types defined in simplified_filter_types.ts.
15-
*
16-
* These schemas are used for runtime validation of API requests and responses
13+
* These schemas are used for server validation of API requests and responses
1714
* in * as Code APIs.
1815
*/
1916

@@ -23,40 +20,46 @@ import { schema } from '@kbn/config-schema';
2320
// CORE FILTER OPERATOR AND VALUE SCHEMAS
2421
// ====================================================================
2522

26-
/**
27-
* Schema for supported filter operators
28-
*/
29-
export const filterOperatorSchema = schema.oneOf([
30-
schema.literal('is'),
31-
schema.literal('is_not'),
32-
schema.literal('is_one_of'),
33-
schema.literal('is_not_one_of'),
34-
schema.literal('exists'),
35-
schema.literal('not_exists'),
36-
schema.literal('range'),
37-
]);
38-
3923
/**
4024
* Schema for range values used in numeric and date filters
4125
*/
4226
export const rangeValueSchema = schema.object({
43-
gte: schema.maybe(schema.oneOf([schema.number(), schema.string()])),
44-
lte: schema.maybe(schema.oneOf([schema.number(), schema.string()])),
45-
gt: schema.maybe(schema.oneOf([schema.number(), schema.string()])),
46-
lt: schema.maybe(schema.oneOf([schema.number(), schema.string()])),
27+
gte: schema.maybe(
28+
schema.oneOf([schema.number(), schema.string()], {
29+
meta: { description: 'Greater than or equal to' },
30+
})
31+
),
32+
lte: schema.maybe(
33+
schema.oneOf([schema.number(), schema.string()], {
34+
meta: { description: 'Less than or equal to' },
35+
})
36+
),
37+
gt: schema.maybe(
38+
schema.oneOf([schema.number(), schema.string()], {
39+
meta: { description: 'Greater than' },
40+
})
41+
),
42+
lt: schema.maybe(
43+
schema.oneOf([schema.number(), schema.string()], {
44+
meta: { description: 'Less than' },
45+
})
46+
),
4747
});
4848

4949
/**
5050
* Schema for all possible filter values
5151
* Supports single values, arrays, and range objects
5252
*/
53-
export const filterValueSchema = schema.oneOf([
54-
schema.string(),
55-
schema.number(),
56-
schema.boolean(),
57-
schema.arrayOf(schema.oneOf([schema.string(), schema.number(), schema.boolean()])),
58-
rangeValueSchema,
59-
]);
53+
export const filterValueSchema = schema.oneOf(
54+
[
55+
schema.string(),
56+
schema.number(),
57+
schema.boolean(),
58+
schema.arrayOf(schema.oneOf([schema.string(), schema.number(), schema.boolean()])),
59+
rangeValueSchema,
60+
],
61+
{ meta: { description: 'Possible filter values that could be single values, arrays, or ranges' } }
62+
);
6063

6164
// ====================================================================
6265
// BASE FILTER PROPERTIES (SHARED BY ALL SIMPLIFIED FILTERS)
@@ -66,13 +69,41 @@ export const filterValueSchema = schema.oneOf([
6669
* Base properties shared by all simplified filters
6770
*/
6871
const baseFilterPropertiesSchema = {
69-
id: schema.maybe(schema.string()),
70-
pinned: schema.maybe(schema.boolean()),
71-
disabled: schema.maybe(schema.boolean()),
72-
controlledBy: schema.maybe(schema.string()),
73-
indexPattern: schema.maybe(schema.string()),
74-
negate: schema.maybe(schema.boolean()),
75-
label: schema.maybe(schema.string()),
72+
id: schema.maybe(
73+
schema.string({
74+
meta: { description: 'Unique identifier for the filter' },
75+
})
76+
),
77+
pinned: schema.maybe(
78+
schema.boolean({
79+
meta: { description: 'Whether the filter is pinned' },
80+
})
81+
),
82+
disabled: schema.maybe(
83+
schema.boolean({
84+
meta: { description: 'Whether the filter is disabled' },
85+
})
86+
),
87+
controlledBy: schema.maybe(
88+
schema.string({
89+
meta: { description: 'Owner that manages this filter' },
90+
})
91+
),
92+
indexPattern: schema.maybe(
93+
schema.string({
94+
meta: { description: 'Data view ID that this filter applies to' },
95+
})
96+
),
97+
negate: schema.maybe(
98+
schema.boolean({
99+
meta: { description: 'Whether to negate the filter condition' },
100+
})
101+
),
102+
label: schema.maybe(
103+
schema.string({
104+
meta: { description: 'Human-readable label for the filter' },
105+
})
106+
),
76107
};
77108

78109
// ====================================================================
@@ -83,7 +114,7 @@ const baseFilterPropertiesSchema = {
83114
* Base schema for simple filter conditions
84115
*/
85116
const baseFilterConditionSchema = {
86-
field: schema.string(),
117+
field: schema.string({ meta: { description: 'Field the filter applies to' } }),
87118
};
88119

89120
// ====================================================================
@@ -95,13 +126,16 @@ const baseFilterConditionSchema = {
95126
*/
96127
export const filterConditionWithValueSchema = schema.object({
97128
...baseFilterConditionSchema,
98-
operator: schema.oneOf([
99-
schema.literal('is'),
100-
schema.literal('is_not'),
101-
schema.literal('is_one_of'),
102-
schema.literal('is_not_one_of'),
103-
schema.literal('range'),
104-
]),
129+
operator: schema.oneOf(
130+
[
131+
schema.literal('is'),
132+
schema.literal('is_not'),
133+
schema.literal('is_one_of'),
134+
schema.literal('is_not_one_of'),
135+
schema.literal('range'),
136+
],
137+
{ meta: { description: 'Filter operators that require a value' } }
138+
),
105139
value: filterValueSchema,
106140
});
107141

@@ -110,17 +144,19 @@ export const filterConditionWithValueSchema = schema.object({
110144
*/
111145
export const filterConditionExistsSchema = schema.object({
112146
...baseFilterConditionSchema,
113-
operator: schema.oneOf([schema.literal('exists'), schema.literal('not_exists')]),
147+
operator: schema.oneOf([schema.literal('exists'), schema.literal('not_exists')], {
148+
meta: { description: 'Filter operators that check existence' },
149+
}),
114150
// value is intentionally omitted for exists/not_exists operators
115151
});
116152

117153
/**
118154
* Discriminated union schema for simple filter conditions
119155
*/
120-
export const simpleFilterConditionSchema = schema.oneOf([
121-
filterConditionWithValueSchema,
122-
filterConditionExistsSchema,
123-
]);
156+
export const simpleFilterConditionSchema = schema.oneOf(
157+
[filterConditionWithValueSchema, filterConditionExistsSchema],
158+
{ meta: { description: 'A filter condition' } }
159+
);
124160

125161
// ====================================================================
126162
// FILTER GROUP SCHEMA (RECURSIVE)
@@ -141,7 +177,7 @@ export const filterGroupSchema = schema.object(
141177
])
142178
),
143179
},
144-
{ meta: { id: 'filterGroup' } }
180+
{ meta: { description: 'Grouped filters', id: 'filterGroup' } }
145181
);
146182

147183
// ====================================================================
@@ -152,7 +188,9 @@ export const filterGroupSchema = schema.object(
152188
* Schema for raw Elasticsearch Query DSL filters
153189
*/
154190
export const rawDSLFilterSchema = schema.object({
155-
query: schema.recordOf(schema.string(), schema.any()),
191+
query: schema.recordOf(schema.string(), schema.any(), {
192+
meta: { description: 'Elasticsearch Query DSL object' },
193+
}),
156194
});
157195

158196
// ====================================================================
@@ -162,33 +200,41 @@ export const rawDSLFilterSchema = schema.object({
162200
/**
163201
* Schema for simple condition filters (Tier 1)
164202
*/
165-
export const simplifiedConditionFilterSchema = schema.object({
166-
...baseFilterPropertiesSchema,
167-
condition: simpleFilterConditionSchema,
168-
});
203+
export const simplifiedConditionFilterSchema = schema.object(
204+
{
205+
...baseFilterPropertiesSchema,
206+
condition: simpleFilterConditionSchema,
207+
},
208+
{ meta: { description: 'Simple condition filter' } }
209+
);
169210

170211
/**
171212
* Schema for grouped condition filters (Tier 2-3)
172213
*/
173-
export const simplifiedGroupFilterSchema = schema.object({
174-
...baseFilterPropertiesSchema,
175-
group: filterGroupSchema,
176-
});
214+
export const simplifiedGroupFilterSchema = schema.object(
215+
{
216+
...baseFilterPropertiesSchema,
217+
group: filterGroupSchema,
218+
},
219+
{ meta: { description: 'Grouped condition filter' } }
220+
);
177221

178222
/**
179223
* Schema for raw DSL filters (Tier 4)
180224
*/
181-
export const simplifiedDSLFilterSchema = schema.object({
182-
...baseFilterPropertiesSchema,
183-
dsl: rawDSLFilterSchema,
184-
});
225+
export const simplifiedDSLFilterSchema = schema.object(
226+
{
227+
...baseFilterPropertiesSchema,
228+
dsl: rawDSLFilterSchema,
229+
},
230+
{ meta: { description: 'Raw DSL filter' } }
231+
);
185232

186233
/**
187234
* Main discriminated union schema for SimplifiedFilter
188235
* Ensures exactly one of: condition, group, or dsl is present
189236
*/
190-
export const simplifiedFilterSchema = schema.oneOf([
191-
simplifiedConditionFilterSchema,
192-
simplifiedGroupFilterSchema,
193-
simplifiedDSLFilterSchema,
194-
]);
237+
export const simplifiedFilterSchema = schema.oneOf(
238+
[simplifiedConditionFilterSchema, simplifiedGroupFilterSchema, simplifiedDSLFilterSchema],
239+
{ meta: { description: 'A filter which can be a condition, group, or raw DSL' } }
240+
);

‎src/platform/packages/shared/kbn-es-query-server/src/types.ts‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,6 @@ import type {
2626
simpleFilterConditionSchema,
2727
filterGroupSchema,
2828
rawDSLFilterSchema,
29-
filterOperatorSchema,
3029
filterValueSchema,
3130
rangeValueSchema,
3231
} from './filter/simplified_filter';
@@ -50,7 +49,6 @@ export type SimplifiedFilter = Writable<TypeOf<typeof simplifiedFilterSchema>>;
5049
export type SimpleFilterCondition = Writable<TypeOf<typeof simpleFilterConditionSchema>>;
5150
export type FilterGroup = Writable<TypeOf<typeof filterGroupSchema>>;
5251
export type RawDSLFilter = Writable<TypeOf<typeof rawDSLFilterSchema>>;
53-
export type FilterOperator = Writable<TypeOf<typeof filterOperatorSchema>>;
5452
export type FilterValue = Writable<TypeOf<typeof filterValueSchema>>;
5553
export type RangeValue = Writable<TypeOf<typeof rangeValueSchema>>;
5654
export type StoredFilterState = TypeOf<typeof appStateSchema> | TypeOf<typeof globalStateSchema>;

0 commit comments

Comments
 (0)