1 // Copyright 2015 go-swagger maintainers 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 /* 16 Package validate provides methods to validate a swagger specification, 17 as well as tools to validate data against their schema. 18 19 This package follows Swagger 2.0. specification (aka OpenAPI 2.0). Reference 20 can be found here: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md. 21 22 # Validating a specification 23 24 Validates a spec document (from JSON or YAML) against the JSON schema for swagger, 25 then checks a number of extra rules that can't be expressed in JSON schema. 26 27 Entry points: 28 - Spec() 29 - NewSpecValidator() 30 - SpecValidator.Validate() 31 32 Reported as errors: 33 34 [x] definition can't declare a property that's already defined by one of its ancestors 35 [x] definition's ancestor can't be a descendant of the same model 36 [x] path uniqueness: each api path should be non-verbatim (account for path param names) unique per method. Validation can be laxed by disabling StrictPathParamUniqueness. 37 [x] each security reference should contain only unique scopes 38 [x] each security scope in a security definition should be unique 39 [x] parameters in path must be unique 40 [x] each path parameter must correspond to a parameter placeholder and vice versa 41 [x] each referenceable definition must have references 42 [x] each definition property listed in the required array must be defined in the properties of the model 43 [x] each parameter should have a unique `name` and `type` combination 44 [x] each operation should have only 1 parameter of type body 45 [x] each reference must point to a valid object 46 [x] every default value that is specified must validate against the schema for that property 47 [x] items property is required for all schemas/definitions of type `array` 48 [x] path parameters must be declared a required 49 [x] headers must not contain $ref 50 [x] schema and property examples provided must validate against their respective object's schema 51 [x] examples provided must validate their schema 52 53 Reported as warnings: 54 55 [x] path parameters should not contain any of [{,},\w] 56 [x] empty path 57 [x] unused definitions 58 [x] unsupported validation of examples on non-JSON media types 59 [x] examples in response without schema 60 [x] readOnly properties should not be required 61 62 # Validating a schema 63 64 The schema validation toolkit validates data against JSON-schema-draft 04 schema. 65 66 It is tested against the full json-schema-testing-suite (https://github.com/json-schema-org/JSON-Schema-Test-Suite), 67 except for the optional part (bignum, ECMA regexp, ...). 68 69 It supports the complete JSON-schema vocabulary, including keywords not supported by Swagger (e.g. additionalItems, ...) 70 71 Entry points: 72 - AgainstSchema() 73 - ... 74 75 # Known limitations 76 77 With the current version of this package, the following aspects of swagger are not yet supported: 78 79 [ ] errors and warnings are not reported with key/line number in spec 80 [ ] default values and examples on responses only support application/json producer type 81 [ ] invalid numeric constraints (such as Minimum, etc..) are not checked except for default and example values 82 [ ] rules for collectionFormat are not implemented 83 [ ] no validation rule for polymorphism support (discriminator) [not done here] 84 [ ] valid js ECMA regexp not supported by Go regexp engine are considered invalid 85 [ ] arbitrary large numbers are not supported: max is math.MaxFloat64 86 */ 87 package validate 88