NAME

Whelk::Schema::Definition - Base class for a Whelk type

SYNOPSIS

        my $definition = Whelk::Schema->build(
                name => {
                        type => 'integer',
                }
        );

DESCRIPTION

Definition is a base class for schemas. Whelk::Schema is just a factory and register for definitions. This class is abstract and does not do anything by itself, but a number of subclasses exist which implement different OpenAPI types.

Definitions use names inhale to describe data validation and exhale for data coercion. Inhaling is recursively checking the entire input to see if it conforms to the definition. Exhaling is recursively adjusting the entire output structure so that it has all the values in line with the definition (for example, changing a boolean field to a real boolean on endpoint output). Exhaling is not a standalone process, as it assumes data was inhaled previously - exhaling without inhaling can lead to problems like warnings or even fatal errors.

Inhaling will short-circuit if it encounters an error and return a string which describes where and what type of problem it encountered. For example, it may return 'boolean' if a definition was boolean and the value was a string. For the same boolean definition, the error may also be 'defined' if the value was not defined - the string is not always the name of the type, but rather which Whelk assumption has failed (which may be a more basic assumption than the actual type). For nested types like objects it will return something like 'object[key]->boolean'. It should be pretty obvious where the problem is based on those strings, but since it short circuits it may require a couple of runs to weed out all the errors.

ATTRIBUTES

There attributes are common for all definitions.

name

Name of this schema, cannot be set in the constructor - is only set through creating a named schema in "build" in Whelk::Schema.

required

Whether this definition is required. It's needed for cases where it is nested inside an object or inside parameters for an endpoint.

description

OpenAPI description of this definition.

rules

An array reference of extra validation rules.

METHODS

create

Constructs a definition. Unlike new which only accepts a hash, it does all the tricks described in "Defining a schema" in Whelk::Schema. Should not be called directly, use "build" in Whelk::Schema instead.

clone

        my $new = $definition->clone(%more_data);

Clones this definition and optionally merges its contents with %more_data, if present. The merge is recursive is the done in the same way Kelp config files are merged. It's used for extending schemas using [\'schema_name', %args] syntax. There should be no need to ever call this directly.

empty

        my $is_empty = $definition->empty;

Whether this definition is empty. It is a special measure to check for Whelk::Schema::Definition::Empty, which is implementing 204 No Content responses.

has_default

Whether this definition has a default value.

inhale

        my $error_or_undef = $definition->inhale($data);

Must be implemented in a subclass.

Inhales data to see if it likes it. See "DESCRIPTION" for more data on inhaling and exhaling.

exhale

        my $adjusted_data = $definition->exhale($data);

Must be implemented in a subclass.

Exhales the data in form described in the definition. See "DESCRIPTION" for more data on inhaling and exhaling.

inhale_or_error

        $definition->inhale_or_error($data, $error_sub = sub {});

Calls "inhale" and calls $error_sub if it failed. The sub will get passed the return value of inhale as its only argument. If the sub is not passed or does not throw an exception, a stock exception will be thrown with the error and dumped $data.

inhale_exhale

        my $adjusted_data = $definition->inhale_exhale($data, $error_sub = sub {});

Both "inhale" and "exhale" in one call. Uses "inhale_or_error" under the hood, so inhaling errors will throw an exception.

openapi_dump

        my $perl_struct = $definition->openapi_dump($obj, %hints);

Must be implemented in a subclass.

Returns the structure which describes this type for the OpenAPI document. Should not be called directly, as it is called by "openapi_schema".

openapi_schema

        my $perl_struct = $definition->openapi_schema($obj, %hints);

Returns the structure which describes this type for the OpenAPI document. It usually just calls "openapi_dump".

$obj should be an object of Whelk::OpenAPI or similar. It should at least implement method location_for_schema.

%hints are special hints which change how the schema is produced. Currently, just a couple hints are defined:

If full hint is present and true, the top level definition will be dumped in full, even if it is a named schema. If not, it will be made a reference to a predefined schema.

Special parameters hint will change how object is treated, since objects are used to define all types of parameters of OpenAPI.

cpanm Whelk

perl -MCPAN -e shell
install Whelk