From 5fcca167b2f7f3e64532bd6f7a25737177b50779 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Sat, 13 Apr 2019 12:33:00 +0200 Subject: [PATCH] golint: add GoDoc for exported types and functions Signed-off-by: Sebastiaan van Stijn --- draft.go | 2 + errors.go | 93 ++++++++++++++++++--------- format_checkers.go | 49 ++++++++++++-- jsonContext.go | 1 + jsonLoader.go | 16 ++++- locales.go | 156 ++++++++++++++++++++++++++++++++++++++++++++- result.go | 35 +++++++++- schema.go | 3 + schemaLoader.go | 3 + subSchema.go | 1 + types.go | 4 ++ validation.go | 2 + 12 files changed, 320 insertions(+), 45 deletions(-) diff --git a/draft.go b/draft.go index 6fd4491..7a0123c 100644 --- a/draft.go +++ b/draft.go @@ -22,8 +22,10 @@ import ( "github.com/xeipuuv/gojsonreference" ) +// Draft is a JSON-schema draft version type Draft int +// Supported Draft versions const ( Draft4 Draft = 4 Draft6 Draft = 6 diff --git a/errors.go b/errors.go index 2f01a1c..3f3be33 100644 --- a/errors.go +++ b/errors.go @@ -16,157 +16,188 @@ type errorTemplate struct { } type ( - // RequiredError. ErrorDetails: property string + // RequiredError indicates that a required field is missing + // ErrorDetails: property string RequiredError struct { ResultErrorFields } - // InvalidTypeError. ErrorDetails: expected, given + // InvalidTypeError indicates that a field has the incorrect type + // ErrorDetails: expected, given InvalidTypeError struct { ResultErrorFields } - // NumberAnyOfError. ErrorDetails: - + // NumberAnyOfError is produced in case of a failing "anyOf" validation + // ErrorDetails: - NumberAnyOfError struct { ResultErrorFields } - // NumberOneOfError. ErrorDetails: - + // NumberOneOfError is produced in case of a failing "oneOf" validation + // ErrorDetails: - NumberOneOfError struct { ResultErrorFields } - // NumberAllOfError. ErrorDetails: - + // NumberAllOfError is produced in case of a failing "allOf" validation + // ErrorDetails: - NumberAllOfError struct { ResultErrorFields } - // NumberNotError. ErrorDetails: - + // NumberNotError is produced if a "not" validation failed + // ErrorDetails: - NumberNotError struct { ResultErrorFields } - // MissingDependencyError. ErrorDetails: dependency + // MissingDependencyError is produced in case of a "missing dependency" problem + // ErrorDetails: dependency MissingDependencyError struct { ResultErrorFields } - // InternalError. ErrorDetails: error + // InternalError indicates an internal error + // ErrorDetails: error InternalError struct { ResultErrorFields } - // ConstError. ErrorDetails: allowed + // ConstError indicates a const error + // ErrorDetails: allowed ConstError struct { ResultErrorFields } - // EnumError. ErrorDetails: allowed + // EnumError indicates an enum error + // ErrorDetails: allowed EnumError struct { ResultErrorFields } - // ArrayNoAdditionalItemsError. ErrorDetails: - + // ArrayNoAdditionalItemsError is produced if additional items were found, but not allowed + // ErrorDetails: - ArrayNoAdditionalItemsError struct { ResultErrorFields } - // ArrayMinItemsError. ErrorDetails: min + // ArrayMinItemsError is produced if an array contains less items than the allowed minimum + // ErrorDetails: min ArrayMinItemsError struct { ResultErrorFields } - // ArrayMaxItemsError. ErrorDetails: max + // ArrayMaxItemsError is produced if an array contains more items than the allowed maximum + // ErrorDetails: max ArrayMaxItemsError struct { ResultErrorFields } - // ItemsMustBeUniqueError. ErrorDetails: type, i, j + // ItemsMustBeUniqueError is produced if an array requires unique items, but contains non-unique items + // ErrorDetails: type, i, j ItemsMustBeUniqueError struct { ResultErrorFields } - // ArrayContainsError. ErrorDetails: + // ArrayContainsError is produced if an array contains invalid items + // ErrorDetails: ArrayContainsError struct { ResultErrorFields } - // ArrayMinPropertiesError. ErrorDetails: min + // ArrayMinPropertiesError is produced if an object contains less properties than the allowed minimum + // ErrorDetails: min ArrayMinPropertiesError struct { ResultErrorFields } - // ArrayMaxPropertiesError. ErrorDetails: max + // ArrayMaxPropertiesError is produced if an object contains more properties than the allowed maximum + // ErrorDetails: max ArrayMaxPropertiesError struct { ResultErrorFields } - // AdditionalPropertyNotAllowedError. ErrorDetails: property + // AdditionalPropertyNotAllowedError is produced if an object has additional properties, but not allowed + // ErrorDetails: property AdditionalPropertyNotAllowedError struct { ResultErrorFields } - // InvalidPropertyPatternError. ErrorDetails: property, pattern + // InvalidPropertyPatternError is produced if an pattern was found + // ErrorDetails: property, pattern InvalidPropertyPatternError struct { ResultErrorFields } - // InvalidPopertyNameError. ErrorDetails: property + // InvalidPropertyNameError is produced if an invalid-named property was found + // ErrorDetails: property InvalidPropertyNameError struct { ResultErrorFields } - // StringLengthGTEError. ErrorDetails: min + // StringLengthGTEError is produced if a string is shorter than the minimum required length + // ErrorDetails: min StringLengthGTEError struct { ResultErrorFields } - // StringLengthLTEError. ErrorDetails: max + // StringLengthLTEError is produced if a string is longer than the maximum allowed length + // ErrorDetails: max StringLengthLTEError struct { ResultErrorFields } - // DoesNotMatchPatternError. ErrorDetails: pattern + // DoesNotMatchPatternError is produced if a string does not match the defined pattern + // ErrorDetails: pattern DoesNotMatchPatternError struct { ResultErrorFields } - // DoesNotMatchFormatError. ErrorDetails: format + // DoesNotMatchFormatError is produced if a string does not match the defined format + // ErrorDetails: format DoesNotMatchFormatError struct { ResultErrorFields } - // MultipleOfError. ErrorDetails: multiple + // MultipleOfError is produced if a number is not a multiple of the defined multipleOf + // ErrorDetails: multiple MultipleOfError struct { ResultErrorFields } - // NumberGTEError. ErrorDetails: min + // NumberGTEError is produced if a number is lower than the allowed minimum + // ErrorDetails: min NumberGTEError struct { ResultErrorFields } - // NumberGTError. ErrorDetails: min + // NumberGTError is produced if a number is lower than, or equal to the specified minimum, and exclusiveMinimum is set + // ErrorDetails: min NumberGTError struct { ResultErrorFields } - // NumberLTEError. ErrorDetails: max + // NumberLTEError is produced if a number is higher than the allowed maximum + // ErrorDetails: max NumberLTEError struct { ResultErrorFields } - // NumberLTError. ErrorDetails: max + // NumberLTError is produced if a number is higher than, or equal to the specified maximum, and exclusiveMaximum is set + // ErrorDetails: max NumberLTError struct { ResultErrorFields } - // ConditionThenError. ErrorDetails: - + // ConditionThenError is produced if a condition's "then" validation is invalid + // ErrorDetails: - ConditionThenError struct { ResultErrorFields } - // ConditionElseError. ErrorDetails: - + // ConditionElseError is produced if a condition's "else" condition is invalid + // ErrorDetails: - ConditionElseError struct { ResultErrorFields } diff --git a/format_checkers.go b/format_checkers.go index d47b0aa..fdfb21d 100644 --- a/format_checkers.go +++ b/format_checkers.go @@ -13,6 +13,7 @@ import ( type ( // FormatChecker is the interface all formatters added to FormatCheckerChain must implement FormatChecker interface { + // IsFormat checks if input has the correct format and type IsFormat(input interface{}) bool } @@ -21,13 +22,13 @@ type ( formatters map[string]FormatChecker } - // EmailFormatter verifies email address formats + // EmailFormatChecker verifies email address formats EmailFormatChecker struct{} - // IPV4FormatChecker verifies IP addresses in the ipv4 format + // IPV4FormatChecker verifies IP addresses in the IPv4 format IPV4FormatChecker struct{} - // IPV6FormatChecker verifies IP addresses in the ipv6 format + // IPV6FormatChecker verifies IP addresses in the IPv6 format IPV6FormatChecker struct{} // DateTimeFormatChecker verifies date/time formats per RFC3339 5.6 @@ -53,8 +54,29 @@ type ( // http://tools.ietf.org/html/rfc3339#section-5.6 DateTimeFormatChecker struct{} + // DateFormatChecker verifies date formats + // + // Valid format: + // Full Date: YYYY-MM-DD + // + // Where + // YYYY = 4DIGIT year + // MM = 2DIGIT month ; 01-12 + // DD = 2DIGIT day-month ; 01-28, 01-29, 01-30, 01-31 based on month/year DateFormatChecker struct{} + // TimeFormatChecker verifies time formats + // + // Valid formats: + // Partial Time: HH:MM:SS + // Full Time: HH:MM:SSZ-07:00 + // + // Where + // HH = 2DIGIT hour ; 00-23 + // MM = 2DIGIT ; 00-59 + // SS = 2DIGIT ; 00-58, 00-60 based on leap second rules + // T = Literal + // Z = Literal TimeFormatChecker struct{} // URIFormatChecker validates a URI with a valid Scheme per RFC3986 @@ -83,7 +105,7 @@ type ( ) var ( - // Formatters holds the valid formatters, and is a public variable + // FormatCheckers holds the valid formatters, and is a public variable // so library users can add custom formatters FormatCheckers = FormatCheckerChain{ formatters: map[string]FormatChecker{ @@ -161,6 +183,7 @@ func (c *FormatCheckerChain) IsFormat(name string, input interface{}) bool { return f.IsFormat(input) } +// IsFormat checks if input is a correctly formatted e-mail address func (f EmailFormatChecker) IsFormat(input interface{}) bool { asString, ok := input.(string) if !ok { @@ -171,28 +194,31 @@ func (f EmailFormatChecker) IsFormat(input interface{}) bool { return err == nil } -// Credit: https://github.com/asaskevich/govalidator +// IsFormat checks if input is a correctly formatted IPv4-address func (f IPV4FormatChecker) IsFormat(input interface{}) bool { asString, ok := input.(string) if !ok { return false } + // Credit: https://github.com/asaskevich/govalidator ip := net.ParseIP(asString) return ip != nil && strings.Contains(asString, ".") } -// Credit: https://github.com/asaskevich/govalidator +// IsFormat checks if input is a correctly formatted IPv6=address func (f IPV6FormatChecker) IsFormat(input interface{}) bool { asString, ok := input.(string) if !ok { return false } + // Credit: https://github.com/asaskevich/govalidator ip := net.ParseIP(asString) return ip != nil && strings.Contains(asString, ":") } +// IsFormat checks if input is a correctly formatted date/time per RFC3339 5.6 func (f DateTimeFormatChecker) IsFormat(input interface{}) bool { asString, ok := input.(string) if !ok { @@ -216,6 +242,7 @@ func (f DateTimeFormatChecker) IsFormat(input interface{}) bool { return false } +// IsFormat checks if input is a correctly formatted date (YYYY-MM-DD) func (f DateFormatChecker) IsFormat(input interface{}) bool { asString, ok := input.(string) if !ok { @@ -225,6 +252,7 @@ func (f DateFormatChecker) IsFormat(input interface{}) bool { return err == nil } +// IsFormat checks if input correctly formatted time (HH:MM:SS or HH:MM:SSZ-07:00) func (f TimeFormatChecker) IsFormat(input interface{}) bool { asString, ok := input.(string) if !ok { @@ -239,6 +267,7 @@ func (f TimeFormatChecker) IsFormat(input interface{}) bool { return err == nil } +// IsFormat checks if input is correctly formatted URI with a valid Scheme per RFC3986 func (f URIFormatChecker) IsFormat(input interface{}) bool { asString, ok := input.(string) if !ok { @@ -254,6 +283,7 @@ func (f URIFormatChecker) IsFormat(input interface{}) bool { return !strings.Contains(asString, `\`) } +// IsFormat checks if input is a correctly formatted URI or relative-reference per RFC3986 func (f URIReferenceFormatChecker) IsFormat(input interface{}) bool { asString, ok := input.(string) if !ok { @@ -264,6 +294,7 @@ func (f URIReferenceFormatChecker) IsFormat(input interface{}) bool { return err == nil && !strings.Contains(asString, `\`) } +// IsFormat checks if input is a correctly formatted URI template per RFC6570 func (f URITemplateFormatChecker) IsFormat(input interface{}) bool { asString, ok := input.(string) if !ok { @@ -278,6 +309,7 @@ func (f URITemplateFormatChecker) IsFormat(input interface{}) bool { return rxURITemplate.MatchString(u.Path) } +// IsFormat checks if input is a correctly formatted hostname func (f HostnameFormatChecker) IsFormat(input interface{}) bool { asString, ok := input.(string) if !ok { @@ -287,6 +319,7 @@ func (f HostnameFormatChecker) IsFormat(input interface{}) bool { return rxHostname.MatchString(asString) && len(asString) < 256 } +// IsFormat checks if input is a correctly formatted UUID func (f UUIDFormatChecker) IsFormat(input interface{}) bool { asString, ok := input.(string) if !ok { @@ -296,7 +329,7 @@ func (f UUIDFormatChecker) IsFormat(input interface{}) bool { return rxUUID.MatchString(asString) } -// IsFormat implements FormatChecker interface. +// IsFormat checks if input is a correctly formatted regular expression func (f RegexFormatChecker) IsFormat(input interface{}) bool { asString, ok := input.(string) if !ok { @@ -310,6 +343,7 @@ func (f RegexFormatChecker) IsFormat(input interface{}) bool { return err == nil } +// IsFormat checks if input is a correctly formatted JSON Pointer per RFC6901 func (f JSONPointerFormatChecker) IsFormat(input interface{}) bool { asString, ok := input.(string) if !ok { @@ -319,6 +353,7 @@ func (f JSONPointerFormatChecker) IsFormat(input interface{}) bool { return rxJSONPointer.MatchString(asString) } +// IsFormat checks if input is a correctly formatted relative JSON Pointer func (f RelativeJSONPointerFormatChecker) IsFormat(input interface{}) bool { asString, ok := input.(string) if !ok { diff --git a/jsonContext.go b/jsonContext.go index f40668a..0e97970 100644 --- a/jsonContext.go +++ b/jsonContext.go @@ -32,6 +32,7 @@ type JsonContext struct { tail *JsonContext } +// NewJsonContext creates a new JsonContext func NewJsonContext(head string, tail *JsonContext) *JsonContext { return &JsonContext{head, tail} } diff --git a/jsonLoader.go b/jsonLoader.go index 865e2f0..e17e3aa 100644 --- a/jsonLoader.go +++ b/jsonLoader.go @@ -43,8 +43,7 @@ import ( var osFS = osFileSystem(os.Open) -// JSON loader interface - +// JSONLoader defines the JSON loader interface type JSONLoader interface { JsonSource() interface{} LoadJSON() (interface{}, error) @@ -52,17 +51,22 @@ type JSONLoader interface { LoaderFactory() JSONLoaderFactory } +// JSONLoaderFactory defines the JSON loader factory interface type JSONLoaderFactory interface { + // New creates a new JSON loader for the given source New(source string) JSONLoader } +// DefaultJSONLoaderFactory is the default JSON loader factory type DefaultJSONLoaderFactory struct { } +// FileSystemJSONLoaderFactory is a JSON loader factory that uses http.FileSystem type FileSystemJSONLoaderFactory struct { fs http.FileSystem } +// New creates a new JSON loader for the given source func (d DefaultJSONLoaderFactory) New(source string) JSONLoader { return &jsonReferenceLoader{ fs: osFS, @@ -70,6 +74,7 @@ func (d DefaultJSONLoaderFactory) New(source string) JSONLoader { } } +// New creates a new JSON loader for the given source func (f FileSystemJSONLoaderFactory) New(source string) JSONLoader { return &jsonReferenceLoader{ fs: f.fs, @@ -80,6 +85,7 @@ func (f FileSystemJSONLoaderFactory) New(source string) JSONLoader { // osFileSystem is a functional wrapper for os.Open that implements http.FileSystem. type osFileSystem func(string) (*os.File, error) +// Opens a file with the given name func (o osFileSystem) Open(name string) (http.File, error) { return o(name) } @@ -224,6 +230,7 @@ func (l *jsonStringLoader) LoaderFactory() JSONLoaderFactory { return &DefaultJSONLoaderFactory{} } +// NewStringLoader creates a new JSONLoader, taking a string as source func NewStringLoader(source string) JSONLoader { return &jsonStringLoader{source: source} } @@ -252,6 +259,7 @@ func (l *jsonBytesLoader) LoaderFactory() JSONLoaderFactory { return &DefaultJSONLoaderFactory{} } +// NewBytesLoader creates a new JSONLoader, taking a `[]byte` as source func NewBytesLoader(source []byte) JSONLoader { return &jsonBytesLoader{source: source} } @@ -279,6 +287,7 @@ func (l *jsonGoLoader) LoaderFactory() JSONLoaderFactory { return &DefaultJSONLoaderFactory{} } +// NewGoLoader creates a new JSONLoader from a given Go struct func NewGoLoader(source interface{}) JSONLoader { return &jsonGoLoader{source: source} } @@ -300,11 +309,13 @@ type jsonIOLoader struct { buf *bytes.Buffer } +// NewReaderLoader creates a new JSON loader using the provided io.Reader func NewReaderLoader(source io.Reader) (JSONLoader, io.Reader) { buf := &bytes.Buffer{} return &jsonIOLoader{buf: buf}, io.TeeReader(source, buf) } +// NewWriterLoader creates a new JSON loader using the provided io.Writer func NewWriterLoader(source io.Writer) (JSONLoader, io.Writer) { buf := &bytes.Buffer{} return &jsonIOLoader{buf: buf}, io.MultiWriter(source, buf) @@ -334,6 +345,7 @@ type jsonRawLoader struct { source interface{} } +// NewRawLoader creates a new JSON raw loader for the given source func NewRawLoader(source interface{}) JSONLoader { return &jsonRawLoader{source: source} } diff --git a/locales.go b/locales.go index 9b4570f..064d3f3 100644 --- a/locales.go +++ b/locales.go @@ -28,61 +28,159 @@ package gojsonschema type ( // locale is an interface for defining custom error strings locale interface { + // Required returns a format-string for "required" schema validation errors Required() string + + // InvalidType returns a format-string for "invalid type" schema validation errors InvalidType() string + + // NumberAnyOf returns a format-string for "anyOf" schema validation errors NumberAnyOf() string + + // NumberOneOf returns a format-string for "oneOf" schema validation errors NumberOneOf() string + + // NumberAllOf returns a format-string for "allOf" schema validation errors NumberAllOf() string + + // NumberNot returns a format-string to format a NumberNotError NumberNot() string + + // MissingDependency returns a format-string for "missing dependency" schema validation errors MissingDependency() string + + // Internal returns a format-string for internal errors Internal() string + + // Const returns a format-string to format a ConstError Const() string + + // Enum returns a format-string to format an EnumError Enum() string + + // ArrayNotEnoughItems returns a format-string to format an error for arrays having not enough items to match positional list of schema ArrayNotEnoughItems() string + + // ArrayNoAdditionalItems returns a format-string to format an ArrayNoAdditionalItemsError ArrayNoAdditionalItems() string + + // ArrayMinItems returns a format-string to format an ArrayMinItemsError ArrayMinItems() string + + // ArrayMaxItems returns a format-string to format an ArrayMaxItemsError ArrayMaxItems() string + + // Unique returns a format-string to format an ItemsMustBeUniqueError Unique() string + + // ArrayContains returns a format-string to format an ArrayContainsError ArrayContains() string + + // ArrayMinProperties returns a format-string to format an ArrayMinPropertiesError ArrayMinProperties() string + + // ArrayMaxProperties returns a format-string to format an ArrayMaxPropertiesError ArrayMaxProperties() string + + // AdditionalPropertyNotAllowed returns a format-string to format an AdditionalPropertyNotAllowedError AdditionalPropertyNotAllowed() string + + // InvalidPropertyPattern returns a format-string to format an InvalidPropertyPatternError InvalidPropertyPattern() string + + // InvalidPropertyName returns a format-string to format an InvalidPropertyNameError InvalidPropertyName() string + + // StringGTE returns a format-string to format an StringLengthGTEError StringGTE() string + + // StringLTE returns a format-string to format an StringLengthLTEError StringLTE() string + + // DoesNotMatchPattern returns a format-string to format an DoesNotMatchPatternError DoesNotMatchPattern() string + + // DoesNotMatchFormat returns a format-string to format an DoesNotMatchFormatError DoesNotMatchFormat() string + + // MultipleOf returns a format-string to format an MultipleOfError MultipleOf() string + + // NumberGTE returns a format-string to format an NumberGTEError NumberGTE() string + + // NumberGT returns a format-string to format an NumberGTError NumberGT() string + + // NumberLTE returns a format-string to format an NumberLTEError NumberLTE() string + + // NumberLT returns a format-string to format an NumberLTError NumberLT() string // Schema validations + + // RegexPattern returns a format-string to format a regex-pattern error RegexPattern() string + + // GreaterThanZero returns a format-string to format an error where a number must be greater than zero GreaterThanZero() string + + // MustBeOfA returns a format-string to format an error where a value is of the wrong type MustBeOfA() string + + // MustBeOfAn returns a format-string to format an error where a value is of the wrong type MustBeOfAn() string + + // CannotBeUsedWithout returns a format-string to format a "cannot be used without" error CannotBeUsedWithout() string + + // CannotBeGT returns a format-string to format an error where a value are greater than allowed CannotBeGT() string + + // MustBeOfType returns a format-string to format an error where a value does not match the required type MustBeOfType() string + + // MustBeValidRegex returns a format-string to format an error where a regex is invalid MustBeValidRegex() string + + // MustBeValidFormat returns a format-string to format an error where a value does not match the expected format MustBeValidFormat() string + + // MustBeGTEZero returns a format-string to format an error where a value must be greater or equal than 0 MustBeGTEZero() string + + // KeyCannotBeGreaterThan returns a format-string to format an error where a key is greater than the maximum allowed KeyCannotBeGreaterThan() string + + // KeyItemsMustBeOfType returns a format-string to format an error where a key is of the wrong type KeyItemsMustBeOfType() string + + // KeyItemsMustBeUnique returns a format-string to format an error where keys are not unique KeyItemsMustBeUnique() string + + // ReferenceMustBeCanonical returns a format-string to format a "reference must be canonical" error ReferenceMustBeCanonical() string + + // NotAValidType returns a format-string to format an invalid type error NotAValidType() string + + // Duplicated returns a format-string to format an error where types are duplicated Duplicated() string + + // HttpBadStatus returns a format-string for errors when loading a schema using HTTP HttpBadStatus() string + + // ParseError returns a format-string for JSON parsing errors ParseError() string + // ConditionThen returns a format-string for ConditionThenError errors ConditionThen() string + + // ConditionElse returns a format-string for ConditionElseError errors ConditionElse() string - // ErrorFormat + // ErrorFormat returns a format string for errors ErrorFormat() string } @@ -90,214 +188,266 @@ type ( DefaultLocale struct{} ) +// Required returns a format-string for "required" schema validation errors func (l DefaultLocale) Required() string { return `{{.property}} is required` } +// InvalidType returns a format-string for "invalid type" schema validation errors func (l DefaultLocale) InvalidType() string { return `Invalid type. Expected: {{.expected}}, given: {{.given}}` } +// NumberAnyOf returns a format-string for "anyOf" schema validation errors func (l DefaultLocale) NumberAnyOf() string { return `Must validate at least one schema (anyOf)` } +// NumberOneOf returns a format-string for "oneOf" schema validation errors func (l DefaultLocale) NumberOneOf() string { return `Must validate one and only one schema (oneOf)` } +// NumberAllOf returns a format-string for "allOf" schema validation errors func (l DefaultLocale) NumberAllOf() string { return `Must validate all the schemas (allOf)` } +// NumberNot returns a format-string to format a NumberNotError func (l DefaultLocale) NumberNot() string { return `Must not validate the schema (not)` } +// MissingDependency returns a format-string for "missing dependency" schema validation errors func (l DefaultLocale) MissingDependency() string { return `Has a dependency on {{.dependency}}` } +// Internal returns a format-string for internal errors func (l DefaultLocale) Internal() string { return `Internal Error {{.error}}` } +// Const returns a format-string to format a ConstError func (l DefaultLocale) Const() string { return `{{.field}} does not match: {{.allowed}}` } +// Enum returns a format-string to format an EnumError func (l DefaultLocale) Enum() string { return `{{.field}} must be one of the following: {{.allowed}}` } +// ArrayNoAdditionalItems returns a format-string to format an ArrayNoAdditionalItemsError func (l DefaultLocale) ArrayNoAdditionalItems() string { return `No additional items allowed on array` } +// ArrayNotEnoughItems returns a format-string to format an error for arrays having not enough items to match positional list of schema func (l DefaultLocale) ArrayNotEnoughItems() string { return `Not enough items on array to match positional list of schema` } +// ArrayMinItems returns a format-string to format an ArrayMinItemsError func (l DefaultLocale) ArrayMinItems() string { return `Array must have at least {{.min}} items` } +// ArrayMaxItems returns a format-string to format an ArrayMaxItemsError func (l DefaultLocale) ArrayMaxItems() string { return `Array must have at most {{.max}} items` } +// Unique returns a format-string to format an ItemsMustBeUniqueError func (l DefaultLocale) Unique() string { return `{{.type}} items[{{.i}},{{.j}}] must be unique` } +// ArrayContains returns a format-string to format an ArrayContainsError func (l DefaultLocale) ArrayContains() string { return `At least one of the items must match` } +// ArrayMinProperties returns a format-string to format an ArrayMinPropertiesError func (l DefaultLocale) ArrayMinProperties() string { return `Must have at least {{.min}} properties` } +// ArrayMaxProperties returns a format-string to format an ArrayMaxPropertiesError func (l DefaultLocale) ArrayMaxProperties() string { return `Must have at most {{.max}} properties` } +// AdditionalPropertyNotAllowed returns a format-string to format an AdditionalPropertyNotAllowedError func (l DefaultLocale) AdditionalPropertyNotAllowed() string { return `Additional property {{.property}} is not allowed` } +// InvalidPropertyPattern returns a format-string to format an InvalidPropertyPatternError func (l DefaultLocale) InvalidPropertyPattern() string { return `Property "{{.property}}" does not match pattern {{.pattern}}` } +// InvalidPropertyName returns a format-string to format an InvalidPropertyNameError func (l DefaultLocale) InvalidPropertyName() string { return `Property name of "{{.property}}" does not match` } +// StringGTE returns a format-string to format an StringLengthGTEError func (l DefaultLocale) StringGTE() string { return `String length must be greater than or equal to {{.min}}` } +// StringLTE returns a format-string to format an StringLengthLTEError func (l DefaultLocale) StringLTE() string { return `String length must be less than or equal to {{.max}}` } +// DoesNotMatchPattern returns a format-string to format an DoesNotMatchPatternError func (l DefaultLocale) DoesNotMatchPattern() string { return `Does not match pattern '{{.pattern}}'` } +// DoesNotMatchFormat returns a format-string to format an DoesNotMatchFormatError func (l DefaultLocale) DoesNotMatchFormat() string { return `Does not match format '{{.format}}'` } +// MultipleOf returns a format-string to format an MultipleOfError func (l DefaultLocale) MultipleOf() string { return `Must be a multiple of {{.multiple}}` } +// NumberGTE returns the format string to format a NumberGTEError func (l DefaultLocale) NumberGTE() string { return `Must be greater than or equal to {{.min}}` } +// NumberGT returns the format string to format a NumberGTError func (l DefaultLocale) NumberGT() string { return `Must be greater than {{.min}}` } +// NumberLTE returns the format string to format a NumberLTEError func (l DefaultLocale) NumberLTE() string { return `Must be less than or equal to {{.max}}` } +// NumberLT returns the format string to format a NumberLTError func (l DefaultLocale) NumberLT() string { return `Must be less than {{.max}}` } // Schema validators + +// RegexPattern returns a format-string to format a regex-pattern error func (l DefaultLocale) RegexPattern() string { return `Invalid regex pattern '{{.pattern}}'` } +// GreaterThanZero returns a format-string to format an error where a number must be greater than zero func (l DefaultLocale) GreaterThanZero() string { return `{{.number}} must be strictly greater than 0` } +// MustBeOfA returns a format-string to format an error where a value is of the wrong type func (l DefaultLocale) MustBeOfA() string { return `{{.x}} must be of a {{.y}}` } +// MustBeOfAn returns a format-string to format an error where a value is of the wrong type func (l DefaultLocale) MustBeOfAn() string { return `{{.x}} must be of an {{.y}}` } +// CannotBeUsedWithout returns a format-string to format a "cannot be used without" error func (l DefaultLocale) CannotBeUsedWithout() string { return `{{.x}} cannot be used without {{.y}}` } +// CannotBeGT returns a format-string to format an error where a value are greater than allowed func (l DefaultLocale) CannotBeGT() string { return `{{.x}} cannot be greater than {{.y}}` } +// MustBeOfType returns a format-string to format an error where a value does not match the required type func (l DefaultLocale) MustBeOfType() string { return `{{.key}} must be of type {{.type}}` } +// MustBeValidRegex returns a format-string to format an error where a regex is invalid func (l DefaultLocale) MustBeValidRegex() string { return `{{.key}} must be a valid regex` } +// MustBeValidFormat returns a format-string to format an error where a value does not match the expected format func (l DefaultLocale) MustBeValidFormat() string { return `{{.key}} must be a valid format {{.given}}` } +// MustBeGTEZero returns a format-string to format an error where a value must be greater or equal than 0 func (l DefaultLocale) MustBeGTEZero() string { return `{{.key}} must be greater than or equal to 0` } +// KeyCannotBeGreaterThan returns a format-string to format an error where a value is greater than the maximum allowed func (l DefaultLocale) KeyCannotBeGreaterThan() string { return `{{.key}} cannot be greater than {{.y}}` } +// KeyItemsMustBeOfType returns a format-string to format an error where a key is of the wrong type func (l DefaultLocale) KeyItemsMustBeOfType() string { return `{{.key}} items must be {{.type}}` } +// KeyItemsMustBeUnique returns a format-string to format an error where keys are not unique func (l DefaultLocale) KeyItemsMustBeUnique() string { return `{{.key}} items must be unique` } +// ReferenceMustBeCanonical returns a format-string to format a "reference must be canonical" error func (l DefaultLocale) ReferenceMustBeCanonical() string { return `Reference {{.reference}} must be canonical` } +// NotAValidType returns a format-string to format an invalid type error func (l DefaultLocale) NotAValidType() string { return `has a primitive type that is NOT VALID -- given: {{.given}} Expected valid values are:{{.expected}}` } +// Duplicated returns a format-string to format an error where types are duplicated func (l DefaultLocale) Duplicated() string { return `{{.type}} type is duplicated` } +// HttpBadStatus returns a format-string for errors when loading a schema using HTTP func (l DefaultLocale) HttpBadStatus() string { return `Could not read schema from HTTP, response status is {{.status}}` } +// ErrorFormat returns a format string for errors // Replacement options: field, description, context, value func (l DefaultLocale) ErrorFormat() string { return `{{.field}}: {{.description}}` } -//Parse error +// ParseError returns a format-string for JSON parsing errors func (l DefaultLocale) ParseError() string { return `Expected: {{.expected}}, given: Invalid JSON` } -//If/Else +// ConditionThen returns a format-string for ConditionThenError errors +// If/Else func (l DefaultLocale) ConditionThen() string { return `Must validate "then" as "if" was valid` } +// ConditionElse returns a format-string for ConditionElseError errors func (l DefaultLocale) ConditionElse() string { return `Must validate "else" as "if" was not valid` } +// constants const ( STRING_NUMBER = "number" STRING_ARRAY_OF_STRINGS = "array of strings" diff --git a/result.go b/result.go index 040d35c..6033cbb 100644 --- a/result.go +++ b/result.go @@ -37,19 +37,34 @@ type ( // ResultError is the interface that library errors must implement ResultError interface { + // Field returns the field name without the root context + // i.e. firstName or person.firstName instead of (root).firstName or (root).person.firstName Field() string + // SetType sets the error-type SetType(string) + // Type returns the error-type Type() string + // SetContext sets the JSON-context for the error SetContext(*JsonContext) + // Context returns the JSON-context of the error Context() *JsonContext + // SetDescription sets a description for the error SetDescription(string) + // Description returns the description of the error Description() string + // SetDescriptionFormat sets the format for the description in the default text/template format SetDescriptionFormat(string) + // DescriptionFormat returns the format for the description in the default text/template format DescriptionFormat() string + // SetValue sets the value related to the error SetValue(interface{}) + // Value returns the value related to the error Value() interface{} + // SetDetails sets the details specific to the error SetDetails(ErrorDetails) + // Details returns details about the error Details() ErrorDetails + // String returns a string representation of the error String() string } @@ -65,6 +80,7 @@ type ( details ErrorDetails } + // Result holds the result of a validation Result struct { errors []ResultError // Scores how well the validation matched. Useful in generating @@ -73,60 +89,73 @@ type ( } ) -// Field outputs the field name without the root context +// Field returns the field name without the root context // i.e. firstName or person.firstName instead of (root).firstName or (root).person.firstName func (v *ResultErrorFields) Field() string { return strings.TrimPrefix(v.context.String(), STRING_ROOT_SCHEMA_PROPERTY+".") } +// SetType sets the error-type func (v *ResultErrorFields) SetType(errorType string) { v.errorType = errorType } +// Type returns the error-type func (v *ResultErrorFields) Type() string { return v.errorType } +// SetContext sets the JSON-context for the error func (v *ResultErrorFields) SetContext(context *JsonContext) { v.context = context } +// Context returns the JSON-context of the error func (v *ResultErrorFields) Context() *JsonContext { return v.context } +// SetDescription sets a description for the error func (v *ResultErrorFields) SetDescription(description string) { v.description = description } +// Description returns the description of the error func (v *ResultErrorFields) Description() string { return v.description } +// SetDescriptionFormat sets the format for the description in the default text/template format func (v *ResultErrorFields) SetDescriptionFormat(descriptionFormat string) { v.descriptionFormat = descriptionFormat } +// DescriptionFormat returns the format for the description in the default text/template format func (v *ResultErrorFields) DescriptionFormat() string { return v.descriptionFormat } +// SetValue sets the value related to the error func (v *ResultErrorFields) SetValue(value interface{}) { v.value = value } +// Value returns the value related to the error func (v *ResultErrorFields) Value() interface{} { return v.value } +// SetDetails sets the details specific to the error func (v *ResultErrorFields) SetDetails(details ErrorDetails) { v.details = details } +// Details returns details about the error func (v *ResultErrorFields) Details() ErrorDetails { return v.details } +// String returns a string representation of the error func (v ResultErrorFields) String() string { // as a fallback, the value is displayed go style valueString := fmt.Sprintf("%v", v.value) @@ -152,15 +181,17 @@ func (v ResultErrorFields) String() string { }) } +// Valid indicates if no errors were found func (v *Result) Valid() bool { return len(v.errors) == 0 } +// Errors returns the errors that were found func (v *Result) Errors() []ResultError { return v.errors } -// Add a fully filled error to the error set +// AddError appends a fully filled error to the error set // SetDescription() will be called with the result of the parsed err.DescriptionFormat() func (v *Result) AddError(err ResultError, details ErrorDetails) { if _, exists := details["context"]; !exists && err.Context() != nil { diff --git a/schema.go b/schema.go index 3859056..e7ae4bc 100644 --- a/schema.go +++ b/schema.go @@ -45,10 +45,12 @@ var ( ErrorTemplateFuncs template.FuncMap ) +// NewSchema instances a schema using the given JSONLoader func NewSchema(l JSONLoader) (*Schema, error) { return NewSchemaLoader().Compile(l) } +// Schema holds a schema type Schema struct { documentReference gojsonreference.JsonReference rootSchema *subSchema @@ -61,6 +63,7 @@ func (d *Schema) parse(document interface{}, draft Draft) error { return d.parseSchema(document, d.rootSchema) } +// SetRootSchemaName sets the root-schema name func (d *Schema) SetRootSchemaName(name string) { d.rootSchema.property = name } diff --git a/schemaLoader.go b/schemaLoader.go index 95e0568..20db0c1 100644 --- a/schemaLoader.go +++ b/schemaLoader.go @@ -21,6 +21,7 @@ import ( "github.com/xeipuuv/gojsonreference" ) +// SchemaLoader is used to load schemas type SchemaLoader struct { pool *schemaPool AutoDetect bool @@ -28,6 +29,7 @@ type SchemaLoader struct { Draft Draft } +// NewSchemaLoader creates a new NewSchemaLoader func NewSchemaLoader() *SchemaLoader { ps := &SchemaLoader{ @@ -141,6 +143,7 @@ func (sl *SchemaLoader) AddSchema(url string, loader JSONLoader) error { return sl.pool.parseReferences(doc, ref, true) } +// Compile loads and compiles a schema func (sl *SchemaLoader) Compile(rootSchema JSONLoader) (*Schema, error) { ref, err := rootSchema.JsonReference() diff --git a/subSchema.go b/subSchema.go index 362d86c..02c290c 100644 --- a/subSchema.go +++ b/subSchema.go @@ -35,6 +35,7 @@ import ( "github.com/xeipuuv/gojsonreference" ) +// Constants const ( KEY_SCHEMA = "$schema" KEY_ID = "id" diff --git a/types.go b/types.go index 952d22e..0e6fd51 100644 --- a/types.go +++ b/types.go @@ -25,6 +25,7 @@ package gojsonschema +// Type constants const ( TYPE_ARRAY = `array` TYPE_BOOLEAN = `boolean` @@ -35,7 +36,10 @@ const ( TYPE_STRING = `string` ) +// JSON_TYPES hosts the list of type that are supported in JSON var JSON_TYPES []string + +// SCHEMA_TYPES hosts the list of type that are supported in schemas var SCHEMA_TYPES []string func init() { diff --git a/validation.go b/validation.go index 90f9043..c2f33dd 100644 --- a/validation.go +++ b/validation.go @@ -35,6 +35,7 @@ import ( "unicode/utf8" ) +// Validate loads and validates a JSON schema func Validate(ls JSONLoader, ld JSONLoader) (*Result, error) { // load schema schema, err := NewSchema(ls) @@ -44,6 +45,7 @@ func Validate(ls JSONLoader, ld JSONLoader) (*Result, error) { return schema.Validate(ld) } +// Validate loads and validates a JSON document func (v *Schema) Validate(l JSONLoader) (*Result, error) { root, err := l.LoadJSON() if err != nil {