summaryrefslogtreecommitdiff
path: root/vendor/github.com/xeipuuv/gojsonschema/README.md
diff options
context:
space:
mode:
authorValentin Rothberg <rothberg@redhat.com>2019-01-08 14:52:57 +0100
committerValentin Rothberg <rothberg@redhat.com>2019-01-11 13:38:11 +0100
commitbd40dcfc2bc7c9014ea1f33482fb63aacbcdfe87 (patch)
tree5f06e4e289f16d9164d692590a3fe6541b5384cf /vendor/github.com/xeipuuv/gojsonschema/README.md
parent545f24421247c9f6251a634764db3f8f8070a812 (diff)
downloadpodman-bd40dcfc2bc7c9014ea1f33482fb63aacbcdfe87.tar.gz
podman-bd40dcfc2bc7c9014ea1f33482fb63aacbcdfe87.tar.bz2
podman-bd40dcfc2bc7c9014ea1f33482fb63aacbcdfe87.zip
vendor: update everything
* If possible, update each dependency to the latest available version. * Use releases over commit IDs and avoid vendoring branches. Signed-off-by: Valentin Rothberg <rothberg@redhat.com>
Diffstat (limited to 'vendor/github.com/xeipuuv/gojsonschema/README.md')
-rw-r--r--vendor/github.com/xeipuuv/gojsonschema/README.md181
1 files changed, 176 insertions, 5 deletions
diff --git a/vendor/github.com/xeipuuv/gojsonschema/README.md b/vendor/github.com/xeipuuv/gojsonschema/README.md
index e02976bc6..24ca34744 100644
--- a/vendor/github.com/xeipuuv/gojsonschema/README.md
+++ b/vendor/github.com/xeipuuv/gojsonschema/README.md
@@ -1,10 +1,11 @@
+[![GoDoc](https://godoc.org/github.com/xeipuuv/gojsonschema?status.svg)](https://godoc.org/github.com/xeipuuv/gojsonschema)
[![Build Status](https://travis-ci.org/xeipuuv/gojsonschema.svg)](https://travis-ci.org/xeipuuv/gojsonschema)
# gojsonschema
## Description
-An implementation of JSON Schema, based on IETF's draft v4 - Go language
+An implementation of JSON Schema for the Go programming language. Supports draft-04, draft-06 and draft-07.
References :
@@ -54,7 +55,6 @@ func main() {
fmt.Printf("- %s\n", desc)
}
}
-
}
@@ -148,6 +148,87 @@ To check the result :
}
```
+
+## Loading local schemas
+
+By default `file` and `http(s)` references to external schemas are loaded automatically via the file system or via http(s). An external schema can also be loaded using a `SchemaLoader`.
+
+```go
+ sl := gojsonschema.NewSchemaLoader()
+ loader1 := gojsonschema.NewStringLoader(`{ "type" : "string" }`)
+ err := sl.AddSchema("http://some_host.com/string.json", loader1)
+```
+
+Alternatively if your schema already has an `$id` you can use the `AddSchemas` function
+```go
+ loader2 := gojsonschema.NewStringLoader(`{
+ "$id" : "http://some_host.com/maxlength.json",
+ "maxLength" : 5
+ }`)
+ err = sl.AddSchemas(loader2)
+```
+
+The main schema should be passed to the `Compile` function. This main schema can then directly reference the added schemas without needing to download them.
+```go
+ loader3 := gojsonschema.NewStringLoader(`{
+ "$id" : "http://some_host.com/main.json",
+ "allOf" : [
+ { "$ref" : "http://some_host.com/string.json" },
+ { "$ref" : "http://some_host.com/maxlength.json" }
+ ]
+ }`)
+
+ schema, err := sl.Compile(loader3)
+
+ documentLoader := gojsonschema.NewStringLoader(`"hello world"`)
+
+ result, err := schema.Validate(documentLoader)
+```
+
+It's also possible to pass a `ReferenceLoader` to the `Compile` function that references a loaded schema.
+
+```go
+err = sl.AddSchemas(loader3)
+schema, err := sl.Compile(gojsonschema.NewReferenceLoader("http://some_host.com/main.json"))
+```
+
+Schemas added by `AddSchema` and `AddSchemas` are only validated when the entire schema is compiled, unless meta-schema validation is used.
+
+## Using a specific draft
+By default `gojsonschema` will try to detect the draft of a schema by using the `$schema` keyword and parse it in a strict draft-04, draft-06 or draft-07 mode. If `$schema` is missing, or the draft version is not explicitely set, a hybrid mode is used which merges together functionality of all drafts into one mode.
+
+Autodectection can be turned off with the `AutoDetect` property. Specific draft versions can be specified with the `Draft` property.
+
+```go
+sl := gojsonschema.NewSchemaLoader()
+sl.Draft = gojsonschema.Draft7
+sl.AutoDetect = false
+```
+
+If autodetection is on (default), a draft-07 schema can savely reference draft-04 schemas and vice-versa, as long as `$schema` is specified in all schemas.
+
+## Meta-schema validation
+Schemas that are added using the `AddSchema`, `AddSchemas` and `Compile` can be validated against their meta-schema by setting the `Validate` property.
+
+The following example will produce an error as `multipleOf` must be a number. If `Validate` is off (default), this error is only returned at the `Compile` step.
+
+```go
+sl := gojsonschema.NewSchemaLoader()
+sl.Validate = true
+err := sl.AddSchemas(gojsonschema.NewStringLoader(`{
+ $id" : "http://some_host.com/invalid.json",
+ "$schema": "http://json-schema.org/draft-07/schema#",
+ "multipleOf" : true
+}`))
+ ```
+```
+ ```
+
+Errors returned by meta-schema validation are more readable and contain more information, which helps significantly if you are developing a schema.
+
+Meta-schema validation also works with a custom `$schema`. In case `$schema` is missing, or `AutoDetect` is set to `false`, the meta-schema of the used draft is used.
+
+
## Working with Errors
The library handles string error codes which you can customize by creating your own gojsonschema.locale and setting it
@@ -155,7 +236,9 @@ The library handles string error codes which you can customize by creating your
gojsonschema.Locale = YourCustomLocale{}
```
-However, each error contains additional contextual information.
+However, each error contains additional contextual information.
+
+Newer versions of `gojsonschema` may have new additional errors, so code that uses a custom locale will need to be updated when this happens.
**err.Type()**: *string* Returns the "type" of error that occurred. Note you can also type check. See below
@@ -169,15 +252,18 @@ Note: An error of RequiredType has an err.Type() return value of "required"
"number_not": NumberNotError
"missing_dependency": MissingDependencyError
"internal": InternalError
+ "const": ConstEror
"enum": EnumError
"array_no_additional_items": ArrayNoAdditionalItemsError
"array_min_items": ArrayMinItemsError
"array_max_items": ArrayMaxItemsError
"unique": ItemsMustBeUniqueError
+ "contains" : ArrayContainsError
"array_min_properties": ArrayMinPropertiesError
"array_max_properties": ArrayMaxPropertiesError
"additional_property_not_allowed": AdditionalPropertyNotAllowedError
"invalid_property_pattern": InvalidPropertyPatternError
+ "invalid_property_name": InvalidPropertyNameError
"string_gte": StringLengthGTEError
"string_lte": StringLengthLTEError
"pattern": DoesNotMatchPatternError
@@ -186,15 +272,19 @@ Note: An error of RequiredType has an err.Type() return value of "required"
"number_gt": NumberGTError
"number_lte": NumberLTEError
"number_lt": NumberLTError
+ "condition_then" : ConditionThenError
+ "condition_else" : ConditionElseError
**err.Value()**: *interface{}* Returns the value given
-**err.Context()**: *gojsonschema.jsonContext* Returns the context. This has a String() method that will print something like this: (root).firstName
+**err.Context()**: *gojsonschema.JsonContext* Returns the context. This has a String() method that will print something like this: (root).firstName
**err.Field()**: *string* Returns the fieldname in the format firstName, or for embedded properties, person.firstName. This returns the same as the String() method on *err.Context()* but removes the (root). prefix.
**err.Description()**: *string* The error description. This is based on the locale you are using. See the beginning of this section for overwriting the locale with a custom implementation.
+**err.DescriptionFormat()**: *string* The error description format. This is relevant if you are adding custom validation errors afterwards to the result.
+
**err.Details()**: *gojsonschema.ErrorDetails* Returns a map[string]interface{} of additional error details specific to the error. For example, GTE errors will have a "min" value, LTE will have a "max" value. See errors.go for a full description of all the error details. Every error always contains a "field" key that holds the value of *err.Field()*
Note in most cases, the err.Details() will be used to generate replacement strings in your locales, and not used directly. These strings follow the text/template format i.e.
@@ -225,10 +315,35 @@ Learn more about what types of template functions you can use in `ErrorTemplateF
## Formats
JSON Schema allows for optional "format" property to validate instances against well-known formats. gojsonschema ships with all of the formats defined in the spec that you can use like this:
+
````json
{"type": "string", "format": "email"}
````
-Available formats: date-time, hostname, email, ipv4, ipv6, uri, uri-reference.
+
+Not all formats defined in draft-07 are available. Implemented formats are:
+
+* `date`
+* `time`
+* `date-time`
+* `hostname`. Subdomains that start with a number are also supported, but this means that it doesn't strictly follow [RFC1034](http://tools.ietf.org/html/rfc1034#section-3.5) and has the implication that ipv4 addresses are also recognized as valid hostnames.
+* `email`. Go's email parser deviates slightly from [RFC5322](https://tools.ietf.org/html/rfc5322). Includes unicode support.
+* `idn-email`. Same caveat as `email`.
+* `ipv4`
+* `ipv6`
+* `uri`. Includes unicode support.
+* `uri-reference`. Includes unicode support.
+* `iri`
+* `iri-reference`
+* `uri-template`
+* `uuid`
+* `regex`. Go uses the [RE2](https://github.com/google/re2/wiki/Syntax) engine and is not [ECMA262](http://www.ecma-international.org/publications/files/ECMA-ST/Ecma-262.pdf) compatible.
+* `json-pointer`
+* `relative-json-pointer`
+
+`email`, `uri` and `uri-reference` use the same validation code as their unicode counterparts `idn-email`, `iri` and `iri-reference`. If you rely on unicode support you should use the specific
+unicode enabled formats for the sake of interoperability as other implementations might not support unicode in the regular formats.
+
+The validation code for `uri`, `idn-email` and their relatives use mostly standard library code. Go 1.5 and 1.6 contain some minor bugs with handling URIs and unicode. You are encouraged to use Go 1.7+ if you rely on these formats.
For repetitive or more complex formats, you can create custom format checkers and add them to gojsonschema like this:
@@ -285,7 +400,63 @@ func (f ValidUserIdFormatChecker) IsFormat(input interface{}) bool {
gojsonschema.FormatCheckers.Add("ValidUserId", ValidUserIdFormatChecker{})
````
+Formats can also be removed, for example if you want to override one of the formats that is defined by default.
+
+```go
+gojsonschema.FormatCheckers.Remove("hostname")
+```
+
+
+## Additional custom validation
+After the validation has run and you have the results, you may add additional
+errors using `Result.AddError`. This is useful to maintain the same format within the resultset instead
+of having to add special exceptions for your own errors. Below is an example.
+
+```go
+type AnswerInvalidError struct {
+ gojsonschema.ResultErrorFields
+}
+
+func newAnswerInvalidError(context *gojsonschema.JsonContext, value interface{}, details gojsonschema.ErrorDetails) *AnswerInvalidError {
+ err := AnswerInvalidError{}
+ err.SetContext(context)
+ err.SetType("custom_invalid_error")
+ // it is important to use SetDescriptionFormat() as this is used to call SetDescription() after it has been parsed
+ // using the description of err will be overridden by this.
+ err.SetDescriptionFormat("Answer to the Ultimate Question of Life, the Universe, and Everything is {{.answer}}")
+ err.SetValue(value)
+ err.SetDetails(details)
+
+ return &err
+}
+
+func main() {
+ // ...
+ schema, err := gojsonschema.NewSchema(schemaLoader)
+ result, err := gojsonschema.Validate(schemaLoader, documentLoader)
+
+ if true { // some validation
+ jsonContext := gojsonschema.NewJsonContext("question", nil)
+ errDetail := gojsonschema.ErrorDetails{
+ "answer": 42,
+ }
+ result.AddError(
+ newAnswerInvalidError(
+ gojsonschema.NewJsonContext("answer", jsonContext),
+ 52,
+ errDetail,
+ ),
+ errDetail,
+ )
+ }
+
+ return result, err
+
+}
+```
+This is especially useful if you want to add validation beyond what the
+json schema drafts can provide such business specific logic.
## Uses