txt: ## dist_cpan-JNTHN-OpenAPI-Schema-Validate.md
  # OpenAPI::Schema::Validate
  
  Validates a value or data structure (of hashes and arrays) against an OpenAPI
  schema definition.
  
  ## Synopsis
  
  ```
  use OpenAPI::Schema::Validate;
  
  # A schema should have been deserialized into a hash at the top level.
  # It will have been if you use this with OpenAPI::Model.
  my $schema = OpenAPI::Schema::Validate.new(
      schema => from-json '{ "type": "string" }'
  );
  
  # Validate it and use the result as a boolean.
  say so $schema.validate("foo");     # True
  say so $schema.validate(42);        # False
  say so $schema.validate(Str);       # False
  
  # Validate it in sink context; Failure throws if there's a validation
  # error; catch it and us the `reason` property for diagnostics.
  for "foo", 42, Str -> $test {
      $schema.validate($est);
      say "$test.perl() is valid";
      CATCH {
          when X::OpenAPI::Schema::Validate::Failed {
              say "$test.perl() is not valid at $_.path(): $_.reason()";
          }
      }
  }
  
  ```
  
  ## Methods
  
  ### new(:%schema!, :%formats, :%add-formats)
  
  Constructs a schema validation object, checking the schema for any errors
  (for example, properties having the wrong type of value, or `pattern` using
  regex syntax beyond that allowed by the OpenAPI specification).
  
  By default, the following values of `format` are recognized and enforced:
  
  * `date-time` (as defined by date-time in RFC3339)
  * `date` (as defined by full-date in RFC3339)
  * `time` (as defined by full-time in RFC3339)
  * `email` (as defined by RFC5322, section 3.4.1)
  * `idn-email` (as defined by RFC6531)
  * `hostname` (as defined by RFC1034 section 3.1, including host names produced
    using the Punycode algorithm specified in RFC5891 section 4.4)
  * `idn-hostname` (as defined by either RFC1034 as for hostname, or an
    internationalized hostname as defined by RFC5890, section 2.3.2.3).
  * `ipv4` (an IPv4 address according to the "dotted-quad" ABNF syntax as
    defined in RFC2673 section 3.2)
  * `ipv6` (an IPv6 address as defined in RFC4291 section 2.2)
  * `uri` (a valid URI as defiend by RFC3986)
  * `uri-reference` (a valid URI or relative-reference as defined by RFC3986)
  * `iri` (a valid IRI as defined by RFC3987)
  * `iri-reference` (a valid IRI or relative-reference as defiend by RFC3987)
  * `uri-template` (a valid URI template as defined by RFC6570)
  * `json-pointer` (a valid representation of a JSON pointer as defiend by
    RFC6901 section 5)
  * `relative-json-pointer` (a valid representation of a `relative-json-pointer`
    as defined by RFC6901)
  * `regex` (a valid regex according to the ECMA 262 regular expression dialect)
  * `int32` (range check)
  * `int64` (range check)
  * `binary` (when `string` type and `binary` format are used, then instead of
    checking for `Str`, we check for `Blob`)
  
  All other `format` strings are ignored. However, it is possible to extend the
  validator to support additional formats by passing a hash as the `add-formats`
  named argument. The keys are the additional format to support, and the value
  will be something used in a smartmatch against the value being validated. The
  most common choices for this will be `Regex` or a `Block`.
  
  ```
      my $schema = OpenAPI::Schema::Validate.new(
          schema => from-json '{ "type": "string" }',
          add-formats => {
              isbn => /^(97(8|9))?\d{9}(\d|X)$/,
              percentage => { 0 <= $_ <= 100 }
          }
      );
  
  ```
  
  Passing `formats` allows complete control over the formats that are validated.
  To disable all format validation, pass `formats => {}`.
  
  ### validate($value, :$read, :$write)
  
  Performs validation of the passed value. Returns `True` if the validation is
  successful, and a `Failure` if it is unsuccessful. This allows use in both a
  boolean context, or a sink context in which case the failiure will be sunk and
  an exception of type `X::OpenAPI::Schema::Validate::Failed` thrown.
  
  OpenAPI schemas may contain the `readOnly` and `writeOnly` properties. These
  are used for properties that may only show up in responses and requets
  respectively. Thus, pass `:read` when validating a response, and `:write` when
  validating a request, in order to allow the appropriate properties to pass (or
  fail) validation. If neither of `:read` and `:write` are passed then both
  `readOnly` and `writeOnly` will always fail.
  