Conch::Plugin::JSONValidator

SOURCE

https://github.com/joyent/conch-api/blob/master/lib/Conch/Plugin/JSONValidator.pm

SYNOPSIS

$app->plugin('Conch::Plugin::JSONValidator');

[ ... in a controller ]

sub endpoint ($c) {
    my $query_params = $c->validate_query_params('MyQueryParamsDefinition');
    return if not $query_params;

    my $body = $c->validate_request('MyRequestDefinition');
    return if not $body;
    ...
}

DESCRIPTION

Provides a mechanism to validate request and response payloads from an API endpoint against a JSON Schema.

METHODS

register

Sets up the helpers.

HELPERS

These methods are made available on the $c object (the invocant of all controller methods, and therefore other helpers).

validate_query_params

Given the name of a json schema in the query_params namespace, validate the provided data against it (defaulting to the request’s query parameters converted into a hashref: parameters appearing once are scalars, parameters appearing more than once have their values in an arrayref).

Because values are being parsed from the URI string, all values are strings even if they look like numbers.

On failure, an HTTP 400 response is prepared, using the response.json#/$defs/QueryParamsValidationError json response schema.

Population of missing data from specified defaults is performed. Returns a boolean.

validate_request

Given the name of a json schema in the request namespace, validate the provided payload against it (defaulting to the request’s json payload).

On failure, an HTTP 400 response is prepared, using the response.json#/$defs/RequestValidationError json response schema.

Returns a boolean.

json_schema_validator

Returns a JSON::Schema::Draft201909 object with all JSON Schemas pre-loaded.

normalize_evaluation_result

Rewrite a JSON::Schema::Draft201909::Result to match the format used by response.json#/$defs/JSONSchemaError.

add_link_to_schema

Adds a response header of the form:

Link: <http://example.com/my-schema>; rel="describedby"

…indicating the JSON Schema that describes the response.

HOOKS

around_action

Before a controller action is executed, validate the incoming query parameters and request body payloads against the schemas in the stash variables query_params_schema and request_schema, respectively.

Performs more checks when this “feature” in Conch::Plugin::Features is enabled:

• validate_all_requests

  Assumes the query parameters schema is query_params.json#/$defs/Null when not provided; assumes the request body schema is request.json#/$defs/Null when not provided (for POST, PUT, DELETE requests)

after_dispatch

Runs after dispatching is complete.

Performs more checks when this “feature” in Conch::Plugin::Features is enabled:

• validate_all_responses

  When not provided, assumes the response body schema is response.json#/$defs/Null (for all 2xx responses), or response.json#/$defs/Error (for 4xx responses).

LICENSING

Copyright Joyent, Inc.

This Source Code Form is subject to the terms of the Mozilla Public License, v.2.0. If a copy of the MPL was not distributed with this file, You can obtain one at https://www.mozilla.org/en-US/MPL/2.0/.