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.
nullable
Whether this definiton can be null regardless of type. False by default.
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.