satay_codegen/error/
validation.rs

1use oas3::spec::ExtensionError;
2use serde::de::Error as SerdeError;
3
4/// Errors that can occur while validating an OpenAPI document.
5///
6/// This enum is [`non_exhaustive`](https://doc.rust-lang.org/reference/attributes/type_system.html)
7/// so new variants may be added in future releases without a semver break.
8#[derive(Debug, thiserror::Error)]
9#[non_exhaustive]
10pub enum ValidationError {
11    // -- Document and component shape validation --
12    /// The OpenAPI version is not supported.
13    ///
14    /// Error message: `unsupported OpenAPI version `{version}`; Satay supports OpenAPI 3.1`
15    #[error("unsupported OpenAPI version `{version}`; Satay supports OpenAPI 3.1")]
16    UnsupportedOpenApiVersion { version: String },
17
18    /// A schema component uses a type that is not supported.
19    ///
20    /// Error message: `unsupported type `{kind}` in schema `{schema}``
21    #[error("unsupported type `{kind}` in schema `{schema}`")]
22    UnsupportedComponentType { schema: String, kind: String },
23
24    /// A schema component is missing a required `type`, `$ref`, `enum`, or `properties` declaration.
25    ///
26    /// Error message: `schema `{schema}` must declare `type`, `$ref`, `enum`, or `properties``
27    #[error("schema `{schema}` must declare `type`, `$ref`, `enum`, or `properties`")]
28    MissingComponentSchemaType { schema: String },
29
30    /// An object schema is missing the required `properties` field.
31    ///
32    /// Error message: `object schema `{schema}` must declare `properties``
33    #[error("object schema `{schema}` must declare `properties`")]
34    MissingObjectProperties { schema: String },
35
36    /// The OpenAPI document is missing the required `paths` field.
37    ///
38    /// Error message: `OpenAPI document must declare `paths``
39    #[error("OpenAPI document must declare `paths`")]
40    MissingPaths,
41
42    // -- Enum and schema type validation --
43    /// A schema uses an enum with a non-string type.
44    ///
45    /// Error message: `{context} uses enum type `{kind}`; only string enums are supported`
46    #[error("{context} uses enum type `{kind}`; only string enums are supported")]
47    UnsupportedEnumType { context: String, kind: String },
48
49    /// A schema declares an enum that is not an array.
50    ///
51    /// Error message: `{context} has a non-array enum`
52    #[error("{context} has a non-array enum")]
53    NonArrayEnum { context: String },
54
55    /// A schema declares an enum with no values.
56    ///
57    /// Error message: `{context} has an empty enum`
58    #[error("{context} has an empty enum")]
59    EmptyEnum { context: String },
60
61    /// A schema enum contains a non-string value.
62    ///
63    /// Error message: `{context} contains a non-string enum value; only string enums are supported`
64    #[error("{context} contains a non-string enum value; only string enums are supported")]
65    NonStringEnumValue { context: String },
66
67    /// A schema declares a `const` value that is not one of its `enum` values.
68    ///
69    /// Error message: `{context} declares a `const` value that is not in its `enum``
70    #[error("{context} declares a `const` value that is not in its `enum`")]
71    ConstNotInEnum { context: String },
72
73    /// A typed specification extension could not be deserialized.
74    ///
75    /// Error message: `{context}: failed to deserialize specification extension at `{path}`: {source}`
76    #[error("{context}: failed to deserialize specification extension at `{path}`: {source}")]
77    InvalidExtension {
78        context: String,
79        path: String,
80        source: serde_json::Error,
81    },
82
83    /// An `x-satay.enum-variants` entry points at a value that is not in the enum.
84    ///
85    /// Error message: `{context}.x-satay.enum-variants contains `{wire_name}`, which is not declared in the enum`
86    #[error(
87        "{context}.x-satay.enum-variants contains `{wire_name}`, which is not declared in the enum"
88    )]
89    UnknownSatayEnumVariantValue { context: String, wire_name: String },
90
91    /// An `x-satay.enum-variants` entry uses a name reserved for generated fallback variants.
92    ///
93    /// Error message: `{context}.x-satay.enum-variants[{wire_name:?}] uses reserved fallback variant `{rust_name}``
94    #[error(
95        "{context}.x-satay.enum-variants[{wire_name:?}] uses reserved fallback variant `{rust_name}`"
96    )]
97    ReservedSatayEnumVariantName {
98        context: String,
99        wire_name: String,
100        rust_name: String,
101    },
102
103    /// Two `x-satay.enum-variants` entries produce the same Rust variant name.
104    ///
105    /// Error message: `{context}.x-satay.enum-variants maps multiple values to `{rust_name}``
106    #[error("{context}.x-satay.enum-variants maps multiple values to `{rust_name}`")]
107    DuplicateSatayEnumVariantName { context: String, rust_name: String },
108
109    /// A schema has a `required` field that is not an array.
110    ///
111    /// Error message: `{context} has a non-array `required` field`
112    #[error("{context} has a non-array `required` field")]
113    NonArrayRequired { context: String },
114
115    /// A schema `required` array contains a non-string element.
116    ///
117    /// Error message: `{context} has a non-string required field name`
118    #[error("{context} has a non-string required field name")]
119    NonStringRequiredField { context: String },
120
121    /// An integer schema uses an unsupported format.
122    ///
123    /// Error message: `{context} uses unsupported integer format `{format}``
124    #[error("{context} uses unsupported integer format `{format}`")]
125    UnsupportedIntegerFormat { context: String, format: String },
126
127    /// A number schema uses an unsupported format.
128    ///
129    /// Error message: `{context} uses unsupported number format `{format}``
130    #[error("{context} uses unsupported number format `{format}`")]
131    UnsupportedNumberFormat { context: String, format: String },
132
133    /// `x-satay.parse-as` was applied to an unsupported wire schema.
134    ///
135    /// Error message: `{context} uses x-satay.parse-as `{parse_as}` on `{kind}`; supported parse-as wire schemas are string schemas, plus integer schemas for bool`
136    #[error(
137        "{context} uses x-satay.parse-as `{parse_as}` on `{kind}`; supported parse-as wire schemas are string schemas, plus integer schemas for bool"
138    )]
139    SatayParseAsRequiresString {
140        context: String,
141        parse_as: String,
142        kind: String,
143    },
144
145    /// An `x-satay.none-if` array is empty.
146    ///
147    /// Error message: `{context}.x-satay.none-if must contain at least one string`
148    #[error("{context}.x-satay.none-if must contain at least one string")]
149    EmptySatayNoneIf { context: String },
150
151    /// `x-satay.none-if` was applied outside a struct property.
152    ///
153    /// Error message: `{context} uses x-satay.none-if outside a struct field`
154    #[error("{context} uses x-satay.none-if outside a struct field")]
155    SatayNoneIfRequiresStructField { context: String },
156
157    /// `x-satay.none-if` was not paired with a string-backed parser.
158    ///
159    /// Error message: `{context} uses x-satay.none-if without a string-backed x-satay.parse-as`
160    #[error("{context} uses x-satay.none-if without a string-backed x-satay.parse-as")]
161    SatayNoneIfRequiresParsedString { context: String },
162
163    /// `x-satay.none-if` and `x-satay.treat-error-as-none` were combined.
164    ///
165    /// Error message: `{context} cannot combine x-satay.none-if with x-satay.treat-error-as-none`
166    #[error("{context} cannot combine x-satay.none-if with x-satay.treat-error-as-none")]
167    ConflictingSatayNoneHandling { context: String },
168
169    /// A boolean string mapping was not paired with a string-backed bool parser.
170    ///
171    /// Error message: `{context} uses boolean string mappings without string-backed x-satay.parse-as bool`
172    #[error("{context} uses boolean string mappings without string-backed x-satay.parse-as bool")]
173    SatayBoolMappingRequiresParsedStringBool { context: String },
174
175    /// A boolean string mapping omitted one of its required value lists.
176    ///
177    /// Error message: `{context} must define both x-satay.true-values and x-satay.false-values`
178    #[error("{context} must define both x-satay.true-values and x-satay.false-values")]
179    IncompleteSatayBoolMapping { context: String },
180
181    /// A boolean string mapping contains an empty value list.
182    ///
183    /// Error message: `{context}.x-satay.{keyword} must contain at least one string`
184    #[error("{context}.x-satay.{keyword} must contain at least one string")]
185    EmptySatayBoolMapping {
186        context: String,
187        keyword: &'static str,
188    },
189
190    /// A value appears in both true and false boolean string mappings.
191    ///
192    /// Error message: `{context} maps `{value}` as both true and false`
193    #[error("{context} maps `{value}` as both true and false")]
194    OverlappingSatayBoolMapping { context: String, value: String },
195
196    /// A boolean mapping value is also configured as a null sentinel.
197    ///
198    /// Error message: `{context} maps `{value}` as both a boolean and x-satay.none-if`
199    #[error("{context} maps `{value}` as both a boolean and x-satay.none-if")]
200    OverlappingSatayBoolMappingNoneIf { context: String, value: String },
201
202    /// `x-satay.ignore` was applied outside an object property.
203    ///
204    /// Error message: `{context} uses x-satay.ignore outside an object property`
205    #[error("{context} uses x-satay.ignore outside an object property")]
206    SatayIgnoreRequiresObjectProperty { context: String },
207
208    /// `x-satay.identifier` was applied outside an object property.
209    ///
210    /// Error message: `{context} uses x-satay.identifier outside an object property`
211    #[error("{context} uses x-satay.identifier outside an object property")]
212    SatayIdentifierRequiresObjectProperty { context: String },
213
214    /// An explicit property identifier collides with another Rust field after normalization.
215    ///
216    /// Error message: `{context} maps properties `{first_property}` and `{second_property}` to duplicate Rust field `{rust_name}``
217    #[error(
218        "{context} maps properties `{first_property}` and `{second_property}` to duplicate Rust field `{rust_name}`"
219    )]
220    DuplicateSatayIdentifierRustField {
221        context: String,
222        first_property: String,
223        second_property: String,
224        rust_name: String,
225    },
226
227    /// `x-satay.integer-type` was applied to a non-integer schema.
228    ///
229    /// Error message: `{context} uses x-satay.integer-type `{integer_type}` on `{kind}`; supported integer-type wire schemas are integer schemas and string schemas with x-satay.parse-as integer-range`
230    #[error(
231        "{context} uses x-satay.integer-type `{integer_type}` on `{kind}`; supported integer-type wire schemas are integer schemas and string schemas with x-satay.parse-as integer-range"
232    )]
233    SatayIntegerTypeRequiresInteger {
234        context: String,
235        integer_type: String,
236        kind: String,
237    },
238
239    /// An array schema is missing the required `items` field.
240    ///
241    /// Error message: `{context} array schema must declare `items``
242    #[error("{context} array schema must declare `items`")]
243    MissingArrayItems { context: String },
244
245    /// A schema defines an inline object instead of using a `$ref`.
246    ///
247    /// Error message: `{context} is an inline object schema; move it to components/schemas and use `$ref``
248    #[error("{context} is an inline object schema; move it to components/schemas and use `$ref`")]
249    InlineObjectSchema { context: String },
250
251    /// An object schema has no properties (i.e. acts as a map/dictionary), which is unsupported.
252    ///
253    /// Error message: `{context} is an object with neither `properties` nor a supported `additionalProperties` schema`
254    #[error(
255        "{context} is an object with neither `properties` nor a supported `additionalProperties` schema"
256    )]
257    UnsupportedMapObjectSchema { context: String },
258
259    /// A schema uses an unsupported type.
260    ///
261    /// Error message: `{context} uses unsupported schema type `{kind}``
262    #[error("{context} uses unsupported schema type `{kind}`")]
263    UnsupportedSchemaType { context: String, kind: String },
264
265    /// A schema is missing a required `type`, `$ref`, or `enum` declaration.
266    ///
267    /// Error message: `{context} must declare `type`, `$ref`, or `enum``
268    #[error("{context} must declare `type`, `$ref`, or `enum`")]
269    MissingSchemaType { context: String },
270
271    /// A JSON Schema boolean schema was used; Satay has no IR equivalent yet.
272    ///
273    /// Error message: `{context} is a boolean schema; boolean JSON Schemas are not supported yet`
274    #[error("{context} is a boolean schema; boolean JSON Schemas are not supported yet")]
275    UnsupportedBooleanSchema { context: String },
276
277    /// A schema type array contains more than one non-null type.
278    ///
279    /// Error message: `{context} declares multiple non-null schema types; Satay supports at most one plus null`
280    #[error(
281        "{context} declares multiple non-null schema types; Satay supports at most one plus null"
282    )]
283    MultipleNonNullSchemaTypesUnsupported { context: String },
284
285    /// A schema uses a composition keyword (`allOf`, `anyOf`, `oneOf`) in an unsupported context.
286    ///
287    /// Error message: `{context} uses `{keyword}`, which is not supported in this context`
288    #[error("{context} uses `{keyword}`, which is not supported in this context")]
289    UnsupportedComposition {
290        context: String,
291        keyword: &'static str,
292    },
293
294    /// A schema uses a sibling beside `$ref` that Satay cannot apply.
295    ///
296    /// Error message: `{context} uses unsupported `$ref` sibling `{keyword}``
297    #[error("{context} uses unsupported `$ref` sibling `{keyword}`")]
298    UnsupportedRefSiblingKeyword { context: String, keyword: String },
299
300    /// An `allOf` schema combines supported struct flattening with another schema keyword.
301    ///
302    /// Error message: `{context} uses `allOf` with `{keyword}`; only object branch flattening is supported`
303    #[error("{context} uses `allOf` with `{keyword}`; only object branch flattening is supported")]
304    UnsupportedAllOfSiblingKeyword { context: String, keyword: String },
305
306    /// An `allOf` branch cannot be flattened into a generated Rust struct.
307    ///
308    /// Error message: `{context}.allOf[{index}] must be a local component schema reference or object schema with properties`
309    #[error(
310        "{context}.allOf[{index}] must be a local component schema reference or object schema with properties"
311    )]
312    UnsupportedAllOfBranch { context: String, index: usize },
313
314    /// Two `allOf` branches declare the same object property.
315    ///
316    /// Error message: `{context} declares duplicate `allOf` property `{property}``
317    #[error("{context} declares duplicate `allOf` property `{property}`")]
318    DuplicateAllOfProperty { context: String, property: String },
319
320    /// `allOf` component schemas form a recursive flattening cycle.
321    ///
322    /// Error message: `{context} forms a recursive `allOf` cycle through schema `{schema}``
323    #[error("{context} forms a recursive `allOf` cycle through schema `{schema}`")]
324    RecursiveAllOf { context: String, schema: String },
325
326    /// A discriminator union branch component recursively contains its own union.
327    ///
328    /// Error message: `{context} forms a recursive discriminator cycle through branch schema `{schema}``
329    #[error("{context} forms a recursive discriminator cycle through branch schema `{schema}`")]
330    RecursiveDiscriminatorBranch { context: String, schema: String },
331
332    /// An `anyOf` schema combines a supported union with another schema keyword.
333    ///
334    /// Error message: `{context} uses `anyOf` with `{keyword}`; only annotation siblings are supported`
335    #[error("{context} uses `anyOf` with `{keyword}`; only annotation siblings are supported")]
336    UnsupportedAnyOfSiblingKeyword { context: String, keyword: String },
337
338    /// An `anyOf` branch is not a supported union branch.
339    ///
340    /// Error message: `{context}.anyOf[{index}] must be a local component schema reference, inline string enum, inline primitive schema, or null schema`
341    #[error(
342        "{context}.anyOf[{index}] must be a local component schema reference, inline string enum, inline primitive schema, or null schema"
343    )]
344    UnsupportedAnyOfBranch { context: String, index: usize },
345
346    /// A `oneOf` schema combines a supported union with another schema keyword.
347    ///
348    /// Error message: `{context} uses `oneOf` with `{keyword}`; only annotation siblings are supported`
349    #[error("{context} uses `oneOf` with `{keyword}`; only annotation siblings are supported")]
350    UnsupportedOneOfSiblingKeyword { context: String, keyword: String },
351
352    /// A `oneOf` branch is not a supported union branch.
353    ///
354    /// Error message: `{context}.oneOf[{index}] must be a local component schema reference, inline string enum, inline primitive schema, or null schema`
355    #[error(
356        "{context}.oneOf[{index}] must be a local component schema reference, inline string enum, inline primitive schema, or null schema"
357    )]
358    UnsupportedOneOfBranch { context: String, index: usize },
359
360    /// A plain `anyOf` or `oneOf` union has more than one null branch.
361    ///
362    /// Error message: `{context}.{keyword}[{index}] duplicates the union null branch`
363    #[error("{context}.{keyword}[{index}] duplicates the union null branch")]
364    DuplicateUnionNullBranch {
365        context: String,
366        keyword: &'static str,
367        index: usize,
368    },
369
370    /// An open string enum `anyOf` repeats an enum or `const` value across branches.
371    ///
372    /// Error message: `{context} declares duplicate open string enum value `{value}` across `anyOf` branches`
373    #[error(
374        "{context} declares duplicate open string enum value `{value}` across `anyOf` branches"
375    )]
376    DuplicateOpenStringEnumValue { context: String, value: String },
377
378    /// A nullable plain `anyOf` or `oneOf` union has no non-null branches.
379    ///
380    /// Error message: `{context}.{keyword} must declare at least one non-null branch`
381    #[error("{context}.{keyword} must declare at least one non-null branch")]
382    NullableUnionWithoutVariants {
383        context: String,
384        keyword: &'static str,
385    },
386
387    /// A plain `anyOf` or `oneOf` union has a branch that is statically shadowed by an earlier branch.
388    ///
389    /// Error message: `{context}.{keyword}[{index}] is shadowed by earlier branch {shadowed_by} under ordered serde untagged deserialization`
390    #[error(
391        "{context}.{keyword}[{index}] is shadowed by earlier branch {shadowed_by} under ordered serde untagged deserialization"
392    )]
393    ShadowedUnionBranch {
394        context: String,
395        keyword: &'static str,
396        index: usize,
397        shadowed_by: usize,
398    },
399
400    /// A composition schema declares no branches.
401    ///
402    /// Raised for empty `anyOf` and, today, for empty component `allOf` that is routed
403    /// through the shared empty composition-shape check.
404    ///
405    /// Error message: `{context} must declare at least one `anyOf` branch`
406    #[error("{context} must declare at least one `anyOf` branch")]
407    EmptyAnyOf { context: String },
408
409    /// `anyOf` component schemas form a recursive union cycle.
410    ///
411    /// Error message: `{context} forms a recursive `anyOf` cycle through schema `{schema}``
412    #[error("{context} forms a recursive `anyOf` cycle through schema `{schema}`")]
413    RecursiveAnyOf { context: String, schema: String },
414
415    /// A discriminator union does not use exactly one non-empty `anyOf` or `oneOf` branch list.
416    ///
417    /// Error message: `{context} discriminator unions must declare exactly one non-empty `anyOf` or `oneOf` branch list`
418    #[error(
419        "{context} discriminator unions must declare exactly one non-empty `anyOf` or `oneOf` branch list"
420    )]
421    InvalidDiscriminatorUnion { context: String },
422
423    /// A discriminator union branch is not a local component schema reference.
424    ///
425    /// Error message: `{context}.{keyword}[{index}] must be a local component schema reference when using `discriminator``
426    #[error(
427        "{context}.{keyword}[{index}] must be a local component schema reference when using `discriminator`"
428    )]
429    UnsupportedDiscriminatorBranch {
430        context: String,
431        keyword: &'static str,
432        index: usize,
433    },
434
435    /// A discriminator union branch target does not generate as an object struct.
436    ///
437    /// Error message: `{context} discriminator branch `{schema}` must be an object struct component`
438    #[error("{context} discriminator branch `{schema}` must be an object struct component")]
439    DiscriminatorBranchNotObject { context: String, schema: String },
440
441    /// A discriminator branch object contains the discriminator property.
442    ///
443    /// Error message: `{context} discriminator branch `{schema}` contains discriminator property `{property}``
444    #[error(
445        "{context} discriminator branch `{schema}` contains discriminator property `{property}`"
446    )]
447    DiscriminatorPropertyConflict {
448        context: String,
449        schema: String,
450        property: String,
451    },
452
453    /// A discriminator branch object contains an invalid embedded discriminator property.
454    ///
455    /// Error message: `{context} discriminator branch `{schema}` property `{property}` must be {expected}`
456    #[error("{context} discriminator branch `{schema}` property `{property}` must be {expected}")]
457    InvalidDiscriminatorProperty {
458        context: String,
459        schema: String,
460        property: String,
461        expected: &'static str,
462    },
463
464    /// A discriminator mapping entry targets a non-local schema or a schema outside the union branches.
465    ///
466    /// Error message: `{context}.discriminator.mapping[{value:?}] targets `{target}`, which is not a local union branch schema`
467    #[error(
468        "{context}.discriminator.mapping[{value:?}] targets `{target}`, which is not a local union branch schema"
469    )]
470    InvalidDiscriminatorMapping {
471        context: String,
472        value: String,
473        target: String,
474    },
475
476    /// Multiple discriminator mapping values target the same union branch schema.
477    ///
478    /// Error message: `{context}.discriminator.mapping maps multiple values to branch schema `{schema}``
479    #[error("{context}.discriminator.mapping maps multiple values to branch schema `{schema}`")]
480    DuplicateDiscriminatorMapping { context: String, schema: String },
481
482    /// A discriminator mapping value disagrees with a branch's embedded discriminator property value.
483    ///
484    /// Error message: `{context}.discriminator.mapping maps value `{value}` to branch schema `{schema}`, but the branch declares discriminator value `{actual}`
485    #[error(
486        "{context}.discriminator.mapping maps value `{value}` to branch schema `{schema}`, but the branch declares discriminator value `{actual}`"
487    )]
488    DiscriminatorMappingValueMismatch {
489        context: String,
490        schema: String,
491        value: String,
492        actual: String,
493    },
494
495    /// Multiple discriminator branches resolve to the same discriminator value after implicit defaults are applied.
496    ///
497    /// Error message: `{context}.discriminator resolves multiple branch schemas to value `{value}``
498    #[error("{context}.discriminator resolves multiple branch schemas to value `{value}`")]
499    DuplicateDiscriminatorValue { context: String, value: String },
500
501    // -- Schema constraint validation --
502    /// A string schema specifies a `minLength` greater than its `maxLength`.
503    ///
504    /// Error message: `{context} has minLength {min_length} greater than maxLength {max_length}`
505    #[error("{context} has minLength {min_length} greater than maxLength {max_length}")]
506    InvalidStringLengthBounds {
507        context: String,
508        min_length: u64,
509        max_length: u64,
510    },
511
512    /// A schema uses `uniqueItems`, which cannot be enforced by generated `Vec`-backed types.
513    ///
514    /// Error message: `{context} uses `uniqueItems`; generated Vec-backed types cannot enforce uniqueness yet`
515    #[error(
516        "{context} uses `uniqueItems`; generated Vec-backed types cannot enforce uniqueness yet"
517    )]
518    UniqueItemsUnsupported { context: String },
519
520    /// An array schema specifies `minItems` greater than `maxItems`.
521    ///
522    /// Error message: `{context} has minItems {min_items} greater than maxItems {max_items}`
523    #[error("{context} has minItems {min_items} greater than maxItems {max_items}")]
524    InvalidArrayLengthBounds {
525        context: String,
526        min_items: u64,
527        max_items: u64,
528    },
529
530    /// A schema uses a keyword that is not safely supported.
531    ///
532    /// Error message: `{context} uses `{keyword}`, which is not safely supported yet`
533    #[error("{context} uses `{keyword}`, which is not safely supported yet")]
534    UnsupportedKeyword { context: String, keyword: String },
535
536    /// A schema keyword that must be a non-negative integer has an invalid value.
537    ///
538    /// Error message: `{context}.{keyword} must be a non-negative integer`
539    #[error("{context}.{keyword} must be a non-negative integer")]
540    InvalidNonNegativeIntegerKeyword {
541        context: String,
542        keyword: &'static str,
543    },
544
545    /// An `exclusiveMinimum`/`exclusiveMaximum` keyword is present but the corresponding bound is missing.
546    ///
547    /// Error message: `{context}.{exclusive_keyword} requires `{keyword}``
548    #[error("{context}.{exclusive_keyword} requires `{keyword}`")]
549    ExclusiveLimitRequiresBound {
550        context: String,
551        exclusive_keyword: &'static str,
552        keyword: &'static str,
553    },
554
555    /// A schema keyword that must be a finite number has a non-finite value.
556    ///
557    /// Error message: `{context}.{keyword} must be a finite number`
558    #[error("{context}.{keyword} must be a finite number")]
559    InvalidFiniteNumberKeyword {
560        context: String,
561        keyword: &'static str,
562    },
563
564    /// A value expected to be an integer is not.
565    ///
566    /// Error message: `{context} must be an integer`
567    #[error("{context} must be an integer")]
568    ExpectedInteger { context: String },
569
570    /// Integer bounds (minimum/maximum) do not permit any value.
571    ///
572    /// Error message: `{context} integer bounds do not allow any value`
573    #[error("{context} integer bounds do not allow any value")]
574    EmptyIntegerBounds { context: String },
575
576    /// An exclusive integer minimum overflows `i64`.
577    ///
578    /// Error message: `exclusive integer minimum overflows`
579    #[error("exclusive integer minimum overflows")]
580    ExclusiveIntegerMinimumOverflow,
581
582    /// An exclusive integer maximum overflows `i64`.
583    ///
584    /// Error message: `exclusive integer maximum overflows`
585    #[error("exclusive integer maximum overflows")]
586    ExclusiveIntegerMaximumOverflow,
587
588    /// Number bounds (minimum/maximum) do not permit any value.
589    ///
590    /// Error message: `{context} number bounds do not allow any value`
591    #[error("{context} number bounds do not allow any value")]
592    EmptyNumberBounds { context: String },
593
594    // -- Operation, parameter, and response validation --
595    /// An operation does not declare any responses.
596    ///
597    /// Error message: `operation `{operation_id}` must declare responses`
598    #[error("operation `{operation_id}` must declare responses")]
599    MissingOperationResponses { operation_id: String },
600
601    /// A value expected to be an array is not.
602    ///
603    /// Error message: `{context} must be an array`
604    #[error("{context} must be an array")]
605    ExpectedArray { context: String },
606
607    /// A parameter uses an unsupported location (e.g. cookie) instead of path, query, or header.
608    ///
609    /// Error message: `{context} parameter `{wire_name}` is in `{location}`; only path, query, and header parameters are supported`
610    #[error(
611        "{context} parameter `{wire_name}` is in `{location}`; only path, query, and header parameters are supported"
612    )]
613    UnsupportedParameterLocation {
614        context: String,
615        wire_name: String,
616        location: String,
617    },
618
619    /// A parameter uses `content` instead of `schema`.
620    ///
621    /// Error message: `{context} parameter `{wire_name}` uses `content`; schema parameters are required`
622    #[error("{context} parameter `{wire_name}` uses `content`; schema parameters are required")]
623    ContentParameterUnsupported { context: String, wire_name: String },
624
625    /// A parameter is missing a required `schema` declaration.
626    ///
627    /// Error message: `{context} parameter `{wire_name}` must declare schema`
628    #[error("{context} parameter `{wire_name}` must declare schema")]
629    MissingParameterSchema { context: String, wire_name: String },
630
631    /// A parameter is nullable, which is not supported.
632    ///
633    /// Error message: `parameter `{wire_name}` is nullable; nullable parameters are not supported`
634    #[error("parameter `{wire_name}` is nullable; nullable parameters are not supported")]
635    NullableParameterUnsupported { wire_name: String },
636
637    /// A parameter uses `anyOf`, which is not supported for URI/header encoding yet.
638    ///
639    /// Error message: `parameter `{wire_name}` uses `anyOf`; anyOf parameters are not supported yet`
640    #[error("parameter `{wire_name}` uses `anyOf`; anyOf parameters are not supported yet")]
641    AnyOfParameterUnsupported { wire_name: String },
642
643    /// A parameter is a map or arbitrary JSON value, which has no URI/header encoding.
644    ///
645    /// Error message: `parameter `{wire_name}` is a map or JSON value; map parameters are not supported`
646    #[error("parameter `{wire_name}` is a map or JSON value; map parameters are not supported")]
647    MapParameterUnsupported { wire_name: String },
648
649    /// A path parameter is an array, which is not supported.
650    ///
651    /// Error message: `path parameter `{wire_name}` is an array; array path parameter styles are not supported`
652    #[error(
653        "path parameter `{wire_name}` is an array; array path parameter styles are not supported"
654    )]
655    ArrayPathParameterUnsupported { wire_name: String },
656
657    /// A header parameter is an array, which is not supported.
658    ///
659    /// Error message: `header parameter `{wire_name}` is an array; array header parameter styles are not supported`
660    #[error(
661        "header parameter `{wire_name}` is an array; array header parameter styles are not supported"
662    )]
663    ArrayHeaderParameterUnsupported { wire_name: String },
664
665    /// A path parameter does not set `required: true`.
666    ///
667    /// Error message: `path parameter `{wire_name}` must set required: true`
668    #[error("path parameter `{wire_name}` must set required: true")]
669    PathParameterNotRequired { wire_name: String },
670
671    /// A context is missing a required `content` declaration.
672    ///
673    /// Error message: `{context} must declare content`
674    #[error("{context} must declare content")]
675    MissingContent { context: String },
676
677    /// A context is missing the required `application/json` content type.
678    ///
679    /// Error message: `{context} must declare application/json content`
680    #[error("{context} must declare application/json content")]
681    MissingJsonContent { context: String },
682
683    /// A context's `application/json` content is missing a schema.
684    ///
685    /// Error message: `{context} application/json content must declare schema`
686    #[error("{context} application/json content must declare schema")]
687    MissingJsonSchema { context: String },
688
689    /// A response body uses the `default` status, which is not yet supported for decoding.
690    ///
691    /// Error message: `{context} contains a default response body; default response decoding is not supported yet`
692    #[error(
693        "{context} contains a default response body; default response decoding is not supported yet"
694    )]
695    DefaultResponseBodyUnsupported { context: String },
696
697    /// A response contains an invalid HTTP status code string.
698    ///
699    /// Error message: `{context} contains invalid status code `{status}``
700    #[error("{context} contains invalid status code `{status}`")]
701    InvalidStatusCode { context: String, status: String },
702
703    /// A response contains a status code outside the valid 100–599 range.
704    ///
705    /// Error message: `{context} contains out-of-range status code `{status_code}``
706    #[error("{context} contains out-of-range status code `{status_code}`")]
707    OutOfRangeStatusCode { context: String, status_code: u16 },
708
709    /// A response for a given status code is missing `application/json` content.
710    ///
711    /// Error message: `{context} {status} response must declare application/json content`
712    #[error("{context} {status} response must declare application/json content")]
713    MissingResponseJsonContent { context: String, status: String },
714
715    /// `x-satay.output` was configured on an operation with no JSON response body.
716    ///
717    /// Error message: `operation `{operation_id}` uses x-satay.output but has no JSON response body`
718    #[error("operation `{operation_id}` uses x-satay.output but has no JSON response body")]
719    SatayOutputRequiresResponseBody { operation_id: String },
720
721    /// A response projection selector was applied to a schema that is not an object with fields.
722    ///
723    /// Error message: `{context} cannot apply x-satay.output.{selector}; expected an object schema with properties`
724    #[error(
725        "{context} cannot apply x-satay.output.{selector}; expected an object schema with properties"
726    )]
727    SatayOutputExpectedObject {
728        context: String,
729        selector: &'static str,
730    },
731
732    /// A response projection selector names a field absent from its object schema.
733    ///
734    /// Error message: `{context} x-satay.output.{selector} `{field}` does not match a declared property`
735    #[error("{context} x-satay.output.{selector} `{field}` does not match a declared property")]
736    UnknownSatayOutputField {
737        context: String,
738        selector: &'static str,
739        field: String,
740    },
741
742    /// `x-satay.output.map-field` follows an unwrapped value that is not an array.
743    ///
744    /// Error message: `{context} cannot apply x-satay.output.map-field after `{field}`; the unwrapped schema must be an array`
745    #[error(
746        "{context} cannot apply x-satay.output.map-field after `{field}`; the unwrapped schema must be an array"
747    )]
748    SatayOutputMapRequiresArray { context: String, field: String },
749
750    /// A path template contains a parameter that is never closed.
751    ///
752    /// Error message: `path `{path}` contains an unclosed parameter`
753    #[error("path `{path}` contains an unclosed parameter")]
754    UnclosedPathParameter { path: String },
755
756    /// A path template contains an empty parameter (e.g. `{}`).
757    ///
758    /// Error message: `path `{path}` contains an empty parameter`
759    #[error("path `{path}` contains an empty parameter")]
760    EmptyPathParameter { path: String },
761
762    /// A path template references a parameter that is not declared in the operation's parameters.
763    ///
764    /// Error message: `path `{path}` uses parameter `{name}` but it is not declared`
765    #[error("path `{path}` uses parameter `{name}` but it is not declared")]
766    UndeclaredPathParameter { path: String, name: String },
767
768    /// A parameter is declared for a path but never used in the path template.
769    ///
770    /// Error message: `path parameter `{name}` is declared but not used in path `{path}``
771    #[error("path parameter `{name}` is declared but not used in path `{path}`")]
772    UnusedPathParameter { path: String, name: String },
773
774    // -- Reference resolution and JSON shape validation --
775    /// A `$ref` could not be resolved because the referenced component failed validation.
776    ///
777    /// Error message: `failed to resolve reference `{reference}` in {context}: {source}`
778    #[error("failed to resolve reference `{reference}` in {context}: {source}")]
779    ResolveReference {
780        reference: String,
781        context: String,
782        #[source]
783        source: Box<ValidationError>,
784    },
785
786    /// A reference points to an external document; only local (`#`) references are supported.
787    ///
788    /// Error message: `only local references are supported`
789    #[error("only local references are supported")]
790    NonLocalReference,
791
792    /// A local reference is not a valid JSON pointer.
793    ///
794    /// Error message: `local reference must be a JSON pointer`
795    #[error("local reference must be a JSON pointer")]
796    InvalidLocalReference,
797
798    /// A JSON pointer is missing a required token segment.
799    ///
800    /// Error message: `missing `{token}``
801    #[error("missing `{token}`")]
802    MissingJsonPointerToken { token: String },
803
804    /// A `$ref` does not point to the expected `#/components/{section}/…` path.
805    ///
806    /// Error message: `reference `{reference}` must point to #/components/{section}/...`
807    #[error("reference `{reference}` must point to #/components/{section}/...")]
808    InvalidComponentReference {
809        reference: String,
810        section: &'static str,
811    },
812
813    /// A local `$ref` chain references itself.
814    ///
815    /// Error message: `circular reference `{reference}``
816    #[error("circular reference `{reference}`")]
817    CircularReference { reference: String },
818
819    /// A value expected to be an object is not.
820    ///
821    /// Error message: `{context} must be an object`
822    #[error("{context} must be an object")]
823    ExpectedObject { context: String },
824}
825
826impl ValidationError {
827    /// Wraps an [`ExtensionError`] with a codegen context string such as a schema
828    /// or operation identifier.
829    pub(crate) fn extension_error(context: &str, source: ExtensionError) -> Self {
830        match source {
831            ExtensionError::InvalidValue { path, source, .. } => {
832                ValidationError::InvalidExtension {
833                    context: context.to_owned(),
834                    path,
835                    source,
836                }
837            }
838            // `x-satay` is always a valid extension name when used by codegen.
839            // The invalid-name case only fires when a caller passes a bad name
840            // itself; preserve it here as a fallback diagnostic.
841            other => ValidationError::InvalidExtension {
842                context: context.to_owned(),
843                path: name_or_other_path(other),
844                source: SerdeError::custom("invalid specification extension"),
845            },
846        }
847    }
848}
849
850fn name_or_other_path(error: oas3::spec::ExtensionError) -> String {
851    match error {
852        ExtensionError::InvalidName { name } => name,
853        _ => "x-satay".to_owned(),
854    }
855}
satay_codegen/error/validation.rs

satay_codegen/error/
validation.rs
