weaver.wps_restapi.swagger_definitions
Schema definitions for OpenAPI generation and validation of data from received requests and returned responses.
This module should contain any and every definition in use to build the Swagger UI and the OpenAPI JSON schema so that one can update the specification without touching any other files after the initial integration.
Schemas defined in this module are employed (through deserialize
method calls) to validate that data conforms to
reported definitions. This makes the documentation of the API better aligned with resulting code execution under it.
It also provides a reference point for external users to understand expected data structures with complete schema
definitions generated on the exposed endpoints (JSON and Swagger UI).
The definitions are also employed to generate the OpenAPI definitions reported in the documentation published on Weaver’s ReadTheDocs page.
Module Contents
- weaver.wps_restapi.swagger_definitions.CWL_REPO_URL = 'https://github.com/common-workflow-language'[source]
- weaver.wps_restapi.swagger_definitions.IO_INFO_IDS = 'Identifier of the {first} {what}. To merge details between corresponding {first} and {second}...'[source]
- weaver.wps_restapi.swagger_definitions.OGC_API_REPO_URL = 'https://github.com/opengeospatial/ogcapi-processes'[source]
- weaver.wps_restapi.swagger_definitions.OGC_API_SCHEMA_URL = 'https://raw.githubusercontent.com/opengeospatial/ogcapi-processes'[source]
- weaver.wps_restapi.swagger_definitions.OGC_API_PROC_PART1 = 'https://schemas.opengis.net/ogcapi/processes/part1/1.0'[source]
- weaver.wps_restapi.swagger_definitions.PROCESS_DESCRIPTION_FIELD_FIRST = ['id', 'title', 'version', 'mutable', 'abstract', 'description', 'keywords', 'metadata',...[source]
- weaver.wps_restapi.swagger_definitions.PROCESS_DESCRIPTION_FIELD_AFTER = ['processDescriptionURL', 'processEndpointWPS1', 'executeEndpoint', 'deploymentProfile', 'links'][source]
- weaver.wps_restapi.swagger_definitions.PROCESS_DESCRIPTION_FIELD_FIRST_OLD_SCHEMA = ['process'][source]
- weaver.wps_restapi.swagger_definitions.PROCESS_DESCRIPTION_FIELD_AFTER_OLD_SCHEMA = ['links'][source]
- weaver.wps_restapi.swagger_definitions.PROCESS_IO_FIELD_FIRST = ['id', 'title', 'description', 'minOccurs', 'maxOccurs'][source]
- weaver.wps_restapi.swagger_definitions.PROCESS_IO_FIELD_AFTER = ['literalDataDomains', 'formats', 'crs', 'bbox'][source]
- weaver.wps_restapi.swagger_definitions.PROCESSES_LISTING_FIELD_FIRST = ['description', 'processes', 'providers'][source]
- weaver.wps_restapi.swagger_definitions.PROCESSES_LISTING_FIELD_AFTER = ['page', 'limit', 'count', 'total', 'links'][source]
- weaver.wps_restapi.swagger_definitions.PROVIDER_DESCRIPTION_FIELD_FIRST = ['id', 'title', 'version', 'mutable', 'description', 'url', 'type', 'public', 'keywords', 'metadata'][source]
- weaver.wps_restapi.swagger_definitions.JOBS_LISTING_FIELD_FIRST = ['description', 'jobs', 'groups'][source]
- weaver.wps_restapi.swagger_definitions.JOBS_LISTING_FIELD_AFTER = ['page', 'limit', 'count', 'total', 'links'][source]
- weaver.wps_restapi.swagger_definitions.QUOTES_LISTING_FIELD_FIRST = ['description', 'quotations'][source]
- weaver.wps_restapi.swagger_definitions.QUOTES_LISTING_FIELD_AFTER = ['page', 'limit', 'count', 'total', 'links'][source]
- class weaver.wps_restapi.swagger_definitions.SLUG(*args, **kwargs)[source]
Base schema node with support of extended functionalities.
Combines all
colander.SchemaNode
extensions so thatdefault
keyword is used first to resolve a missing field value duringdeserialize()
call, and then removes the node completely if nodefault
was provided, and evaluate variables as needed.See also
ExtendedMappingSchema
ExtendedSequenceSchema
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
- class weaver.wps_restapi.swagger_definitions.Tag(*args, **kwargs)[source]
Base schema node with support of extended functionalities.
Combines all
colander.SchemaNode
extensions so thatdefault
keyword is used first to resolve a missing field value duringdeserialize()
call, and then removes the node completely if nodefault
was provided, and evaluate variables as needed.See also
ExtendedMappingSchema
ExtendedSequenceSchema
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
- class weaver.wps_restapi.swagger_definitions.URL(*args, **kwargs)[source]
Base schema node with support of extended functionalities.
Combines all
colander.SchemaNode
extensions so thatdefault
keyword is used first to resolve a missing field value duringdeserialize()
call, and then removes the node completely if nodefault
was provided, and evaluate variables as needed.See also
ExtendedMappingSchema
ExtendedSequenceSchema
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
- class weaver.wps_restapi.swagger_definitions.MediaType(*args, **kwargs)[source]
Base schema node with support of extended functionalities.
Combines all
colander.SchemaNode
extensions so thatdefault
keyword is used first to resolve a missing field value duringdeserialize()
call, and then removes the node completely if nodefault
was provided, and evaluate variables as needed.See also
ExtendedMappingSchema
ExtendedSequenceSchema
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
- class weaver.wps_restapi.swagger_definitions.QueryBoolean(*_: Any, **__: Any)[source]
A type representing a boolean object.
The constructor accepts these keyword arguments:
false_choices
: The set of strings representing aFalse
value on deserialization.true_choices
: The set of strings representing aTrue
value on deserialization.false_val
: The value returned on serialization of a False value.true_val
: The value returned on serialization of a True value.
During deserialization, a value contained in
false_choices
, will be consideredFalse
.The behaviour for values not contained in
false_choices
depends ontrue_choices
: if it’s empty, any value is consideredTrue
; otherwise, only values contained intrue_choices
are consideredTrue
, and an Invalid exception would be raised for values outside of bothfalse_choices
andtrue_choices
.Serialization will produce
true_val
orfalse_val
based on the value.If the
colander.null
value is passed to the serialize method of this class, thecolander.null
value will be returned.The subnodes of the
colander.SchemaNode
that wraps this type are ignored.Initializes the extended boolean schema node.
When arguments
true_choices
orfalse_choices
are provided, the corresponding string values are respectively considered as valid truthy/falsy values. Otherwise (default),strict
values only of explicit typebool
will be considered valid.When values are specified
colander
converts them to string lowercase to compare against truthy/falsy values it should accept. For real OpenAPI typing validation, do NOT add other values like"1"
to avoid conflict withExtendedInteger
type for schemas that support both variants. If an OpenAPI field is expected to support truthy/falsy values, it is recommended to explicitly define its schema using aoneOf
keyword of all relevant schemas it supports, an any applicable validators for explicit values. This is the safest way to ensure the generated OpenAPI schema corresponds to expected type validation.
- class weaver.wps_restapi.swagger_definitions.DateTimeInterval(*args, **kwargs)[source]
Base schema node with support of extended functionalities.
Combines all
colander.SchemaNode
extensions so thatdefault
keyword is used first to resolve a missing field value duringdeserialize()
call, and then removes the node completely if nodefault
was provided, and evaluate variables as needed.See also
ExtendedMappingSchema
ExtendedSequenceSchema
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
- class weaver.wps_restapi.swagger_definitions.S3BucketReference(*args, **kwargs)[source]
Base schema node with support of extended functionalities.
Combines all
colander.SchemaNode
extensions so thatdefault
keyword is used first to resolve a missing field value duringdeserialize()
call, and then removes the node completely if nodefault
was provided, and evaluate variables as needed.See also
ExtendedMappingSchema
ExtendedSequenceSchema
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
- class weaver.wps_restapi.swagger_definitions.FileLocal(*args, **kwargs)[source]
Base schema node with support of extended functionalities.
Combines all
colander.SchemaNode
extensions so thatdefault
keyword is used first to resolve a missing field value duringdeserialize()
call, and then removes the node completely if nodefault
was provided, and evaluate variables as needed.See also
ExtendedMappingSchema
ExtendedSequenceSchema
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
- class weaver.wps_restapi.swagger_definitions.FileURL(*args, **kwargs)[source]
Base schema node with support of extended functionalities.
Combines all
colander.SchemaNode
extensions so thatdefault
keyword is used first to resolve a missing field value duringdeserialize()
call, and then removes the node completely if nodefault
was provided, and evaluate variables as needed.See also
ExtendedMappingSchema
ExtendedSequenceSchema
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
- class weaver.wps_restapi.swagger_definitions.VaultReference(*args, **kwargs)[source]
Base schema node with support of extended functionalities.
Combines all
colander.SchemaNode
extensions so thatdefault
keyword is used first to resolve a missing field value duringdeserialize()
call, and then removes the node completely if nodefault
was provided, and evaluate variables as needed.See also
ExtendedMappingSchema
ExtendedSequenceSchema
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
- class weaver.wps_restapi.swagger_definitions.ProcessURL(*args, **kwargs)[source]
Base schema node with support of extended functionalities.
Combines all
colander.SchemaNode
extensions so thatdefault
keyword is used first to resolve a missing field value duringdeserialize()
call, and then removes the node completely if nodefault
was provided, and evaluate variables as needed.See also
ExtendedMappingSchema
ExtendedSequenceSchema
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
- class weaver.wps_restapi.swagger_definitions.ReferenceURL(*args, **kwargs)[source]
Allows specifying all mapping schemas that can be matched for an underlying schema definition.
Corresponds to the
anyOf
specifier of OpenAPI specification.Contrary to
OneOfKeywordSchema
that MUST be validated with exactly one schema, this definition will continue parsing all possibilities and apply validated sub-schemas on top of each other. Not all schemas have to be valid like in the case ofAllOfKeywordSchema
to succeed, as long as at least one of them is valid.Example:
class RequiredItem(ExtendedMappingSchema): item = ExtendedSchemaNode(String()) class RequiredType(ExtendedMappingSchema): type = ExtendedSchemaNode(String()) class RequiredFields(ExtendedMappingSchema): field_str = ExtendedSchemaNode(String()) field_int = ExtendedSchemaNode(Integer()) class AnyRequired(AnyKeywordSchema): _any_of = [RequiredItem(), RequiredType(), RequiredFields()] # following is valid because their individual parts have all required sub-fields, result is their composition AnyRequired().deserialize({"type": "test", "item": "valid"}) # result: {"type": "test", "item": "valid"} # following is also valid because even though 'item' is missing, the 'type' is present AnyRequired().deserialize({"type": "test"}) # result: {"type": "test"} # following is invalid because every one of the sub-field of individual parts are missing AnyRequired().deserialize({"type": "test"}) # following is invalid because fields of 'RequiredFields' are only partially fulfilled AnyRequired().deserialize({"field_str": "str"}) # following is valid because although fields of 'RequiredFields' are not all fulfilled, 'RequiredType' is valid AnyRequired().deserialize({"field_str": "str", "type": "str"}) # result: {"type": "test"} # following is invalid because 'RequiredFields' field 'field_int' is incorrect schema type AnyRequired().deserialize({"field_str": "str", "field_int": "str"}) # following is valid, but result omits 'type' because its schema-type is incorrect, while others are valid AnyRequired().deserialize({"field_str": "str", "field_int": 1, "items": "fields", "type": 1}) # result: {"field_str": "str", "field_int": 1, "items": "fields"}
Warning
Because valid items are applied on top of each other by merging fields during combinations, conflicting field names of any valid schema will contain only the final valid parsing during deserialization.
See also
OneOfKeywordSchema
AllOfKeywordSchema
NotKeywordSchema
- class weaver.wps_restapi.swagger_definitions.ExecuteReferenceURL(*args, **kwargs)[source]
Allows specifying all mapping schemas that can be matched for an underlying schema definition.
Corresponds to the
anyOf
specifier of OpenAPI specification.Contrary to
OneOfKeywordSchema
that MUST be validated with exactly one schema, this definition will continue parsing all possibilities and apply validated sub-schemas on top of each other. Not all schemas have to be valid like in the case ofAllOfKeywordSchema
to succeed, as long as at least one of them is valid.Example:
class RequiredItem(ExtendedMappingSchema): item = ExtendedSchemaNode(String()) class RequiredType(ExtendedMappingSchema): type = ExtendedSchemaNode(String()) class RequiredFields(ExtendedMappingSchema): field_str = ExtendedSchemaNode(String()) field_int = ExtendedSchemaNode(Integer()) class AnyRequired(AnyKeywordSchema): _any_of = [RequiredItem(), RequiredType(), RequiredFields()] # following is valid because their individual parts have all required sub-fields, result is their composition AnyRequired().deserialize({"type": "test", "item": "valid"}) # result: {"type": "test", "item": "valid"} # following is also valid because even though 'item' is missing, the 'type' is present AnyRequired().deserialize({"type": "test"}) # result: {"type": "test"} # following is invalid because every one of the sub-field of individual parts are missing AnyRequired().deserialize({"type": "test"}) # following is invalid because fields of 'RequiredFields' are only partially fulfilled AnyRequired().deserialize({"field_str": "str"}) # following is valid because although fields of 'RequiredFields' are not all fulfilled, 'RequiredType' is valid AnyRequired().deserialize({"field_str": "str", "type": "str"}) # result: {"type": "test"} # following is invalid because 'RequiredFields' field 'field_int' is incorrect schema type AnyRequired().deserialize({"field_str": "str", "field_int": "str"}) # following is valid, but result omits 'type' because its schema-type is incorrect, while others are valid AnyRequired().deserialize({"field_str": "str", "field_int": 1, "items": "fields", "type": 1}) # result: {"field_str": "str", "field_int": 1, "items": "fields"}
Warning
Because valid items are applied on top of each other by merging fields during combinations, conflicting field names of any valid schema will contain only the final valid parsing during deserialization.
See also
OneOfKeywordSchema
AllOfKeywordSchema
NotKeywordSchema
- class weaver.wps_restapi.swagger_definitions.UUID(*args, **kwargs)[source]
Base schema node with support of extended functionalities.
Combines all
colander.SchemaNode
extensions so thatdefault
keyword is used first to resolve a missing field value duringdeserialize()
call, and then removes the node completely if nodefault
was provided, and evaluate variables as needed.See also
ExtendedMappingSchema
ExtendedSequenceSchema
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
- class weaver.wps_restapi.swagger_definitions.AnyIdentifier(*args, **kwargs)[source]
Base schema node with support of extended functionalities.
Combines all
colander.SchemaNode
extensions so thatdefault
keyword is used first to resolve a missing field value duringdeserialize()
call, and then removes the node completely if nodefault
was provided, and evaluate variables as needed.See also
ExtendedMappingSchema
ExtendedSequenceSchema
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
- class weaver.wps_restapi.swagger_definitions.ProcessIdentifier(*args, **kwargs)[source]
Allows specifying all mapping schemas that can be matched for an underlying schema definition.
Corresponds to the
anyOf
specifier of OpenAPI specification.Contrary to
OneOfKeywordSchema
that MUST be validated with exactly one schema, this definition will continue parsing all possibilities and apply validated sub-schemas on top of each other. Not all schemas have to be valid like in the case ofAllOfKeywordSchema
to succeed, as long as at least one of them is valid.Example:
class RequiredItem(ExtendedMappingSchema): item = ExtendedSchemaNode(String()) class RequiredType(ExtendedMappingSchema): type = ExtendedSchemaNode(String()) class RequiredFields(ExtendedMappingSchema): field_str = ExtendedSchemaNode(String()) field_int = ExtendedSchemaNode(Integer()) class AnyRequired(AnyKeywordSchema): _any_of = [RequiredItem(), RequiredType(), RequiredFields()] # following is valid because their individual parts have all required sub-fields, result is their composition AnyRequired().deserialize({"type": "test", "item": "valid"}) # result: {"type": "test", "item": "valid"} # following is also valid because even though 'item' is missing, the 'type' is present AnyRequired().deserialize({"type": "test"}) # result: {"type": "test"} # following is invalid because every one of the sub-field of individual parts are missing AnyRequired().deserialize({"type": "test"}) # following is invalid because fields of 'RequiredFields' are only partially fulfilled AnyRequired().deserialize({"field_str": "str"}) # following is valid because although fields of 'RequiredFields' are not all fulfilled, 'RequiredType' is valid AnyRequired().deserialize({"field_str": "str", "type": "str"}) # result: {"type": "test"} # following is invalid because 'RequiredFields' field 'field_int' is incorrect schema type AnyRequired().deserialize({"field_str": "str", "field_int": "str"}) # following is valid, but result omits 'type' because its schema-type is incorrect, while others are valid AnyRequired().deserialize({"field_str": "str", "field_int": 1, "items": "fields", "type": 1}) # result: {"field_str": "str", "field_int": 1, "items": "fields"}
Warning
Because valid items are applied on top of each other by merging fields during combinations, conflicting field names of any valid schema will contain only the final valid parsing during deserialization.
See also
OneOfKeywordSchema
AllOfKeywordSchema
NotKeywordSchema
- class weaver.wps_restapi.swagger_definitions.ProcessIdentifierTag(*args, **kwargs)[source]
Allows specifying all mapping schemas that can be matched for an underlying schema definition.
Corresponds to the
anyOf
specifier of OpenAPI specification.Contrary to
OneOfKeywordSchema
that MUST be validated with exactly one schema, this definition will continue parsing all possibilities and apply validated sub-schemas on top of each other. Not all schemas have to be valid like in the case ofAllOfKeywordSchema
to succeed, as long as at least one of them is valid.Example:
class RequiredItem(ExtendedMappingSchema): item = ExtendedSchemaNode(String()) class RequiredType(ExtendedMappingSchema): type = ExtendedSchemaNode(String()) class RequiredFields(ExtendedMappingSchema): field_str = ExtendedSchemaNode(String()) field_int = ExtendedSchemaNode(Integer()) class AnyRequired(AnyKeywordSchema): _any_of = [RequiredItem(), RequiredType(), RequiredFields()] # following is valid because their individual parts have all required sub-fields, result is their composition AnyRequired().deserialize({"type": "test", "item": "valid"}) # result: {"type": "test", "item": "valid"} # following is also valid because even though 'item' is missing, the 'type' is present AnyRequired().deserialize({"type": "test"}) # result: {"type": "test"} # following is invalid because every one of the sub-field of individual parts are missing AnyRequired().deserialize({"type": "test"}) # following is invalid because fields of 'RequiredFields' are only partially fulfilled AnyRequired().deserialize({"field_str": "str"}) # following is valid because although fields of 'RequiredFields' are not all fulfilled, 'RequiredType' is valid AnyRequired().deserialize({"field_str": "str", "type": "str"}) # result: {"type": "test"} # following is invalid because 'RequiredFields' field 'field_int' is incorrect schema type AnyRequired().deserialize({"field_str": "str", "field_int": "str"}) # following is valid, but result omits 'type' because its schema-type is incorrect, while others are valid AnyRequired().deserialize({"field_str": "str", "field_int": 1, "items": "fields", "type": 1}) # result: {"field_str": "str", "field_int": 1, "items": "fields"}
Warning
Because valid items are applied on top of each other by merging fields during combinations, conflicting field names of any valid schema will contain only the final valid parsing during deserialization.
See also
OneOfKeywordSchema
AllOfKeywordSchema
NotKeywordSchema
- class weaver.wps_restapi.swagger_definitions.JobID(*args, **kwargs)[source]
Base schema node with support of extended functionalities.
Combines all
colander.SchemaNode
extensions so thatdefault
keyword is used first to resolve a missing field value duringdeserialize()
call, and then removes the node completely if nodefault
was provided, and evaluate variables as needed.See also
ExtendedMappingSchema
ExtendedSequenceSchema
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
- class weaver.wps_restapi.swagger_definitions.Version(*args, **kwargs)[source]
Base schema node with support of extended functionalities.
Combines all
colander.SchemaNode
extensions so thatdefault
keyword is used first to resolve a missing field value duringdeserialize()
call, and then removes the node completely if nodefault
was provided, and evaluate variables as needed.See also
ExtendedMappingSchema
ExtendedSequenceSchema
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
- class weaver.wps_restapi.swagger_definitions.ContentTypeHeader(*args, **kwargs)[source]
Base schema node with support of extended functionalities.
Combines all
colander.SchemaNode
extensions so thatdefault
keyword is used first to resolve a missing field value duringdeserialize()
call, and then removes the node completely if nodefault
was provided, and evaluate variables as needed.See also
ExtendedMappingSchema
ExtendedSequenceSchema
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
- class weaver.wps_restapi.swagger_definitions.ContentLengthHeader(*args, **kwargs)[source]
Base schema node with support of extended functionalities.
Combines all
colander.SchemaNode
extensions so thatdefault
keyword is used first to resolve a missing field value duringdeserialize()
call, and then removes the node completely if nodefault
was provided, and evaluate variables as needed.See also
ExtendedMappingSchema
ExtendedSequenceSchema
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
- class weaver.wps_restapi.swagger_definitions.ContentDispositionHeader(*args, **kwargs)[source]
Base schema node with support of extended functionalities.
Combines all
colander.SchemaNode
extensions so thatdefault
keyword is used first to resolve a missing field value duringdeserialize()
call, and then removes the node completely if nodefault
was provided, and evaluate variables as needed.See also
ExtendedMappingSchema
ExtendedSequenceSchema
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
- class weaver.wps_restapi.swagger_definitions.DateHeader(*args, **kwargs)[source]
Base schema node with support of extended functionalities.
Combines all
colander.SchemaNode
extensions so thatdefault
keyword is used first to resolve a missing field value duringdeserialize()
call, and then removes the node completely if nodefault
was provided, and evaluate variables as needed.See also
ExtendedMappingSchema
ExtendedSequenceSchema
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
- class weaver.wps_restapi.swagger_definitions.LastModifiedHeader(*args, **kwargs)[source]
Base schema node with support of extended functionalities.
Combines all
colander.SchemaNode
extensions so thatdefault
keyword is used first to resolve a missing field value duringdeserialize()
call, and then removes the node completely if nodefault
was provided, and evaluate variables as needed.See also
ExtendedMappingSchema
ExtendedSequenceSchema
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
- class weaver.wps_restapi.swagger_definitions.AcceptHeader(*args, **kwargs)[source]
Base schema node with support of extended functionalities.
Combines all
colander.SchemaNode
extensions so thatdefault
keyword is used first to resolve a missing field value duringdeserialize()
call, and then removes the node completely if nodefault
was provided, and evaluate variables as needed.See also
ExtendedMappingSchema
ExtendedSequenceSchema
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
- class weaver.wps_restapi.swagger_definitions.AcceptLanguageHeader(*args, **kwargs)[source]
Base schema node with support of extended functionalities.
Combines all
colander.SchemaNode
extensions so thatdefault
keyword is used first to resolve a missing field value duringdeserialize()
call, and then removes the node completely if nodefault
was provided, and evaluate variables as needed.See also
ExtendedMappingSchema
ExtendedSequenceSchema
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
- class weaver.wps_restapi.swagger_definitions.JsonHeader(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.HtmlHeader(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.XmlHeader(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.XAuthDockerHeader(*args, **kwargs)[source]
Base schema node with support of extended functionalities.
Combines all
colander.SchemaNode
extensions so thatdefault
keyword is used first to resolve a missing field value duringdeserialize()
call, and then removes the node completely if nodefault
was provided, and evaluate variables as needed.See also
ExtendedMappingSchema
ExtendedSequenceSchema
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
- class weaver.wps_restapi.swagger_definitions.RequestContentTypeHeader(*args, **kwargs)[source]
Base schema node with support of extended functionalities.
Combines all
colander.SchemaNode
extensions so thatdefault
keyword is used first to resolve a missing field value duringdeserialize()
call, and then removes the node completely if nodefault
was provided, and evaluate variables as needed.See also
ExtendedMappingSchema
ExtendedSequenceSchema
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
- class weaver.wps_restapi.swagger_definitions.ResponseContentTypeHeader(*args, **kwargs)[source]
Base schema node with support of extended functionalities.
Combines all
colander.SchemaNode
extensions so thatdefault
keyword is used first to resolve a missing field value duringdeserialize()
call, and then removes the node completely if nodefault
was provided, and evaluate variables as needed.See also
ExtendedMappingSchema
ExtendedSequenceSchema
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
- class weaver.wps_restapi.swagger_definitions.RequestHeaders(*args, **kwargs)[source]
Headers that can indicate how to adjust the behavior and/or result to be provided in the response.
- class weaver.wps_restapi.swagger_definitions.ResponseHeaders(*args, **kwargs)[source]
Headers describing resulting response.
- class weaver.wps_restapi.swagger_definitions.RedirectHeaders(*args, **kwargs)[source]
Headers describing resulting response.
- class weaver.wps_restapi.swagger_definitions.AcceptFormatHeaders(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.OutputFormatQuery(*args, **kwargs)[source]
Base schema node with support of extended functionalities.
Combines all
colander.SchemaNode
extensions so thatdefault
keyword is used first to resolve a missing field value duringdeserialize()
call, and then removes the node completely if nodefault
was provided, and evaluate variables as needed.See also
ExtendedMappingSchema
ExtendedSequenceSchema
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
- class weaver.wps_restapi.swagger_definitions.FormatQueryValue(*args, **kwargs)[source]
Allows specifying multiple supported mapping schemas variants for an underlying schema definition.
Corresponds to the
oneOf
specifier of OpenAPI specification.Example:
class Variant1(MappingSchema): [...fields of Variant1...] class Variant2(MappingSchema): [...fields of Variant2...] class RequiredByBoth(MappingSchema): [...fields required by both Variant1 and Variant2...] class OneOfWithRequiredFields(OneOfKeywordSchema, RequiredByBoth): _one_of = (Variant1, Variant2) [...alternatively, field required by all variants here...]
In the above example, the validation (ie:
deserialize
) process will succeed if only one of the_one_of
variants’ validator completely succeed, and will fail if every variant fails validation execution. The operation will also fail if more than one validation succeeds.Note
Class
OneOfWithRequiredFields
in the example is a shortcut variant to generate a specification that represents the pseudo-codeoneOf([<list-of-objects-with-same-base>])
.The real OpenAPI method to implement the above very commonly occurring situation is as presented by the following pseudo-code:
oneOf[allOf[RequiredByBoth, Variant1], allOf[RequiredByBoth, Variant2]]
This is both painful to read and is a lot of extra code to write when you actually expand it all into classes (each
oneOf/allOf
is another class). ClassOneOfKeywordSchema
will actually simplify this by automatically making theallOf
definitions for you if it detects other schema nodes thanoneOf
specified in the class bases. You can still do the fulloneOf/allOf
classes expansion manually though, it will result into the same specification.Warning
When
oneOf/allOf
automatic expansion occurs during schema generationWarning
When calling
deserialize()
, because the validation process requires exactly one of the variants to succeed to consider the whole object to evaluate as valid, it is important to insert more permissive validators later in the_one_of
iterator (orvalidator
keyword). For example, having a variant with all fields defined as optional (ie: withmissing=drop
) inserted as first item in_one_of
will make it always succeed regardless of following variants (since an empty schema with everything dropped is valid for optional-only elements). This would have as side effect of potentially failing the validation if other object are also valid depending on the received schema because the schema cannot be discriminated between many. If this occurs, it means the your schemas are too permissive.In the event that you have very similar schemas that can sometime match except one identifier (e.g.: field
type
defining the type of object), consider adding avalidator
to each sub-node with explicit values to solve the discrimination problem.As a shortcut, the OpenAPI keyword
discriminator
can be provided to try matching as a last resort.For example:
class Animal(ExtendedMappingSchema): name = ExtendedSchemaNode(String()) type = ExtendedSchemaNode(String()) # with explicit definition, this shouldn't be here ## With explicit definitions, each below 'Animal' class should be defined as follows ## type = ExtendedSchemaNode(String(), validator=colander.OneOf(['<animal>'])) class Cat(Animal): [...] # many **OPTIONAL** fields class Dog(Animal): [...] # many **OPTIONAL** fields # With the discriminator keyword, following is possible # (each schema must provide the same property name) class SomeAnimal(OneOfMappingSchema): discriminator = "type" _one_of = [ Cat(), Dog(), ] # If more specific mapping resolutions than 1-to-1 by name are needed, # an explicit dictionary can be specified instead. class SomeAnimal(OneOfMappingSchema): discriminator = { "propertyName": "type", # correspond to 'type' of 'Animal' "mapping": { "cat": Cat, "dog": Dog # map expected values to target schemas } } _one_of = [ Cat(), Dog(), ]
Note
Keyword
discriminator
supports a map of key-string to schemas-type as presented in the example, and the key must be located at the top level of the mapping. If onlydiscriminator = "<field>"
is provided, the definition will be created automatically using theexample
(which should be only the matching value) of the corresponding field of each node within the_one_of
mapping.When multiple valid schemas are matched against the input data, the error will be raised and returned with corresponding erroneous elements for each sub-schema (fully listed).
See also
AllOfKeywordSchema
AnyOfKeywordSchema
NotKeywordSchema
- class weaver.wps_restapi.swagger_definitions.FormatQuery(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.NoContent(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.FileUploadHeaders(*args, **kwargs)[source]
Headers that can indicate how to adjust the behavior and/or result to be provided in the response.
- class weaver.wps_restapi.swagger_definitions.FileUploadContent(*args, **kwargs)[source]
Base schema node with support of extended functionalities.
Combines all
colander.SchemaNode
extensions so thatdefault
keyword is used first to resolve a missing field value duringdeserialize()
call, and then removes the node completely if nodefault
was provided, and evaluate variables as needed.See also
ExtendedMappingSchema
ExtendedSequenceSchema
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
- class weaver.wps_restapi.swagger_definitions.FileResponseHeaders(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.AccessToken(*args, **kwargs)[source]
Base schema node with support of extended functionalities.
Combines all
colander.SchemaNode
extensions so thatdefault
keyword is used first to resolve a missing field value duringdeserialize()
call, and then removes the node completely if nodefault
was provided, and evaluate variables as needed.See also
ExtendedMappingSchema
ExtendedSequenceSchema
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
- class weaver.wps_restapi.swagger_definitions.DescriptionSchema(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.KeywordList(*args, **kwargs)[source]
Sequence schema that supports all applicable extended schema node functionalities.
Combines
DefaultSequenceSchema
andDefaultSequenceSchema
extensions so thatdefault
keyword is used first to resolve a missing sequence duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
ExtendedSchemaNode
ExtendedMappingSchema
- class weaver.wps_restapi.swagger_definitions.Language(*args, **kwargs)[source]
Base schema node with support of extended functionalities.
Combines all
colander.SchemaNode
extensions so thatdefault
keyword is used first to resolve a missing field value duringdeserialize()
call, and then removes the node completely if nodefault
was provided, and evaluate variables as needed.See also
ExtendedMappingSchema
ExtendedSequenceSchema
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
- class weaver.wps_restapi.swagger_definitions.ValueLanguage(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.LinkLanguage(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.LinkHeader(*args, **kwargs)[source]
Base schema node with support of extended functionalities.
Combines all
colander.SchemaNode
extensions so thatdefault
keyword is used first to resolve a missing field value duringdeserialize()
call, and then removes the node completely if nodefault
was provided, and evaluate variables as needed.See also
ExtendedMappingSchema
ExtendedSequenceSchema
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
- class weaver.wps_restapi.swagger_definitions.MetadataBase(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.MetadataRole(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.LinkRelationshipType(*args, **kwargs)[source]
Allows specifying multiple supported mapping schemas variants for an underlying schema definition.
Corresponds to the
oneOf
specifier of OpenAPI specification.Example:
class Variant1(MappingSchema): [...fields of Variant1...] class Variant2(MappingSchema): [...fields of Variant2...] class RequiredByBoth(MappingSchema): [...fields required by both Variant1 and Variant2...] class OneOfWithRequiredFields(OneOfKeywordSchema, RequiredByBoth): _one_of = (Variant1, Variant2) [...alternatively, field required by all variants here...]
In the above example, the validation (ie:
deserialize
) process will succeed if only one of the_one_of
variants’ validator completely succeed, and will fail if every variant fails validation execution. The operation will also fail if more than one validation succeeds.Note
Class
OneOfWithRequiredFields
in the example is a shortcut variant to generate a specification that represents the pseudo-codeoneOf([<list-of-objects-with-same-base>])
.The real OpenAPI method to implement the above very commonly occurring situation is as presented by the following pseudo-code:
oneOf[allOf[RequiredByBoth, Variant1], allOf[RequiredByBoth, Variant2]]
This is both painful to read and is a lot of extra code to write when you actually expand it all into classes (each
oneOf/allOf
is another class). ClassOneOfKeywordSchema
will actually simplify this by automatically making theallOf
definitions for you if it detects other schema nodes thanoneOf
specified in the class bases. You can still do the fulloneOf/allOf
classes expansion manually though, it will result into the same specification.Warning
When
oneOf/allOf
automatic expansion occurs during schema generationWarning
When calling
deserialize()
, because the validation process requires exactly one of the variants to succeed to consider the whole object to evaluate as valid, it is important to insert more permissive validators later in the_one_of
iterator (orvalidator
keyword). For example, having a variant with all fields defined as optional (ie: withmissing=drop
) inserted as first item in_one_of
will make it always succeed regardless of following variants (since an empty schema with everything dropped is valid for optional-only elements). This would have as side effect of potentially failing the validation if other object are also valid depending on the received schema because the schema cannot be discriminated between many. If this occurs, it means the your schemas are too permissive.In the event that you have very similar schemas that can sometime match except one identifier (e.g.: field
type
defining the type of object), consider adding avalidator
to each sub-node with explicit values to solve the discrimination problem.As a shortcut, the OpenAPI keyword
discriminator
can be provided to try matching as a last resort.For example:
class Animal(ExtendedMappingSchema): name = ExtendedSchemaNode(String()) type = ExtendedSchemaNode(String()) # with explicit definition, this shouldn't be here ## With explicit definitions, each below 'Animal' class should be defined as follows ## type = ExtendedSchemaNode(String(), validator=colander.OneOf(['<animal>'])) class Cat(Animal): [...] # many **OPTIONAL** fields class Dog(Animal): [...] # many **OPTIONAL** fields # With the discriminator keyword, following is possible # (each schema must provide the same property name) class SomeAnimal(OneOfMappingSchema): discriminator = "type" _one_of = [ Cat(), Dog(), ] # If more specific mapping resolutions than 1-to-1 by name are needed, # an explicit dictionary can be specified instead. class SomeAnimal(OneOfMappingSchema): discriminator = { "propertyName": "type", # correspond to 'type' of 'Animal' "mapping": { "cat": Cat, "dog": Dog # map expected values to target schemas } } _one_of = [ Cat(), Dog(), ]
Note
Keyword
discriminator
supports a map of key-string to schemas-type as presented in the example, and the key must be located at the top level of the mapping. If onlydiscriminator = "<field>"
is provided, the definition will be created automatically using theexample
(which should be only the matching value) of the corresponding field of each node within the_one_of
mapping.When multiple valid schemas are matched against the input data, the error will be raised and returned with corresponding erroneous elements for each sub-schema (fully listed).
See also
AllOfKeywordSchema
AnyOfKeywordSchema
NotKeywordSchema
- class weaver.wps_restapi.swagger_definitions.LinkRelationship(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.LinkBase(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.Link(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.MetadataValue(*args, **kwargs)[source]
Allows specifying specific schema conditions that fails underlying schema definition validation if present.
Corresponds to the
not
specifier of OpenAPI specification.Example:
class RequiredItem(ExtendedMappingSchema): item = ExtendedSchemaNode(String()) class MappingWithType(ExtendedMappingSchema): type = ExtendedSchemaNode(String()) class MappingWithoutType(NotKeywordSchema, RequiredItem): _not = [MappingWithType()] class MappingOnlyNotType(NotKeywordSchema): _not = [MappingWithType()] # following will raise invalid error even if 'item' is valid because 'type' is also present MappingWithoutType().deserialize({"type": "invalid", "item": "valid"}) # following will return successfully with only 'item' because 'type' was not present MappingWithoutType().deserialize({"item": "valid", "value": "ignore"}) # result: {"item": "valid"} # following will return an empty mapping dropping 'item' since it only needs to ensure 'type' was not present, # but did not provide any additional fields requirement from other class inheritances MappingOnlyNotType().deserialize({"item": "valid"}) # result: {}
See also
OneOfKeywordSchema
AllOfKeywordSchema
AnyOfKeywordSchema
- class weaver.wps_restapi.swagger_definitions.MetadataLink(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.MetadataContent(*args, **kwargs)[source]
Allows specifying multiple supported mapping schemas variants for an underlying schema definition.
Corresponds to the
oneOf
specifier of OpenAPI specification.Example:
class Variant1(MappingSchema): [...fields of Variant1...] class Variant2(MappingSchema): [...fields of Variant2...] class RequiredByBoth(MappingSchema): [...fields required by both Variant1 and Variant2...] class OneOfWithRequiredFields(OneOfKeywordSchema, RequiredByBoth): _one_of = (Variant1, Variant2) [...alternatively, field required by all variants here...]
In the above example, the validation (ie:
deserialize
) process will succeed if only one of the_one_of
variants’ validator completely succeed, and will fail if every variant fails validation execution. The operation will also fail if more than one validation succeeds.Note
Class
OneOfWithRequiredFields
in the example is a shortcut variant to generate a specification that represents the pseudo-codeoneOf([<list-of-objects-with-same-base>])
.The real OpenAPI method to implement the above very commonly occurring situation is as presented by the following pseudo-code:
oneOf[allOf[RequiredByBoth, Variant1], allOf[RequiredByBoth, Variant2]]
This is both painful to read and is a lot of extra code to write when you actually expand it all into classes (each
oneOf/allOf
is another class). ClassOneOfKeywordSchema
will actually simplify this by automatically making theallOf
definitions for you if it detects other schema nodes thanoneOf
specified in the class bases. You can still do the fulloneOf/allOf
classes expansion manually though, it will result into the same specification.Warning
When
oneOf/allOf
automatic expansion occurs during schema generationWarning
When calling
deserialize()
, because the validation process requires exactly one of the variants to succeed to consider the whole object to evaluate as valid, it is important to insert more permissive validators later in the_one_of
iterator (orvalidator
keyword). For example, having a variant with all fields defined as optional (ie: withmissing=drop
) inserted as first item in_one_of
will make it always succeed regardless of following variants (since an empty schema with everything dropped is valid for optional-only elements). This would have as side effect of potentially failing the validation if other object are also valid depending on the received schema because the schema cannot be discriminated between many. If this occurs, it means the your schemas are too permissive.In the event that you have very similar schemas that can sometime match except one identifier (e.g.: field
type
defining the type of object), consider adding avalidator
to each sub-node with explicit values to solve the discrimination problem.As a shortcut, the OpenAPI keyword
discriminator
can be provided to try matching as a last resort.For example:
class Animal(ExtendedMappingSchema): name = ExtendedSchemaNode(String()) type = ExtendedSchemaNode(String()) # with explicit definition, this shouldn't be here ## With explicit definitions, each below 'Animal' class should be defined as follows ## type = ExtendedSchemaNode(String(), validator=colander.OneOf(['<animal>'])) class Cat(Animal): [...] # many **OPTIONAL** fields class Dog(Animal): [...] # many **OPTIONAL** fields # With the discriminator keyword, following is possible # (each schema must provide the same property name) class SomeAnimal(OneOfMappingSchema): discriminator = "type" _one_of = [ Cat(), Dog(), ] # If more specific mapping resolutions than 1-to-1 by name are needed, # an explicit dictionary can be specified instead. class SomeAnimal(OneOfMappingSchema): discriminator = { "propertyName": "type", # correspond to 'type' of 'Animal' "mapping": { "cat": Cat, "dog": Dog # map expected values to target schemas } } _one_of = [ Cat(), Dog(), ]
Note
Keyword
discriminator
supports a map of key-string to schemas-type as presented in the example, and the key must be located at the top level of the mapping. If onlydiscriminator = "<field>"
is provided, the definition will be created automatically using theexample
(which should be only the matching value) of the corresponding field of each node within the_one_of
mapping.When multiple valid schemas are matched against the input data, the error will be raised and returned with corresponding erroneous elements for each sub-schema (fully listed).
See also
AllOfKeywordSchema
AnyOfKeywordSchema
NotKeywordSchema
- class weaver.wps_restapi.swagger_definitions.Metadata(*args, **kwargs)[source]
Allows specifying multiple supported mapping schemas variants for an underlying schema definition.
Corresponds to the
oneOf
specifier of OpenAPI specification.Example:
class Variant1(MappingSchema): [...fields of Variant1...] class Variant2(MappingSchema): [...fields of Variant2...] class RequiredByBoth(MappingSchema): [...fields required by both Variant1 and Variant2...] class OneOfWithRequiredFields(OneOfKeywordSchema, RequiredByBoth): _one_of = (Variant1, Variant2) [...alternatively, field required by all variants here...]
In the above example, the validation (ie:
deserialize
) process will succeed if only one of the_one_of
variants’ validator completely succeed, and will fail if every variant fails validation execution. The operation will also fail if more than one validation succeeds.Note
Class
OneOfWithRequiredFields
in the example is a shortcut variant to generate a specification that represents the pseudo-codeoneOf([<list-of-objects-with-same-base>])
.The real OpenAPI method to implement the above very commonly occurring situation is as presented by the following pseudo-code:
oneOf[allOf[RequiredByBoth, Variant1], allOf[RequiredByBoth, Variant2]]
This is both painful to read and is a lot of extra code to write when you actually expand it all into classes (each
oneOf/allOf
is another class). ClassOneOfKeywordSchema
will actually simplify this by automatically making theallOf
definitions for you if it detects other schema nodes thanoneOf
specified in the class bases. You can still do the fulloneOf/allOf
classes expansion manually though, it will result into the same specification.Warning
When
oneOf/allOf
automatic expansion occurs during schema generationWarning
When calling
deserialize()
, because the validation process requires exactly one of the variants to succeed to consider the whole object to evaluate as valid, it is important to insert more permissive validators later in the_one_of
iterator (orvalidator
keyword). For example, having a variant with all fields defined as optional (ie: withmissing=drop
) inserted as first item in_one_of
will make it always succeed regardless of following variants (since an empty schema with everything dropped is valid for optional-only elements). This would have as side effect of potentially failing the validation if other object are also valid depending on the received schema because the schema cannot be discriminated between many. If this occurs, it means the your schemas are too permissive.In the event that you have very similar schemas that can sometime match except one identifier (e.g.: field
type
defining the type of object), consider adding avalidator
to each sub-node with explicit values to solve the discrimination problem.As a shortcut, the OpenAPI keyword
discriminator
can be provided to try matching as a last resort.For example:
class Animal(ExtendedMappingSchema): name = ExtendedSchemaNode(String()) type = ExtendedSchemaNode(String()) # with explicit definition, this shouldn't be here ## With explicit definitions, each below 'Animal' class should be defined as follows ## type = ExtendedSchemaNode(String(), validator=colander.OneOf(['<animal>'])) class Cat(Animal): [...] # many **OPTIONAL** fields class Dog(Animal): [...] # many **OPTIONAL** fields # With the discriminator keyword, following is possible # (each schema must provide the same property name) class SomeAnimal(OneOfMappingSchema): discriminator = "type" _one_of = [ Cat(), Dog(), ] # If more specific mapping resolutions than 1-to-1 by name are needed, # an explicit dictionary can be specified instead. class SomeAnimal(OneOfMappingSchema): discriminator = { "propertyName": "type", # correspond to 'type' of 'Animal' "mapping": { "cat": Cat, "dog": Dog # map expected values to target schemas } } _one_of = [ Cat(), Dog(), ]
Note
Keyword
discriminator
supports a map of key-string to schemas-type as presented in the example, and the key must be located at the top level of the mapping. If onlydiscriminator = "<field>"
is provided, the definition will be created automatically using theexample
(which should be only the matching value) of the corresponding field of each node within the_one_of
mapping.When multiple valid schemas are matched against the input data, the error will be raised and returned with corresponding erroneous elements for each sub-schema (fully listed).
See also
AllOfKeywordSchema
AnyOfKeywordSchema
NotKeywordSchema
- class weaver.wps_restapi.swagger_definitions.MetadataList(*args, **kwargs)[source]
Sequence schema that supports all applicable extended schema node functionalities.
Combines
DefaultSequenceSchema
andDefaultSequenceSchema
extensions so thatdefault
keyword is used first to resolve a missing sequence duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
ExtendedSchemaNode
ExtendedMappingSchema
- class weaver.wps_restapi.swagger_definitions.LinkList(*args, **kwargs)[source]
Sequence schema that supports all applicable extended schema node functionalities.
Combines
DefaultSequenceSchema
andDefaultSequenceSchema
extensions so thatdefault
keyword is used first to resolve a missing sequence duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
ExtendedSchemaNode
ExtendedMappingSchema
- class weaver.wps_restapi.swagger_definitions.LandingPage(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.FormatSchema(*args, **kwargs)[source]
Allows specifying multiple supported mapping schemas variants for an underlying schema definition.
Corresponds to the
oneOf
specifier of OpenAPI specification.Example:
class Variant1(MappingSchema): [...fields of Variant1...] class Variant2(MappingSchema): [...fields of Variant2...] class RequiredByBoth(MappingSchema): [...fields required by both Variant1 and Variant2...] class OneOfWithRequiredFields(OneOfKeywordSchema, RequiredByBoth): _one_of = (Variant1, Variant2) [...alternatively, field required by all variants here...]
In the above example, the validation (ie:
deserialize
) process will succeed if only one of the_one_of
variants’ validator completely succeed, and will fail if every variant fails validation execution. The operation will also fail if more than one validation succeeds.Note
Class
OneOfWithRequiredFields
in the example is a shortcut variant to generate a specification that represents the pseudo-codeoneOf([<list-of-objects-with-same-base>])
.The real OpenAPI method to implement the above very commonly occurring situation is as presented by the following pseudo-code:
oneOf[allOf[RequiredByBoth, Variant1], allOf[RequiredByBoth, Variant2]]
This is both painful to read and is a lot of extra code to write when you actually expand it all into classes (each
oneOf/allOf
is another class). ClassOneOfKeywordSchema
will actually simplify this by automatically making theallOf
definitions for you if it detects other schema nodes thanoneOf
specified in the class bases. You can still do the fulloneOf/allOf
classes expansion manually though, it will result into the same specification.Warning
When
oneOf/allOf
automatic expansion occurs during schema generationWarning
When calling
deserialize()
, because the validation process requires exactly one of the variants to succeed to consider the whole object to evaluate as valid, it is important to insert more permissive validators later in the_one_of
iterator (orvalidator
keyword). For example, having a variant with all fields defined as optional (ie: withmissing=drop
) inserted as first item in_one_of
will make it always succeed regardless of following variants (since an empty schema with everything dropped is valid for optional-only elements). This would have as side effect of potentially failing the validation if other object are also valid depending on the received schema because the schema cannot be discriminated between many. If this occurs, it means the your schemas are too permissive.In the event that you have very similar schemas that can sometime match except one identifier (e.g.: field
type
defining the type of object), consider adding avalidator
to each sub-node with explicit values to solve the discrimination problem.As a shortcut, the OpenAPI keyword
discriminator
can be provided to try matching as a last resort.For example:
class Animal(ExtendedMappingSchema): name = ExtendedSchemaNode(String()) type = ExtendedSchemaNode(String()) # with explicit definition, this shouldn't be here ## With explicit definitions, each below 'Animal' class should be defined as follows ## type = ExtendedSchemaNode(String(), validator=colander.OneOf(['<animal>'])) class Cat(Animal): [...] # many **OPTIONAL** fields class Dog(Animal): [...] # many **OPTIONAL** fields # With the discriminator keyword, following is possible # (each schema must provide the same property name) class SomeAnimal(OneOfMappingSchema): discriminator = "type" _one_of = [ Cat(), Dog(), ] # If more specific mapping resolutions than 1-to-1 by name are needed, # an explicit dictionary can be specified instead. class SomeAnimal(OneOfMappingSchema): discriminator = { "propertyName": "type", # correspond to 'type' of 'Animal' "mapping": { "cat": Cat, "dog": Dog # map expected values to target schemas } } _one_of = [ Cat(), Dog(), ]
Note
Keyword
discriminator
supports a map of key-string to schemas-type as presented in the example, and the key must be located at the top level of the mapping. If onlydiscriminator = "<field>"
is provided, the definition will be created automatically using theexample
(which should be only the matching value) of the corresponding field of each node within the_one_of
mapping.When multiple valid schemas are matched against the input data, the error will be raised and returned with corresponding erroneous elements for each sub-schema (fully listed).
See also
AllOfKeywordSchema
AnyOfKeywordSchema
NotKeywordSchema
- deserialize(cstruct)[source]
Deserialize the cstruct into an appstruct based on the schema, run this appstruct through the preparer, if one is present, then validate the prepared appstruct. The
cstruct
value is deserialized into anappstruct
unconditionally.If
appstruct
returned by type deserialization and preparation is the valuecolander.null
, do something special before attempting validation:If the
missing
attribute of this node has been set explicitly, return its value. No validation of this value is performed; it is simply returned.If the
missing
attribute of this node has not been set explicitly, raise acolander.Invalid
exception error.
If the appstruct is not
colander.null
and cannot be validated , acolander.Invalid
exception will be raised.If a
cstruct
argument is not explicitly provided, it defaults tocolander.null
.
- class weaver.wps_restapi.swagger_definitions.FormatMimeType(*args, **kwargs)[source]
Used to respect
mimeType
field to work with pre-existing processes.
- class weaver.wps_restapi.swagger_definitions.Format(*args, **kwargs)[source]
Used to respect
mediaType
field as suggested per OGC-API.
- class weaver.wps_restapi.swagger_definitions.FormatDefaultMimeType(*args, **kwargs)[source]
Used to respect
mimeType
field to work with pre-existing processes.
- class weaver.wps_restapi.swagger_definitions.FormatDefaultMediaType(*args, **kwargs)[source]
Used to respect
mediaType
field as suggested per OGC-API.
- class weaver.wps_restapi.swagger_definitions.FormatSelection(*args, **kwargs)[source]
Validation against
mimeType
ormediaType
format.Note
Format are validated to be retro-compatible with pre-existing/deployed/remote processes.
- class weaver.wps_restapi.swagger_definitions.FormatDescription(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.FormatDefault(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.DescriptionFormat(*args, **kwargs)[source]
Used to respect
mediaType
field as suggested per OGC-API.
- class weaver.wps_restapi.swagger_definitions.DeploymentFormat(*args, **kwargs)[source]
Validation against
mimeType
ormediaType
format.Note
Format are validated to be retro-compatible with pre-existing/deployed/remote processes.
- class weaver.wps_restapi.swagger_definitions.ResultFormat(*args, **kwargs)[source]
Format employed for reference results respecting ‘OGC API - Processes’ schemas.
- class weaver.wps_restapi.swagger_definitions.DescriptionFormatList(*args, **kwargs)[source]
Sequence schema that supports all applicable extended schema node functionalities.
Combines
DefaultSequenceSchema
andDefaultSequenceSchema
extensions so thatdefault
keyword is used first to resolve a missing sequence duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
ExtendedSchemaNode
ExtendedMappingSchema
- class weaver.wps_restapi.swagger_definitions.DeploymentFormatList(*args, **kwargs)[source]
Sequence schema that supports all applicable extended schema node functionalities.
Combines
DefaultSequenceSchema
andDefaultSequenceSchema
extensions so thatdefault
keyword is used first to resolve a missing sequence duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
ExtendedSchemaNode
ExtendedMappingSchema
- class weaver.wps_restapi.swagger_definitions.AdditionalParameterUnique(*args, **kwargs)[source]
Allows specifying multiple supported mapping schemas variants for an underlying schema definition.
Corresponds to the
oneOf
specifier of OpenAPI specification.Example:
class Variant1(MappingSchema): [...fields of Variant1...] class Variant2(MappingSchema): [...fields of Variant2...] class RequiredByBoth(MappingSchema): [...fields required by both Variant1 and Variant2...] class OneOfWithRequiredFields(OneOfKeywordSchema, RequiredByBoth): _one_of = (Variant1, Variant2) [...alternatively, field required by all variants here...]
In the above example, the validation (ie:
deserialize
) process will succeed if only one of the_one_of
variants’ validator completely succeed, and will fail if every variant fails validation execution. The operation will also fail if more than one validation succeeds.Note
Class
OneOfWithRequiredFields
in the example is a shortcut variant to generate a specification that represents the pseudo-codeoneOf([<list-of-objects-with-same-base>])
.The real OpenAPI method to implement the above very commonly occurring situation is as presented by the following pseudo-code:
oneOf[allOf[RequiredByBoth, Variant1], allOf[RequiredByBoth, Variant2]]
This is both painful to read and is a lot of extra code to write when you actually expand it all into classes (each
oneOf/allOf
is another class). ClassOneOfKeywordSchema
will actually simplify this by automatically making theallOf
definitions for you if it detects other schema nodes thanoneOf
specified in the class bases. You can still do the fulloneOf/allOf
classes expansion manually though, it will result into the same specification.Warning
When
oneOf/allOf
automatic expansion occurs during schema generationWarning
When calling
deserialize()
, because the validation process requires exactly one of the variants to succeed to consider the whole object to evaluate as valid, it is important to insert more permissive validators later in the_one_of
iterator (orvalidator
keyword). For example, having a variant with all fields defined as optional (ie: withmissing=drop
) inserted as first item in_one_of
will make it always succeed regardless of following variants (since an empty schema with everything dropped is valid for optional-only elements). This would have as side effect of potentially failing the validation if other object are also valid depending on the received schema because the schema cannot be discriminated between many. If this occurs, it means the your schemas are too permissive.In the event that you have very similar schemas that can sometime match except one identifier (e.g.: field
type
defining the type of object), consider adding avalidator
to each sub-node with explicit values to solve the discrimination problem.As a shortcut, the OpenAPI keyword
discriminator
can be provided to try matching as a last resort.For example:
class Animal(ExtendedMappingSchema): name = ExtendedSchemaNode(String()) type = ExtendedSchemaNode(String()) # with explicit definition, this shouldn't be here ## With explicit definitions, each below 'Animal' class should be defined as follows ## type = ExtendedSchemaNode(String(), validator=colander.OneOf(['<animal>'])) class Cat(Animal): [...] # many **OPTIONAL** fields class Dog(Animal): [...] # many **OPTIONAL** fields # With the discriminator keyword, following is possible # (each schema must provide the same property name) class SomeAnimal(OneOfMappingSchema): discriminator = "type" _one_of = [ Cat(), Dog(), ] # If more specific mapping resolutions than 1-to-1 by name are needed, # an explicit dictionary can be specified instead. class SomeAnimal(OneOfMappingSchema): discriminator = { "propertyName": "type", # correspond to 'type' of 'Animal' "mapping": { "cat": Cat, "dog": Dog # map expected values to target schemas } } _one_of = [ Cat(), Dog(), ]
Note
Keyword
discriminator
supports a map of key-string to schemas-type as presented in the example, and the key must be located at the top level of the mapping. If onlydiscriminator = "<field>"
is provided, the definition will be created automatically using theexample
(which should be only the matching value) of the corresponding field of each node within the_one_of
mapping.When multiple valid schemas are matched against the input data, the error will be raised and returned with corresponding erroneous elements for each sub-schema (fully listed).
See also
AllOfKeywordSchema
AnyOfKeywordSchema
NotKeywordSchema
- class weaver.wps_restapi.swagger_definitions.AdditionalParameterListing(*args, **kwargs)[source]
Sequence schema that supports all applicable extended schema node functionalities.
Combines
DefaultSequenceSchema
andDefaultSequenceSchema
extensions so thatdefault
keyword is used first to resolve a missing sequence duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
ExtendedSchemaNode
ExtendedMappingSchema
- class weaver.wps_restapi.swagger_definitions.AdditionalParameterValues(*args, **kwargs)[source]
Allows specifying multiple supported mapping schemas variants for an underlying schema definition.
Corresponds to the
oneOf
specifier of OpenAPI specification.Example:
class Variant1(MappingSchema): [...fields of Variant1...] class Variant2(MappingSchema): [...fields of Variant2...] class RequiredByBoth(MappingSchema): [...fields required by both Variant1 and Variant2...] class OneOfWithRequiredFields(OneOfKeywordSchema, RequiredByBoth): _one_of = (Variant1, Variant2) [...alternatively, field required by all variants here...]
In the above example, the validation (ie:
deserialize
) process will succeed if only one of the_one_of
variants’ validator completely succeed, and will fail if every variant fails validation execution. The operation will also fail if more than one validation succeeds.Note
Class
OneOfWithRequiredFields
in the example is a shortcut variant to generate a specification that represents the pseudo-codeoneOf([<list-of-objects-with-same-base>])
.The real OpenAPI method to implement the above very commonly occurring situation is as presented by the following pseudo-code:
oneOf[allOf[RequiredByBoth, Variant1], allOf[RequiredByBoth, Variant2]]
This is both painful to read and is a lot of extra code to write when you actually expand it all into classes (each
oneOf/allOf
is another class). ClassOneOfKeywordSchema
will actually simplify this by automatically making theallOf
definitions for you if it detects other schema nodes thanoneOf
specified in the class bases. You can still do the fulloneOf/allOf
classes expansion manually though, it will result into the same specification.Warning
When
oneOf/allOf
automatic expansion occurs during schema generationWarning
When calling
deserialize()
, because the validation process requires exactly one of the variants to succeed to consider the whole object to evaluate as valid, it is important to insert more permissive validators later in the_one_of
iterator (orvalidator
keyword). For example, having a variant with all fields defined as optional (ie: withmissing=drop
) inserted as first item in_one_of
will make it always succeed regardless of following variants (since an empty schema with everything dropped is valid for optional-only elements). This would have as side effect of potentially failing the validation if other object are also valid depending on the received schema because the schema cannot be discriminated between many. If this occurs, it means the your schemas are too permissive.In the event that you have very similar schemas that can sometime match except one identifier (e.g.: field
type
defining the type of object), consider adding avalidator
to each sub-node with explicit values to solve the discrimination problem.As a shortcut, the OpenAPI keyword
discriminator
can be provided to try matching as a last resort.For example:
class Animal(ExtendedMappingSchema): name = ExtendedSchemaNode(String()) type = ExtendedSchemaNode(String()) # with explicit definition, this shouldn't be here ## With explicit definitions, each below 'Animal' class should be defined as follows ## type = ExtendedSchemaNode(String(), validator=colander.OneOf(['<animal>'])) class Cat(Animal): [...] # many **OPTIONAL** fields class Dog(Animal): [...] # many **OPTIONAL** fields # With the discriminator keyword, following is possible # (each schema must provide the same property name) class SomeAnimal(OneOfMappingSchema): discriminator = "type" _one_of = [ Cat(), Dog(), ] # If more specific mapping resolutions than 1-to-1 by name are needed, # an explicit dictionary can be specified instead. class SomeAnimal(OneOfMappingSchema): discriminator = { "propertyName": "type", # correspond to 'type' of 'Animal' "mapping": { "cat": Cat, "dog": Dog # map expected values to target schemas } } _one_of = [ Cat(), Dog(), ]
Note
Keyword
discriminator
supports a map of key-string to schemas-type as presented in the example, and the key must be located at the top level of the mapping. If onlydiscriminator = "<field>"
is provided, the definition will be created automatically using theexample
(which should be only the matching value) of the corresponding field of each node within the_one_of
mapping.When multiple valid schemas are matched against the input data, the error will be raised and returned with corresponding erroneous elements for each sub-schema (fully listed).
See also
AllOfKeywordSchema
AnyOfKeywordSchema
NotKeywordSchema
- class weaver.wps_restapi.swagger_definitions.AdditionalParameterDefinition(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.AdditionalParameterList(*args, **kwargs)[source]
Sequence schema that supports all applicable extended schema node functionalities.
Combines
DefaultSequenceSchema
andDefaultSequenceSchema
extensions so thatdefault
keyword is used first to resolve a missing sequence duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
ExtendedSchemaNode
ExtendedMappingSchema
- class weaver.wps_restapi.swagger_definitions.AdditionalParametersMeta(*args, **kwargs)[source]
Allows specifying multiple supported mapping schemas variants for an underlying schema definition.
Corresponds to the
oneOf
specifier of OpenAPI specification.Example:
class Variant1(MappingSchema): [...fields of Variant1...] class Variant2(MappingSchema): [...fields of Variant2...] class RequiredByBoth(MappingSchema): [...fields required by both Variant1 and Variant2...] class OneOfWithRequiredFields(OneOfKeywordSchema, RequiredByBoth): _one_of = (Variant1, Variant2) [...alternatively, field required by all variants here...]
In the above example, the validation (ie:
deserialize
) process will succeed if only one of the_one_of
variants’ validator completely succeed, and will fail if every variant fails validation execution. The operation will also fail if more than one validation succeeds.Note
Class
OneOfWithRequiredFields
in the example is a shortcut variant to generate a specification that represents the pseudo-codeoneOf([<list-of-objects-with-same-base>])
.The real OpenAPI method to implement the above very commonly occurring situation is as presented by the following pseudo-code:
oneOf[allOf[RequiredByBoth, Variant1], allOf[RequiredByBoth, Variant2]]
This is both painful to read and is a lot of extra code to write when you actually expand it all into classes (each
oneOf/allOf
is another class). ClassOneOfKeywordSchema
will actually simplify this by automatically making theallOf
definitions for you if it detects other schema nodes thanoneOf
specified in the class bases. You can still do the fulloneOf/allOf
classes expansion manually though, it will result into the same specification.Warning
When
oneOf/allOf
automatic expansion occurs during schema generationWarning
When calling
deserialize()
, because the validation process requires exactly one of the variants to succeed to consider the whole object to evaluate as valid, it is important to insert more permissive validators later in the_one_of
iterator (orvalidator
keyword). For example, having a variant with all fields defined as optional (ie: withmissing=drop
) inserted as first item in_one_of
will make it always succeed regardless of following variants (since an empty schema with everything dropped is valid for optional-only elements). This would have as side effect of potentially failing the validation if other object are also valid depending on the received schema because the schema cannot be discriminated between many. If this occurs, it means the your schemas are too permissive.In the event that you have very similar schemas that can sometime match except one identifier (e.g.: field
type
defining the type of object), consider adding avalidator
to each sub-node with explicit values to solve the discrimination problem.As a shortcut, the OpenAPI keyword
discriminator
can be provided to try matching as a last resort.For example:
class Animal(ExtendedMappingSchema): name = ExtendedSchemaNode(String()) type = ExtendedSchemaNode(String()) # with explicit definition, this shouldn't be here ## With explicit definitions, each below 'Animal' class should be defined as follows ## type = ExtendedSchemaNode(String(), validator=colander.OneOf(['<animal>'])) class Cat(Animal): [...] # many **OPTIONAL** fields class Dog(Animal): [...] # many **OPTIONAL** fields # With the discriminator keyword, following is possible # (each schema must provide the same property name) class SomeAnimal(OneOfMappingSchema): discriminator = "type" _one_of = [ Cat(), Dog(), ] # If more specific mapping resolutions than 1-to-1 by name are needed, # an explicit dictionary can be specified instead. class SomeAnimal(OneOfMappingSchema): discriminator = { "propertyName": "type", # correspond to 'type' of 'Animal' "mapping": { "cat": Cat, "dog": Dog # map expected values to target schemas } } _one_of = [ Cat(), Dog(), ]
Note
Keyword
discriminator
supports a map of key-string to schemas-type as presented in the example, and the key must be located at the top level of the mapping. If onlydiscriminator = "<field>"
is provided, the definition will be created automatically using theexample
(which should be only the matching value) of the corresponding field of each node within the_one_of
mapping.When multiple valid schemas are matched against the input data, the error will be raised and returned with corresponding erroneous elements for each sub-schema (fully listed).
See also
AllOfKeywordSchema
AnyOfKeywordSchema
NotKeywordSchema
- class weaver.wps_restapi.swagger_definitions.AdditionalParameters(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.AdditionalParametersItem(*args, **kwargs)[source]
Allows specifying all mapping schemas that can be matched for an underlying schema definition.
Corresponds to the
anyOf
specifier of OpenAPI specification.Contrary to
OneOfKeywordSchema
that MUST be validated with exactly one schema, this definition will continue parsing all possibilities and apply validated sub-schemas on top of each other. Not all schemas have to be valid like in the case ofAllOfKeywordSchema
to succeed, as long as at least one of them is valid.Example:
class RequiredItem(ExtendedMappingSchema): item = ExtendedSchemaNode(String()) class RequiredType(ExtendedMappingSchema): type = ExtendedSchemaNode(String()) class RequiredFields(ExtendedMappingSchema): field_str = ExtendedSchemaNode(String()) field_int = ExtendedSchemaNode(Integer()) class AnyRequired(AnyKeywordSchema): _any_of = [RequiredItem(), RequiredType(), RequiredFields()] # following is valid because their individual parts have all required sub-fields, result is their composition AnyRequired().deserialize({"type": "test", "item": "valid"}) # result: {"type": "test", "item": "valid"} # following is also valid because even though 'item' is missing, the 'type' is present AnyRequired().deserialize({"type": "test"}) # result: {"type": "test"} # following is invalid because every one of the sub-field of individual parts are missing AnyRequired().deserialize({"type": "test"}) # following is invalid because fields of 'RequiredFields' are only partially fulfilled AnyRequired().deserialize({"field_str": "str"}) # following is valid because although fields of 'RequiredFields' are not all fulfilled, 'RequiredType' is valid AnyRequired().deserialize({"field_str": "str", "type": "str"}) # result: {"type": "test"} # following is invalid because 'RequiredFields' field 'field_int' is incorrect schema type AnyRequired().deserialize({"field_str": "str", "field_int": "str"}) # following is valid, but result omits 'type' because its schema-type is incorrect, while others are valid AnyRequired().deserialize({"field_str": "str", "field_int": 1, "items": "fields", "type": 1}) # result: {"field_str": "str", "field_int": 1, "items": "fields"}
Warning
Because valid items are applied on top of each other by merging fields during combinations, conflicting field names of any valid schema will contain only the final valid parsing during deserialization.
See also
OneOfKeywordSchema
AllOfKeywordSchema
NotKeywordSchema
- class weaver.wps_restapi.swagger_definitions.AdditionalParametersList(*args, **kwargs)[source]
Sequence schema that supports all applicable extended schema node functionalities.
Combines
DefaultSequenceSchema
andDefaultSequenceSchema
extensions so thatdefault
keyword is used first to resolve a missing sequence duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
ExtendedSchemaNode
ExtendedMappingSchema
- class weaver.wps_restapi.swagger_definitions.Content(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.Offering(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.OWSContext(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.DescriptionBase(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.DescriptionLinks(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.ProcessContext(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.DescriptionExtra(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.DescriptionType(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.DeploymentType(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.DescriptionMeta(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.ProcessDeployMeta(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.InputOutputDescriptionMeta(*args: Any, **kwargs: Any)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.ReferenceOAS(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.TypeOAS(*args, **kwargs)[source]
Base schema node with support of extended functionalities.
Combines all
colander.SchemaNode
extensions so thatdefault
keyword is used first to resolve a missing field value duringdeserialize()
call, and then removes the node completely if nodefault
was provided, and evaluate variables as needed.See also
ExtendedMappingSchema
ExtendedSequenceSchema
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
- class weaver.wps_restapi.swagger_definitions.EnumItemOAS(*args, **kwargs)[source]
Allows specifying multiple supported mapping schemas variants for an underlying schema definition.
Corresponds to the
oneOf
specifier of OpenAPI specification.Example:
class Variant1(MappingSchema): [...fields of Variant1...] class Variant2(MappingSchema): [...fields of Variant2...] class RequiredByBoth(MappingSchema): [...fields required by both Variant1 and Variant2...] class OneOfWithRequiredFields(OneOfKeywordSchema, RequiredByBoth): _one_of = (Variant1, Variant2) [...alternatively, field required by all variants here...]
In the above example, the validation (ie:
deserialize
) process will succeed if only one of the_one_of
variants’ validator completely succeed, and will fail if every variant fails validation execution. The operation will also fail if more than one validation succeeds.Note
Class
OneOfWithRequiredFields
in the example is a shortcut variant to generate a specification that represents the pseudo-codeoneOf([<list-of-objects-with-same-base>])
.The real OpenAPI method to implement the above very commonly occurring situation is as presented by the following pseudo-code:
oneOf[allOf[RequiredByBoth, Variant1], allOf[RequiredByBoth, Variant2]]
This is both painful to read and is a lot of extra code to write when you actually expand it all into classes (each
oneOf/allOf
is another class). ClassOneOfKeywordSchema
will actually simplify this by automatically making theallOf
definitions for you if it detects other schema nodes thanoneOf
specified in the class bases. You can still do the fulloneOf/allOf
classes expansion manually though, it will result into the same specification.Warning
When
oneOf/allOf
automatic expansion occurs during schema generationWarning
When calling
deserialize()
, because the validation process requires exactly one of the variants to succeed to consider the whole object to evaluate as valid, it is important to insert more permissive validators later in the_one_of
iterator (orvalidator
keyword). For example, having a variant with all fields defined as optional (ie: withmissing=drop
) inserted as first item in_one_of
will make it always succeed regardless of following variants (since an empty schema with everything dropped is valid for optional-only elements). This would have as side effect of potentially failing the validation if other object are also valid depending on the received schema because the schema cannot be discriminated between many. If this occurs, it means the your schemas are too permissive.In the event that you have very similar schemas that can sometime match except one identifier (e.g.: field
type
defining the type of object), consider adding avalidator
to each sub-node with explicit values to solve the discrimination problem.As a shortcut, the OpenAPI keyword
discriminator
can be provided to try matching as a last resort.For example:
class Animal(ExtendedMappingSchema): name = ExtendedSchemaNode(String()) type = ExtendedSchemaNode(String()) # with explicit definition, this shouldn't be here ## With explicit definitions, each below 'Animal' class should be defined as follows ## type = ExtendedSchemaNode(String(), validator=colander.OneOf(['<animal>'])) class Cat(Animal): [...] # many **OPTIONAL** fields class Dog(Animal): [...] # many **OPTIONAL** fields # With the discriminator keyword, following is possible # (each schema must provide the same property name) class SomeAnimal(OneOfMappingSchema): discriminator = "type" _one_of = [ Cat(), Dog(), ] # If more specific mapping resolutions than 1-to-1 by name are needed, # an explicit dictionary can be specified instead. class SomeAnimal(OneOfMappingSchema): discriminator = { "propertyName": "type", # correspond to 'type' of 'Animal' "mapping": { "cat": Cat, "dog": Dog # map expected values to target schemas } } _one_of = [ Cat(), Dog(), ]
Note
Keyword
discriminator
supports a map of key-string to schemas-type as presented in the example, and the key must be located at the top level of the mapping. If onlydiscriminator = "<field>"
is provided, the definition will be created automatically using theexample
(which should be only the matching value) of the corresponding field of each node within the_one_of
mapping.When multiple valid schemas are matched against the input data, the error will be raised and returned with corresponding erroneous elements for each sub-schema (fully listed).
See also
AllOfKeywordSchema
AnyOfKeywordSchema
NotKeywordSchema
- class weaver.wps_restapi.swagger_definitions.EnumOAS(*args, **kwargs)[source]
Sequence schema that supports all applicable extended schema node functionalities.
Combines
DefaultSequenceSchema
andDefaultSequenceSchema
extensions so thatdefault
keyword is used first to resolve a missing sequence duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
ExtendedSchemaNode
ExtendedMappingSchema
- class weaver.wps_restapi.swagger_definitions.RequiredOAS(*args, **kwargs)[source]
Sequence schema that supports all applicable extended schema node functionalities.
Combines
DefaultSequenceSchema
andDefaultSequenceSchema
extensions so thatdefault
keyword is used first to resolve a missing sequence duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
ExtendedSchemaNode
ExtendedMappingSchema
- class weaver.wps_restapi.swagger_definitions.MultipleOfOAS(*args, **kwargs)[source]
Allows specifying multiple supported mapping schemas variants for an underlying schema definition.
Corresponds to the
oneOf
specifier of OpenAPI specification.Example:
class Variant1(MappingSchema): [...fields of Variant1...] class Variant2(MappingSchema): [...fields of Variant2...] class RequiredByBoth(MappingSchema): [...fields required by both Variant1 and Variant2...] class OneOfWithRequiredFields(OneOfKeywordSchema, RequiredByBoth): _one_of = (Variant1, Variant2) [...alternatively, field required by all variants here...]
In the above example, the validation (ie:
deserialize
) process will succeed if only one of the_one_of
variants’ validator completely succeed, and will fail if every variant fails validation execution. The operation will also fail if more than one validation succeeds.Note
Class
OneOfWithRequiredFields
in the example is a shortcut variant to generate a specification that represents the pseudo-codeoneOf([<list-of-objects-with-same-base>])
.The real OpenAPI method to implement the above very commonly occurring situation is as presented by the following pseudo-code:
oneOf[allOf[RequiredByBoth, Variant1], allOf[RequiredByBoth, Variant2]]
This is both painful to read and is a lot of extra code to write when you actually expand it all into classes (each
oneOf/allOf
is another class). ClassOneOfKeywordSchema
will actually simplify this by automatically making theallOf
definitions for you if it detects other schema nodes thanoneOf
specified in the class bases. You can still do the fulloneOf/allOf
classes expansion manually though, it will result into the same specification.Warning
When
oneOf/allOf
automatic expansion occurs during schema generationWarning
When calling
deserialize()
, because the validation process requires exactly one of the variants to succeed to consider the whole object to evaluate as valid, it is important to insert more permissive validators later in the_one_of
iterator (orvalidator
keyword). For example, having a variant with all fields defined as optional (ie: withmissing=drop
) inserted as first item in_one_of
will make it always succeed regardless of following variants (since an empty schema with everything dropped is valid for optional-only elements). This would have as side effect of potentially failing the validation if other object are also valid depending on the received schema because the schema cannot be discriminated between many. If this occurs, it means the your schemas are too permissive.In the event that you have very similar schemas that can sometime match except one identifier (e.g.: field
type
defining the type of object), consider adding avalidator
to each sub-node with explicit values to solve the discrimination problem.As a shortcut, the OpenAPI keyword
discriminator
can be provided to try matching as a last resort.For example:
class Animal(ExtendedMappingSchema): name = ExtendedSchemaNode(String()) type = ExtendedSchemaNode(String()) # with explicit definition, this shouldn't be here ## With explicit definitions, each below 'Animal' class should be defined as follows ## type = ExtendedSchemaNode(String(), validator=colander.OneOf(['<animal>'])) class Cat(Animal): [...] # many **OPTIONAL** fields class Dog(Animal): [...] # many **OPTIONAL** fields # With the discriminator keyword, following is possible # (each schema must provide the same property name) class SomeAnimal(OneOfMappingSchema): discriminator = "type" _one_of = [ Cat(), Dog(), ] # If more specific mapping resolutions than 1-to-1 by name are needed, # an explicit dictionary can be specified instead. class SomeAnimal(OneOfMappingSchema): discriminator = { "propertyName": "type", # correspond to 'type' of 'Animal' "mapping": { "cat": Cat, "dog": Dog # map expected values to target schemas } } _one_of = [ Cat(), Dog(), ]
Note
Keyword
discriminator
supports a map of key-string to schemas-type as presented in the example, and the key must be located at the top level of the mapping. If onlydiscriminator = "<field>"
is provided, the definition will be created automatically using theexample
(which should be only the matching value) of the corresponding field of each node within the_one_of
mapping.When multiple valid schemas are matched against the input data, the error will be raised and returned with corresponding erroneous elements for each sub-schema (fully listed).
See also
AllOfKeywordSchema
AnyOfKeywordSchema
NotKeywordSchema
- class weaver.wps_restapi.swagger_definitions.PermissiveDefinitionOAS(*args, **kwargs)[source]
Allows specifying specific schema conditions that fails underlying schema definition validation if present.
Corresponds to the
not
specifier of OpenAPI specification.Example:
class RequiredItem(ExtendedMappingSchema): item = ExtendedSchemaNode(String()) class MappingWithType(ExtendedMappingSchema): type = ExtendedSchemaNode(String()) class MappingWithoutType(NotKeywordSchema, RequiredItem): _not = [MappingWithType()] class MappingOnlyNotType(NotKeywordSchema): _not = [MappingWithType()] # following will raise invalid error even if 'item' is valid because 'type' is also present MappingWithoutType().deserialize({"type": "invalid", "item": "valid"}) # following will return successfully with only 'item' because 'type' was not present MappingWithoutType().deserialize({"item": "valid", "value": "ignore"}) # result: {"item": "valid"} # following will return an empty mapping dropping 'item' since it only needs to ensure 'type' was not present, # but did not provide any additional fields requirement from other class inheritances MappingOnlyNotType().deserialize({"item": "valid"}) # result: {}
See also
OneOfKeywordSchema
AllOfKeywordSchema
AnyOfKeywordSchema
- class weaver.wps_restapi.swagger_definitions.PseudoObjectOAS(*args, **kwargs)[source]
Allows specifying multiple supported mapping schemas variants for an underlying schema definition.
Corresponds to the
oneOf
specifier of OpenAPI specification.Example:
class Variant1(MappingSchema): [...fields of Variant1...] class Variant2(MappingSchema): [...fields of Variant2...] class RequiredByBoth(MappingSchema): [...fields required by both Variant1 and Variant2...] class OneOfWithRequiredFields(OneOfKeywordSchema, RequiredByBoth): _one_of = (Variant1, Variant2) [...alternatively, field required by all variants here...]
In the above example, the validation (ie:
deserialize
) process will succeed if only one of the_one_of
variants’ validator completely succeed, and will fail if every variant fails validation execution. The operation will also fail if more than one validation succeeds.Note
Class
OneOfWithRequiredFields
in the example is a shortcut variant to generate a specification that represents the pseudo-codeoneOf([<list-of-objects-with-same-base>])
.The real OpenAPI method to implement the above very commonly occurring situation is as presented by the following pseudo-code:
oneOf[allOf[RequiredByBoth, Variant1], allOf[RequiredByBoth, Variant2]]
This is both painful to read and is a lot of extra code to write when you actually expand it all into classes (each
oneOf/allOf
is another class). ClassOneOfKeywordSchema
will actually simplify this by automatically making theallOf
definitions for you if it detects other schema nodes thanoneOf
specified in the class bases. You can still do the fulloneOf/allOf
classes expansion manually though, it will result into the same specification.Warning
When
oneOf/allOf
automatic expansion occurs during schema generationWarning
When calling
deserialize()
, because the validation process requires exactly one of the variants to succeed to consider the whole object to evaluate as valid, it is important to insert more permissive validators later in the_one_of
iterator (orvalidator
keyword). For example, having a variant with all fields defined as optional (ie: withmissing=drop
) inserted as first item in_one_of
will make it always succeed regardless of following variants (since an empty schema with everything dropped is valid for optional-only elements). This would have as side effect of potentially failing the validation if other object are also valid depending on the received schema because the schema cannot be discriminated between many. If this occurs, it means the your schemas are too permissive.In the event that you have very similar schemas that can sometime match except one identifier (e.g.: field
type
defining the type of object), consider adding avalidator
to each sub-node with explicit values to solve the discrimination problem.As a shortcut, the OpenAPI keyword
discriminator
can be provided to try matching as a last resort.For example:
class Animal(ExtendedMappingSchema): name = ExtendedSchemaNode(String()) type = ExtendedSchemaNode(String()) # with explicit definition, this shouldn't be here ## With explicit definitions, each below 'Animal' class should be defined as follows ## type = ExtendedSchemaNode(String(), validator=colander.OneOf(['<animal>'])) class Cat(Animal): [...] # many **OPTIONAL** fields class Dog(Animal): [...] # many **OPTIONAL** fields # With the discriminator keyword, following is possible # (each schema must provide the same property name) class SomeAnimal(OneOfMappingSchema): discriminator = "type" _one_of = [ Cat(), Dog(), ] # If more specific mapping resolutions than 1-to-1 by name are needed, # an explicit dictionary can be specified instead. class SomeAnimal(OneOfMappingSchema): discriminator = { "propertyName": "type", # correspond to 'type' of 'Animal' "mapping": { "cat": Cat, "dog": Dog # map expected values to target schemas } } _one_of = [ Cat(), Dog(), ]
Note
Keyword
discriminator
supports a map of key-string to schemas-type as presented in the example, and the key must be located at the top level of the mapping. If onlydiscriminator = "<field>"
is provided, the definition will be created automatically using theexample
(which should be only the matching value) of the corresponding field of each node within the_one_of
mapping.When multiple valid schemas are matched against the input data, the error will be raised and returned with corresponding erroneous elements for each sub-schema (fully listed).
See also
AllOfKeywordSchema
AnyOfKeywordSchema
NotKeywordSchema
- class weaver.wps_restapi.swagger_definitions.KeywordObjectOAS(*args, **kwargs)[source]
Sequence schema that supports all applicable extended schema node functionalities.
Combines
DefaultSequenceSchema
andDefaultSequenceSchema
extensions so thatdefault
keyword is used first to resolve a missing sequence duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
ExtendedSchemaNode
ExtendedMappingSchema
- class weaver.wps_restapi.swagger_definitions.AdditionalPropertiesOAS(*args, **kwargs)[source]
Allows specifying multiple supported mapping schemas variants for an underlying schema definition.
Corresponds to the
oneOf
specifier of OpenAPI specification.Example:
class Variant1(MappingSchema): [...fields of Variant1...] class Variant2(MappingSchema): [...fields of Variant2...] class RequiredByBoth(MappingSchema): [...fields required by both Variant1 and Variant2...] class OneOfWithRequiredFields(OneOfKeywordSchema, RequiredByBoth): _one_of = (Variant1, Variant2) [...alternatively, field required by all variants here...]
In the above example, the validation (ie:
deserialize
) process will succeed if only one of the_one_of
variants’ validator completely succeed, and will fail if every variant fails validation execution. The operation will also fail if more than one validation succeeds.Note
Class
OneOfWithRequiredFields
in the example is a shortcut variant to generate a specification that represents the pseudo-codeoneOf([<list-of-objects-with-same-base>])
.The real OpenAPI method to implement the above very commonly occurring situation is as presented by the following pseudo-code:
oneOf[allOf[RequiredByBoth, Variant1], allOf[RequiredByBoth, Variant2]]
This is both painful to read and is a lot of extra code to write when you actually expand it all into classes (each
oneOf/allOf
is another class). ClassOneOfKeywordSchema
will actually simplify this by automatically making theallOf
definitions for you if it detects other schema nodes thanoneOf
specified in the class bases. You can still do the fulloneOf/allOf
classes expansion manually though, it will result into the same specification.Warning
When
oneOf/allOf
automatic expansion occurs during schema generationWarning
When calling
deserialize()
, because the validation process requires exactly one of the variants to succeed to consider the whole object to evaluate as valid, it is important to insert more permissive validators later in the_one_of
iterator (orvalidator
keyword). For example, having a variant with all fields defined as optional (ie: withmissing=drop
) inserted as first item in_one_of
will make it always succeed regardless of following variants (since an empty schema with everything dropped is valid for optional-only elements). This would have as side effect of potentially failing the validation if other object are also valid depending on the received schema because the schema cannot be discriminated between many. If this occurs, it means the your schemas are too permissive.In the event that you have very similar schemas that can sometime match except one identifier (e.g.: field
type
defining the type of object), consider adding avalidator
to each sub-node with explicit values to solve the discrimination problem.As a shortcut, the OpenAPI keyword
discriminator
can be provided to try matching as a last resort.For example:
class Animal(ExtendedMappingSchema): name = ExtendedSchemaNode(String()) type = ExtendedSchemaNode(String()) # with explicit definition, this shouldn't be here ## With explicit definitions, each below 'Animal' class should be defined as follows ## type = ExtendedSchemaNode(String(), validator=colander.OneOf(['<animal>'])) class Cat(Animal): [...] # many **OPTIONAL** fields class Dog(Animal): [...] # many **OPTIONAL** fields # With the discriminator keyword, following is possible # (each schema must provide the same property name) class SomeAnimal(OneOfMappingSchema): discriminator = "type" _one_of = [ Cat(), Dog(), ] # If more specific mapping resolutions than 1-to-1 by name are needed, # an explicit dictionary can be specified instead. class SomeAnimal(OneOfMappingSchema): discriminator = { "propertyName": "type", # correspond to 'type' of 'Animal' "mapping": { "cat": Cat, "dog": Dog # map expected values to target schemas } } _one_of = [ Cat(), Dog(), ]
Note
Keyword
discriminator
supports a map of key-string to schemas-type as presented in the example, and the key must be located at the top level of the mapping. If onlydiscriminator = "<field>"
is provided, the definition will be created automatically using theexample
(which should be only the matching value) of the corresponding field of each node within the_one_of
mapping.When multiple valid schemas are matched against the input data, the error will be raised and returned with corresponding erroneous elements for each sub-schema (fully listed).
See also
AllOfKeywordSchema
AnyOfKeywordSchema
NotKeywordSchema
- class weaver.wps_restapi.swagger_definitions.AnyValueOAS(*args, **kwargs)[source]
Allows specifying all mapping schemas that can be matched for an underlying schema definition.
Corresponds to the
anyOf
specifier of OpenAPI specification.Contrary to
OneOfKeywordSchema
that MUST be validated with exactly one schema, this definition will continue parsing all possibilities and apply validated sub-schemas on top of each other. Not all schemas have to be valid like in the case ofAllOfKeywordSchema
to succeed, as long as at least one of them is valid.Example:
class RequiredItem(ExtendedMappingSchema): item = ExtendedSchemaNode(String()) class RequiredType(ExtendedMappingSchema): type = ExtendedSchemaNode(String()) class RequiredFields(ExtendedMappingSchema): field_str = ExtendedSchemaNode(String()) field_int = ExtendedSchemaNode(Integer()) class AnyRequired(AnyKeywordSchema): _any_of = [RequiredItem(), RequiredType(), RequiredFields()] # following is valid because their individual parts have all required sub-fields, result is their composition AnyRequired().deserialize({"type": "test", "item": "valid"}) # result: {"type": "test", "item": "valid"} # following is also valid because even though 'item' is missing, the 'type' is present AnyRequired().deserialize({"type": "test"}) # result: {"type": "test"} # following is invalid because every one of the sub-field of individual parts are missing AnyRequired().deserialize({"type": "test"}) # following is invalid because fields of 'RequiredFields' are only partially fulfilled AnyRequired().deserialize({"field_str": "str"}) # following is valid because although fields of 'RequiredFields' are not all fulfilled, 'RequiredType' is valid AnyRequired().deserialize({"field_str": "str", "type": "str"}) # result: {"type": "test"} # following is invalid because 'RequiredFields' field 'field_int' is incorrect schema type AnyRequired().deserialize({"field_str": "str", "field_int": "str"}) # following is valid, but result omits 'type' because its schema-type is incorrect, while others are valid AnyRequired().deserialize({"field_str": "str", "field_int": 1, "items": "fields", "type": 1}) # result: {"field_str": "str", "field_int": 1, "items": "fields"}
Warning
Because valid items are applied on top of each other by merging fields during combinations, conflicting field names of any valid schema will contain only the final valid parsing during deserialization.
See also
OneOfKeywordSchema
AllOfKeywordSchema
NotKeywordSchema
- class weaver.wps_restapi.swagger_definitions.PropertyOAS(*args: Any, **kwargs: Any)[source]
Object schema that will
preserve
any unknown field to remain present in the resulting deserialization.This type is useful for defining a dictionary where some field names are not known in advance, or when more optional keys that don’t need to all be exhaustively provided in the schema are acceptable.
- ..note::
When doing schema deserialization to validate it, unknown keys would normally be removed without this class (default behaviour is to
ignore
them). With this schema, content under an unknown key usingpreserve
are passed down without any validation. Other fields that are explicitly specified with sub-schema nodes will still be validated as per usual behaviour.
See also
StrictMappingSchema
Example:
class AnyKeyObject(PermissiveMappingSchema): known_key = SchemaNode(String()) AnyKeyObject().deserialize({"unknown": "kept", "known_key": "requirement"})) # result: dictionary returned as is instead of removing 'unknown' entry # 'known_key' is still validated with its string schema
Note
This class is only a shorthand definition of
unknown
keyword for convenience. Allcolander.MappingSchema
support this natively.
- class weaver.wps_restapi.swagger_definitions.AnyPropertyOAS(*args, **kwargs)[source]
Allows specifying multiple supported mapping schemas variants for an underlying schema definition.
Corresponds to the
oneOf
specifier of OpenAPI specification.Example:
class Variant1(MappingSchema): [...fields of Variant1...] class Variant2(MappingSchema): [...fields of Variant2...] class RequiredByBoth(MappingSchema): [...fields required by both Variant1 and Variant2...] class OneOfWithRequiredFields(OneOfKeywordSchema, RequiredByBoth): _one_of = (Variant1, Variant2) [...alternatively, field required by all variants here...]
In the above example, the validation (ie:
deserialize
) process will succeed if only one of the_one_of
variants’ validator completely succeed, and will fail if every variant fails validation execution. The operation will also fail if more than one validation succeeds.Note
Class
OneOfWithRequiredFields
in the example is a shortcut variant to generate a specification that represents the pseudo-codeoneOf([<list-of-objects-with-same-base>])
.The real OpenAPI method to implement the above very commonly occurring situation is as presented by the following pseudo-code:
oneOf[allOf[RequiredByBoth, Variant1], allOf[RequiredByBoth, Variant2]]
This is both painful to read and is a lot of extra code to write when you actually expand it all into classes (each
oneOf/allOf
is another class). ClassOneOfKeywordSchema
will actually simplify this by automatically making theallOf
definitions for you if it detects other schema nodes thanoneOf
specified in the class bases. You can still do the fulloneOf/allOf
classes expansion manually though, it will result into the same specification.Warning
When
oneOf/allOf
automatic expansion occurs during schema generationWarning
When calling
deserialize()
, because the validation process requires exactly one of the variants to succeed to consider the whole object to evaluate as valid, it is important to insert more permissive validators later in the_one_of
iterator (orvalidator
keyword). For example, having a variant with all fields defined as optional (ie: withmissing=drop
) inserted as first item in_one_of
will make it always succeed regardless of following variants (since an empty schema with everything dropped is valid for optional-only elements). This would have as side effect of potentially failing the validation if other object are also valid depending on the received schema because the schema cannot be discriminated between many. If this occurs, it means the your schemas are too permissive.In the event that you have very similar schemas that can sometime match except one identifier (e.g.: field
type
defining the type of object), consider adding avalidator
to each sub-node with explicit values to solve the discrimination problem.As a shortcut, the OpenAPI keyword
discriminator
can be provided to try matching as a last resort.For example:
class Animal(ExtendedMappingSchema): name = ExtendedSchemaNode(String()) type = ExtendedSchemaNode(String()) # with explicit definition, this shouldn't be here ## With explicit definitions, each below 'Animal' class should be defined as follows ## type = ExtendedSchemaNode(String(), validator=colander.OneOf(['<animal>'])) class Cat(Animal): [...] # many **OPTIONAL** fields class Dog(Animal): [...] # many **OPTIONAL** fields # With the discriminator keyword, following is possible # (each schema must provide the same property name) class SomeAnimal(OneOfMappingSchema): discriminator = "type" _one_of = [ Cat(), Dog(), ] # If more specific mapping resolutions than 1-to-1 by name are needed, # an explicit dictionary can be specified instead. class SomeAnimal(OneOfMappingSchema): discriminator = { "propertyName": "type", # correspond to 'type' of 'Animal' "mapping": { "cat": Cat, "dog": Dog # map expected values to target schemas } } _one_of = [ Cat(), Dog(), ]
Note
Keyword
discriminator
supports a map of key-string to schemas-type as presented in the example, and the key must be located at the top level of the mapping. If onlydiscriminator = "<field>"
is provided, the definition will be created automatically using theexample
(which should be only the matching value) of the corresponding field of each node within the_one_of
mapping.When multiple valid schemas are matched against the input data, the error will be raised and returned with corresponding erroneous elements for each sub-schema (fully listed).
See also
AllOfKeywordSchema
AnyOfKeywordSchema
NotKeywordSchema
- class weaver.wps_restapi.swagger_definitions.ObjectPropertiesOAS(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.ObjectOAS(*args, **kwargs)[source]
Allows specifying specific schema conditions that fails underlying schema definition validation if present.
Corresponds to the
not
specifier of OpenAPI specification.Example:
class RequiredItem(ExtendedMappingSchema): item = ExtendedSchemaNode(String()) class MappingWithType(ExtendedMappingSchema): type = ExtendedSchemaNode(String()) class MappingWithoutType(NotKeywordSchema, RequiredItem): _not = [MappingWithType()] class MappingOnlyNotType(NotKeywordSchema): _not = [MappingWithType()] # following will raise invalid error even if 'item' is valid because 'type' is also present MappingWithoutType().deserialize({"type": "invalid", "item": "valid"}) # following will return successfully with only 'item' because 'type' was not present MappingWithoutType().deserialize({"item": "valid", "value": "ignore"}) # result: {"item": "valid"} # following will return an empty mapping dropping 'item' since it only needs to ensure 'type' was not present, # but did not provide any additional fields requirement from other class inheritances MappingOnlyNotType().deserialize({"item": "valid"}) # result: {}
See also
OneOfKeywordSchema
AllOfKeywordSchema
AnyOfKeywordSchema
- class weaver.wps_restapi.swagger_definitions.DefinitionOAS(*args, **kwargs)[source]
Allows specifying all mapping schemas that can be matched for an underlying schema definition.
Corresponds to the
anyOf
specifier of OpenAPI specification.Contrary to
OneOfKeywordSchema
that MUST be validated with exactly one schema, this definition will continue parsing all possibilities and apply validated sub-schemas on top of each other. Not all schemas have to be valid like in the case ofAllOfKeywordSchema
to succeed, as long as at least one of them is valid.Example:
class RequiredItem(ExtendedMappingSchema): item = ExtendedSchemaNode(String()) class RequiredType(ExtendedMappingSchema): type = ExtendedSchemaNode(String()) class RequiredFields(ExtendedMappingSchema): field_str = ExtendedSchemaNode(String()) field_int = ExtendedSchemaNode(Integer()) class AnyRequired(AnyKeywordSchema): _any_of = [RequiredItem(), RequiredType(), RequiredFields()] # following is valid because their individual parts have all required sub-fields, result is their composition AnyRequired().deserialize({"type": "test", "item": "valid"}) # result: {"type": "test", "item": "valid"} # following is also valid because even though 'item' is missing, the 'type' is present AnyRequired().deserialize({"type": "test"}) # result: {"type": "test"} # following is invalid because every one of the sub-field of individual parts are missing AnyRequired().deserialize({"type": "test"}) # following is invalid because fields of 'RequiredFields' are only partially fulfilled AnyRequired().deserialize({"field_str": "str"}) # following is valid because although fields of 'RequiredFields' are not all fulfilled, 'RequiredType' is valid AnyRequired().deserialize({"field_str": "str", "type": "str"}) # result: {"type": "test"} # following is invalid because 'RequiredFields' field 'field_int' is incorrect schema type AnyRequired().deserialize({"field_str": "str", "field_int": "str"}) # following is valid, but result omits 'type' because its schema-type is incorrect, while others are valid AnyRequired().deserialize({"field_str": "str", "field_int": 1, "items": "fields", "type": 1}) # result: {"field_str": "str", "field_int": 1, "items": "fields"}
Warning
Because valid items are applied on top of each other by merging fields during combinations, conflicting field names of any valid schema will contain only the final valid parsing during deserialization.
See also
OneOfKeywordSchema
AllOfKeywordSchema
NotKeywordSchema
- class weaver.wps_restapi.swagger_definitions.OAS(*args, **kwargs)[source]
Allows specifying multiple supported mapping schemas variants for an underlying schema definition.
Corresponds to the
oneOf
specifier of OpenAPI specification.Example:
class Variant1(MappingSchema): [...fields of Variant1...] class Variant2(MappingSchema): [...fields of Variant2...] class RequiredByBoth(MappingSchema): [...fields required by both Variant1 and Variant2...] class OneOfWithRequiredFields(OneOfKeywordSchema, RequiredByBoth): _one_of = (Variant1, Variant2) [...alternatively, field required by all variants here...]
In the above example, the validation (ie:
deserialize
) process will succeed if only one of the_one_of
variants’ validator completely succeed, and will fail if every variant fails validation execution. The operation will also fail if more than one validation succeeds.Note
Class
OneOfWithRequiredFields
in the example is a shortcut variant to generate a specification that represents the pseudo-codeoneOf([<list-of-objects-with-same-base>])
.The real OpenAPI method to implement the above very commonly occurring situation is as presented by the following pseudo-code:
oneOf[allOf[RequiredByBoth, Variant1], allOf[RequiredByBoth, Variant2]]
This is both painful to read and is a lot of extra code to write when you actually expand it all into classes (each
oneOf/allOf
is another class). ClassOneOfKeywordSchema
will actually simplify this by automatically making theallOf
definitions for you if it detects other schema nodes thanoneOf
specified in the class bases. You can still do the fulloneOf/allOf
classes expansion manually though, it will result into the same specification.Warning
When
oneOf/allOf
automatic expansion occurs during schema generationWarning
When calling
deserialize()
, because the validation process requires exactly one of the variants to succeed to consider the whole object to evaluate as valid, it is important to insert more permissive validators later in the_one_of
iterator (orvalidator
keyword). For example, having a variant with all fields defined as optional (ie: withmissing=drop
) inserted as first item in_one_of
will make it always succeed regardless of following variants (since an empty schema with everything dropped is valid for optional-only elements). This would have as side effect of potentially failing the validation if other object are also valid depending on the received schema because the schema cannot be discriminated between many. If this occurs, it means the your schemas are too permissive.In the event that you have very similar schemas that can sometime match except one identifier (e.g.: field
type
defining the type of object), consider adding avalidator
to each sub-node with explicit values to solve the discrimination problem.As a shortcut, the OpenAPI keyword
discriminator
can be provided to try matching as a last resort.For example:
class Animal(ExtendedMappingSchema): name = ExtendedSchemaNode(String()) type = ExtendedSchemaNode(String()) # with explicit definition, this shouldn't be here ## With explicit definitions, each below 'Animal' class should be defined as follows ## type = ExtendedSchemaNode(String(), validator=colander.OneOf(['<animal>'])) class Cat(Animal): [...] # many **OPTIONAL** fields class Dog(Animal): [...] # many **OPTIONAL** fields # With the discriminator keyword, following is possible # (each schema must provide the same property name) class SomeAnimal(OneOfMappingSchema): discriminator = "type" _one_of = [ Cat(), Dog(), ] # If more specific mapping resolutions than 1-to-1 by name are needed, # an explicit dictionary can be specified instead. class SomeAnimal(OneOfMappingSchema): discriminator = { "propertyName": "type", # correspond to 'type' of 'Animal' "mapping": { "cat": Cat, "dog": Dog # map expected values to target schemas } } _one_of = [ Cat(), Dog(), ]
Note
Keyword
discriminator
supports a map of key-string to schemas-type as presented in the example, and the key must be located at the top level of the mapping. If onlydiscriminator = "<field>"
is provided, the definition will be created automatically using theexample
(which should be only the matching value) of the corresponding field of each node within the_one_of
mapping.When multiple valid schemas are matched against the input data, the error will be raised and returned with corresponding erroneous elements for each sub-schema (fully listed).
See also
AllOfKeywordSchema
AnyOfKeywordSchema
NotKeywordSchema
- class weaver.wps_restapi.swagger_definitions.InputOutputDescriptionSchema(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.MinOccursDefinition(*args, **kwargs)[source]
Allows specifying multiple supported mapping schemas variants for an underlying schema definition.
Corresponds to the
oneOf
specifier of OpenAPI specification.Example:
class Variant1(MappingSchema): [...fields of Variant1...] class Variant2(MappingSchema): [...fields of Variant2...] class RequiredByBoth(MappingSchema): [...fields required by both Variant1 and Variant2...] class OneOfWithRequiredFields(OneOfKeywordSchema, RequiredByBoth): _one_of = (Variant1, Variant2) [...alternatively, field required by all variants here...]
In the above example, the validation (ie:
deserialize
) process will succeed if only one of the_one_of
variants’ validator completely succeed, and will fail if every variant fails validation execution. The operation will also fail if more than one validation succeeds.Note
Class
OneOfWithRequiredFields
in the example is a shortcut variant to generate a specification that represents the pseudo-codeoneOf([<list-of-objects-with-same-base>])
.The real OpenAPI method to implement the above very commonly occurring situation is as presented by the following pseudo-code:
oneOf[allOf[RequiredByBoth, Variant1], allOf[RequiredByBoth, Variant2]]
This is both painful to read and is a lot of extra code to write when you actually expand it all into classes (each
oneOf/allOf
is another class). ClassOneOfKeywordSchema
will actually simplify this by automatically making theallOf
definitions for you if it detects other schema nodes thanoneOf
specified in the class bases. You can still do the fulloneOf/allOf
classes expansion manually though, it will result into the same specification.Warning
When
oneOf/allOf
automatic expansion occurs during schema generationWarning
When calling
deserialize()
, because the validation process requires exactly one of the variants to succeed to consider the whole object to evaluate as valid, it is important to insert more permissive validators later in the_one_of
iterator (orvalidator
keyword). For example, having a variant with all fields defined as optional (ie: withmissing=drop
) inserted as first item in_one_of
will make it always succeed regardless of following variants (since an empty schema with everything dropped is valid for optional-only elements). This would have as side effect of potentially failing the validation if other object are also valid depending on the received schema because the schema cannot be discriminated between many. If this occurs, it means the your schemas are too permissive.In the event that you have very similar schemas that can sometime match except one identifier (e.g.: field
type
defining the type of object), consider adding avalidator
to each sub-node with explicit values to solve the discrimination problem.As a shortcut, the OpenAPI keyword
discriminator
can be provided to try matching as a last resort.For example:
class Animal(ExtendedMappingSchema): name = ExtendedSchemaNode(String()) type = ExtendedSchemaNode(String()) # with explicit definition, this shouldn't be here ## With explicit definitions, each below 'Animal' class should be defined as follows ## type = ExtendedSchemaNode(String(), validator=colander.OneOf(['<animal>'])) class Cat(Animal): [...] # many **OPTIONAL** fields class Dog(Animal): [...] # many **OPTIONAL** fields # With the discriminator keyword, following is possible # (each schema must provide the same property name) class SomeAnimal(OneOfMappingSchema): discriminator = "type" _one_of = [ Cat(), Dog(), ] # If more specific mapping resolutions than 1-to-1 by name are needed, # an explicit dictionary can be specified instead. class SomeAnimal(OneOfMappingSchema): discriminator = { "propertyName": "type", # correspond to 'type' of 'Animal' "mapping": { "cat": Cat, "dog": Dog # map expected values to target schemas } } _one_of = [ Cat(), Dog(), ]
Note
Keyword
discriminator
supports a map of key-string to schemas-type as presented in the example, and the key must be located at the top level of the mapping. If onlydiscriminator = "<field>"
is provided, the definition will be created automatically using theexample
(which should be only the matching value) of the corresponding field of each node within the_one_of
mapping.When multiple valid schemas are matched against the input data, the error will be raised and returned with corresponding erroneous elements for each sub-schema (fully listed).
See also
AllOfKeywordSchema
AnyOfKeywordSchema
NotKeywordSchema
- class weaver.wps_restapi.swagger_definitions.MaxOccursDefinition(*args, **kwargs)[source]
Allows specifying multiple supported mapping schemas variants for an underlying schema definition.
Corresponds to the
oneOf
specifier of OpenAPI specification.Example:
class Variant1(MappingSchema): [...fields of Variant1...] class Variant2(MappingSchema): [...fields of Variant2...] class RequiredByBoth(MappingSchema): [...fields required by both Variant1 and Variant2...] class OneOfWithRequiredFields(OneOfKeywordSchema, RequiredByBoth): _one_of = (Variant1, Variant2) [...alternatively, field required by all variants here...]
In the above example, the validation (ie:
deserialize
) process will succeed if only one of the_one_of
variants’ validator completely succeed, and will fail if every variant fails validation execution. The operation will also fail if more than one validation succeeds.Note
Class
OneOfWithRequiredFields
in the example is a shortcut variant to generate a specification that represents the pseudo-codeoneOf([<list-of-objects-with-same-base>])
.The real OpenAPI method to implement the above very commonly occurring situation is as presented by the following pseudo-code:
oneOf[allOf[RequiredByBoth, Variant1], allOf[RequiredByBoth, Variant2]]
This is both painful to read and is a lot of extra code to write when you actually expand it all into classes (each
oneOf/allOf
is another class). ClassOneOfKeywordSchema
will actually simplify this by automatically making theallOf
definitions for you if it detects other schema nodes thanoneOf
specified in the class bases. You can still do the fulloneOf/allOf
classes expansion manually though, it will result into the same specification.Warning
When
oneOf/allOf
automatic expansion occurs during schema generationWarning
When calling
deserialize()
, because the validation process requires exactly one of the variants to succeed to consider the whole object to evaluate as valid, it is important to insert more permissive validators later in the_one_of
iterator (orvalidator
keyword). For example, having a variant with all fields defined as optional (ie: withmissing=drop
) inserted as first item in_one_of
will make it always succeed regardless of following variants (since an empty schema with everything dropped is valid for optional-only elements). This would have as side effect of potentially failing the validation if other object are also valid depending on the received schema because the schema cannot be discriminated between many. If this occurs, it means the your schemas are too permissive.In the event that you have very similar schemas that can sometime match except one identifier (e.g.: field
type
defining the type of object), consider adding avalidator
to each sub-node with explicit values to solve the discrimination problem.As a shortcut, the OpenAPI keyword
discriminator
can be provided to try matching as a last resort.For example:
class Animal(ExtendedMappingSchema): name = ExtendedSchemaNode(String()) type = ExtendedSchemaNode(String()) # with explicit definition, this shouldn't be here ## With explicit definitions, each below 'Animal' class should be defined as follows ## type = ExtendedSchemaNode(String(), validator=colander.OneOf(['<animal>'])) class Cat(Animal): [...] # many **OPTIONAL** fields class Dog(Animal): [...] # many **OPTIONAL** fields # With the discriminator keyword, following is possible # (each schema must provide the same property name) class SomeAnimal(OneOfMappingSchema): discriminator = "type" _one_of = [ Cat(), Dog(), ] # If more specific mapping resolutions than 1-to-1 by name are needed, # an explicit dictionary can be specified instead. class SomeAnimal(OneOfMappingSchema): discriminator = { "propertyName": "type", # correspond to 'type' of 'Animal' "mapping": { "cat": Cat, "dog": Dog # map expected values to target schemas } } _one_of = [ Cat(), Dog(), ]
Note
Keyword
discriminator
supports a map of key-string to schemas-type as presented in the example, and the key must be located at the top level of the mapping. If onlydiscriminator = "<field>"
is provided, the definition will be created automatically using theexample
(which should be only the matching value) of the corresponding field of each node within the_one_of
mapping.When multiple valid schemas are matched against the input data, the error will be raised and returned with corresponding erroneous elements for each sub-schema (fully listed).
See also
AllOfKeywordSchema
AnyOfKeywordSchema
NotKeywordSchema
- class weaver.wps_restapi.swagger_definitions.DescribeMinMaxOccurs(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.DeployMinMaxOccurs(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.ProcessDescriptionType(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.InputIdentifierType(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.OutputIdentifierType(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.DescribeWithFormats(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.DeployWithFormats(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.DescribeComplexInputType(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.DeployComplexInputType(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.SupportedCRS(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.SupportedCRSList(*args, **kwargs)[source]
Sequence schema that supports all applicable extended schema node functionalities.
Combines
DefaultSequenceSchema
andDefaultSequenceSchema
extensions so thatdefault
keyword is used first to resolve a missing sequence duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
ExtendedSchemaNode
ExtendedMappingSchema
- class weaver.wps_restapi.swagger_definitions.BoundingBoxInputType(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.AnyLiteralType(*args, **kwargs)[source]
Submitted values that correspond to literal data.
- class weaver.wps_restapi.swagger_definitions.Number(*args, **kwargs)[source]
Represents a literal number, integer or float.
- class weaver.wps_restapi.swagger_definitions.NumericType(*args, **kwargs)[source]
Represents a numeric-like value.
- class weaver.wps_restapi.swagger_definitions.DecimalType(*args, **kwargs)[source]
Base schema node with support of extended functionalities.
Combines all
colander.SchemaNode
extensions so thatdefault
keyword is used first to resolve a missing field value duringdeserialize()
call, and then removes the node completely if nodefault
was provided, and evaluate variables as needed.See also
ExtendedMappingSchema
ExtendedSequenceSchema
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
- class weaver.wps_restapi.swagger_definitions.PositiveNumber(*args, **kwargs)[source]
Represents a literal number, integer or float, of positive value.
- class weaver.wps_restapi.swagger_definitions.LiteralReference(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.NameReferenceType(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.DataTypeSchema(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.UomSchema(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.AllowedValuesList(*args, **kwargs)[source]
Sequence schema that supports all applicable extended schema node functionalities.
Combines
DefaultSequenceSchema
andDefaultSequenceSchema
extensions so thatdefault
keyword is used first to resolve a missing sequence duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
ExtendedSchemaNode
ExtendedMappingSchema
- class weaver.wps_restapi.swagger_definitions.AllowedRange(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.AllowedRangesList(*args, **kwargs)[source]
Sequence schema that supports all applicable extended schema node functionalities.
Combines
DefaultSequenceSchema
andDefaultSequenceSchema
extensions so thatdefault
keyword is used first to resolve a missing sequence duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
ExtendedSchemaNode
ExtendedMappingSchema
- class weaver.wps_restapi.swagger_definitions.AllowedValues(*args, **kwargs)[source]
Allows specifying multiple supported mapping schemas variants for an underlying schema definition.
Corresponds to the
oneOf
specifier of OpenAPI specification.Example:
class Variant1(MappingSchema): [...fields of Variant1...] class Variant2(MappingSchema): [...fields of Variant2...] class RequiredByBoth(MappingSchema): [...fields required by both Variant1 and Variant2...] class OneOfWithRequiredFields(OneOfKeywordSchema, RequiredByBoth): _one_of = (Variant1, Variant2) [...alternatively, field required by all variants here...]
In the above example, the validation (ie:
deserialize
) process will succeed if only one of the_one_of
variants’ validator completely succeed, and will fail if every variant fails validation execution. The operation will also fail if more than one validation succeeds.Note
Class
OneOfWithRequiredFields
in the example is a shortcut variant to generate a specification that represents the pseudo-codeoneOf([<list-of-objects-with-same-base>])
.The real OpenAPI method to implement the above very commonly occurring situation is as presented by the following pseudo-code:
oneOf[allOf[RequiredByBoth, Variant1], allOf[RequiredByBoth, Variant2]]
This is both painful to read and is a lot of extra code to write when you actually expand it all into classes (each
oneOf/allOf
is another class). ClassOneOfKeywordSchema
will actually simplify this by automatically making theallOf
definitions for you if it detects other schema nodes thanoneOf
specified in the class bases. You can still do the fulloneOf/allOf
classes expansion manually though, it will result into the same specification.Warning
When
oneOf/allOf
automatic expansion occurs during schema generationWarning
When calling
deserialize()
, because the validation process requires exactly one of the variants to succeed to consider the whole object to evaluate as valid, it is important to insert more permissive validators later in the_one_of
iterator (orvalidator
keyword). For example, having a variant with all fields defined as optional (ie: withmissing=drop
) inserted as first item in_one_of
will make it always succeed regardless of following variants (since an empty schema with everything dropped is valid for optional-only elements). This would have as side effect of potentially failing the validation if other object are also valid depending on the received schema because the schema cannot be discriminated between many. If this occurs, it means the your schemas are too permissive.In the event that you have very similar schemas that can sometime match except one identifier (e.g.: field
type
defining the type of object), consider adding avalidator
to each sub-node with explicit values to solve the discrimination problem.As a shortcut, the OpenAPI keyword
discriminator
can be provided to try matching as a last resort.For example:
class Animal(ExtendedMappingSchema): name = ExtendedSchemaNode(String()) type = ExtendedSchemaNode(String()) # with explicit definition, this shouldn't be here ## With explicit definitions, each below 'Animal' class should be defined as follows ## type = ExtendedSchemaNode(String(), validator=colander.OneOf(['<animal>'])) class Cat(Animal): [...] # many **OPTIONAL** fields class Dog(Animal): [...] # many **OPTIONAL** fields # With the discriminator keyword, following is possible # (each schema must provide the same property name) class SomeAnimal(OneOfMappingSchema): discriminator = "type" _one_of = [ Cat(), Dog(), ] # If more specific mapping resolutions than 1-to-1 by name are needed, # an explicit dictionary can be specified instead. class SomeAnimal(OneOfMappingSchema): discriminator = { "propertyName": "type", # correspond to 'type' of 'Animal' "mapping": { "cat": Cat, "dog": Dog # map expected values to target schemas } } _one_of = [ Cat(), Dog(), ]
Note
Keyword
discriminator
supports a map of key-string to schemas-type as presented in the example, and the key must be located at the top level of the mapping. If onlydiscriminator = "<field>"
is provided, the definition will be created automatically using theexample
(which should be only the matching value) of the corresponding field of each node within the_one_of
mapping.When multiple valid schemas are matched against the input data, the error will be raised and returned with corresponding erroneous elements for each sub-schema (fully listed).
See also
AllOfKeywordSchema
AnyOfKeywordSchema
NotKeywordSchema
- class weaver.wps_restapi.swagger_definitions.AnyValue(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.ValuesReference(*args, **kwargs)[source]
Allows specifying all mapping schemas that can be matched for an underlying schema definition.
Corresponds to the
anyOf
specifier of OpenAPI specification.Contrary to
OneOfKeywordSchema
that MUST be validated with exactly one schema, this definition will continue parsing all possibilities and apply validated sub-schemas on top of each other. Not all schemas have to be valid like in the case ofAllOfKeywordSchema
to succeed, as long as at least one of them is valid.Example:
class RequiredItem(ExtendedMappingSchema): item = ExtendedSchemaNode(String()) class RequiredType(ExtendedMappingSchema): type = ExtendedSchemaNode(String()) class RequiredFields(ExtendedMappingSchema): field_str = ExtendedSchemaNode(String()) field_int = ExtendedSchemaNode(Integer()) class AnyRequired(AnyKeywordSchema): _any_of = [RequiredItem(), RequiredType(), RequiredFields()] # following is valid because their individual parts have all required sub-fields, result is their composition AnyRequired().deserialize({"type": "test", "item": "valid"}) # result: {"type": "test", "item": "valid"} # following is also valid because even though 'item' is missing, the 'type' is present AnyRequired().deserialize({"type": "test"}) # result: {"type": "test"} # following is invalid because every one of the sub-field of individual parts are missing AnyRequired().deserialize({"type": "test"}) # following is invalid because fields of 'RequiredFields' are only partially fulfilled AnyRequired().deserialize({"field_str": "str"}) # following is valid because although fields of 'RequiredFields' are not all fulfilled, 'RequiredType' is valid AnyRequired().deserialize({"field_str": "str", "type": "str"}) # result: {"type": "test"} # following is invalid because 'RequiredFields' field 'field_int' is incorrect schema type AnyRequired().deserialize({"field_str": "str", "field_int": "str"}) # following is valid, but result omits 'type' because its schema-type is incorrect, while others are valid AnyRequired().deserialize({"field_str": "str", "field_int": 1, "items": "fields", "type": 1}) # result: {"field_str": "str", "field_int": 1, "items": "fields"}
Warning
Because valid items are applied on top of each other by merging fields during combinations, conflicting field names of any valid schema will contain only the final valid parsing during deserialization.
See also
OneOfKeywordSchema
AllOfKeywordSchema
NotKeywordSchema
- class weaver.wps_restapi.swagger_definitions.ArrayLiteralType(*args, **kwargs)[source]
Sequence schema that supports all applicable extended schema node functionalities.
Combines
DefaultSequenceSchema
andDefaultSequenceSchema
extensions so thatdefault
keyword is used first to resolve a missing sequence duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
ExtendedSchemaNode
ExtendedMappingSchema
- class weaver.wps_restapi.swagger_definitions.ArrayLiteralDataType(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.ArrayLiteralValueType(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.AnyLiteralDataType(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.AnyLiteralValueType(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.AnyLiteralDefaultType(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.LiteralDataValueDefinition(*args, **kwargs)[source]
Allows specifying multiple supported mapping schemas variants for an underlying schema definition.
Corresponds to the
oneOf
specifier of OpenAPI specification.Example:
class Variant1(MappingSchema): [...fields of Variant1...] class Variant2(MappingSchema): [...fields of Variant2...] class RequiredByBoth(MappingSchema): [...fields required by both Variant1 and Variant2...] class OneOfWithRequiredFields(OneOfKeywordSchema, RequiredByBoth): _one_of = (Variant1, Variant2) [...alternatively, field required by all variants here...]
In the above example, the validation (ie:
deserialize
) process will succeed if only one of the_one_of
variants’ validator completely succeed, and will fail if every variant fails validation execution. The operation will also fail if more than one validation succeeds.Note
Class
OneOfWithRequiredFields
in the example is a shortcut variant to generate a specification that represents the pseudo-codeoneOf([<list-of-objects-with-same-base>])
.The real OpenAPI method to implement the above very commonly occurring situation is as presented by the following pseudo-code:
oneOf[allOf[RequiredByBoth, Variant1], allOf[RequiredByBoth, Variant2]]
This is both painful to read and is a lot of extra code to write when you actually expand it all into classes (each
oneOf/allOf
is another class). ClassOneOfKeywordSchema
will actually simplify this by automatically making theallOf
definitions for you if it detects other schema nodes thanoneOf
specified in the class bases. You can still do the fulloneOf/allOf
classes expansion manually though, it will result into the same specification.Warning
When
oneOf/allOf
automatic expansion occurs during schema generationWarning
When calling
deserialize()
, because the validation process requires exactly one of the variants to succeed to consider the whole object to evaluate as valid, it is important to insert more permissive validators later in the_one_of
iterator (orvalidator
keyword). For example, having a variant with all fields defined as optional (ie: withmissing=drop
) inserted as first item in_one_of
will make it always succeed regardless of following variants (since an empty schema with everything dropped is valid for optional-only elements). This would have as side effect of potentially failing the validation if other object are also valid depending on the received schema because the schema cannot be discriminated between many. If this occurs, it means the your schemas are too permissive.In the event that you have very similar schemas that can sometime match except one identifier (e.g.: field
type
defining the type of object), consider adding avalidator
to each sub-node with explicit values to solve the discrimination problem.As a shortcut, the OpenAPI keyword
discriminator
can be provided to try matching as a last resort.For example:
class Animal(ExtendedMappingSchema): name = ExtendedSchemaNode(String()) type = ExtendedSchemaNode(String()) # with explicit definition, this shouldn't be here ## With explicit definitions, each below 'Animal' class should be defined as follows ## type = ExtendedSchemaNode(String(), validator=colander.OneOf(['<animal>'])) class Cat(Animal): [...] # many **OPTIONAL** fields class Dog(Animal): [...] # many **OPTIONAL** fields # With the discriminator keyword, following is possible # (each schema must provide the same property name) class SomeAnimal(OneOfMappingSchema): discriminator = "type" _one_of = [ Cat(), Dog(), ] # If more specific mapping resolutions than 1-to-1 by name are needed, # an explicit dictionary can be specified instead. class SomeAnimal(OneOfMappingSchema): discriminator = { "propertyName": "type", # correspond to 'type' of 'Animal' "mapping": { "cat": Cat, "dog": Dog # map expected values to target schemas } } _one_of = [ Cat(), Dog(), ]
Note
Keyword
discriminator
supports a map of key-string to schemas-type as presented in the example, and the key must be located at the top level of the mapping. If onlydiscriminator = "<field>"
is provided, the definition will be created automatically using theexample
(which should be only the matching value) of the corresponding field of each node within the_one_of
mapping.When multiple valid schemas are matched against the input data, the error will be raised and returned with corresponding erroneous elements for each sub-schema (fully listed).
See also
AllOfKeywordSchema
AnyOfKeywordSchema
NotKeywordSchema
- class weaver.wps_restapi.swagger_definitions.LiteralDataDomain(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.LiteralDataDomainList(*args, **kwargs)[source]
Constraints that apply to the literal data values.
- class weaver.wps_restapi.swagger_definitions.LiteralDataType(*args, **kwargs)[source]
Allows specifying specific schema conditions that fails underlying schema definition validation if present.
Corresponds to the
not
specifier of OpenAPI specification.Example:
class RequiredItem(ExtendedMappingSchema): item = ExtendedSchemaNode(String()) class MappingWithType(ExtendedMappingSchema): type = ExtendedSchemaNode(String()) class MappingWithoutType(NotKeywordSchema, RequiredItem): _not = [MappingWithType()] class MappingOnlyNotType(NotKeywordSchema): _not = [MappingWithType()] # following will raise invalid error even if 'item' is valid because 'type' is also present MappingWithoutType().deserialize({"type": "invalid", "item": "valid"}) # following will return successfully with only 'item' because 'type' was not present MappingWithoutType().deserialize({"item": "valid", "value": "ignore"}) # result: {"item": "valid"} # following will return an empty mapping dropping 'item' since it only needs to ensure 'type' was not present, # but did not provide any additional fields requirement from other class inheritances MappingOnlyNotType().deserialize({"item": "valid"}) # result: {}
See also
OneOfKeywordSchema
AllOfKeywordSchema
AnyOfKeywordSchema
- class weaver.wps_restapi.swagger_definitions.LiteralInputType(*args, **kwargs)[source]
Allows specifying specific schema conditions that fails underlying schema definition validation if present.
Corresponds to the
not
specifier of OpenAPI specification.Example:
class RequiredItem(ExtendedMappingSchema): item = ExtendedSchemaNode(String()) class MappingWithType(ExtendedMappingSchema): type = ExtendedSchemaNode(String()) class MappingWithoutType(NotKeywordSchema, RequiredItem): _not = [MappingWithType()] class MappingOnlyNotType(NotKeywordSchema): _not = [MappingWithType()] # following will raise invalid error even if 'item' is valid because 'type' is also present MappingWithoutType().deserialize({"type": "invalid", "item": "valid"}) # following will return successfully with only 'item' because 'type' was not present MappingWithoutType().deserialize({"item": "valid", "value": "ignore"}) # result: {"item": "valid"} # following will return an empty mapping dropping 'item' since it only needs to ensure 'type' was not present, # but did not provide any additional fields requirement from other class inheritances MappingOnlyNotType().deserialize({"item": "valid"}) # result: {}
See also
OneOfKeywordSchema
AllOfKeywordSchema
AnyOfKeywordSchema
- class weaver.wps_restapi.swagger_definitions.DescribeInputTypeDefinition(*args, **kwargs)[source]
Allows specifying multiple supported mapping schemas variants for an underlying schema definition.
Corresponds to the
oneOf
specifier of OpenAPI specification.Example:
class Variant1(MappingSchema): [...fields of Variant1...] class Variant2(MappingSchema): [...fields of Variant2...] class RequiredByBoth(MappingSchema): [...fields required by both Variant1 and Variant2...] class OneOfWithRequiredFields(OneOfKeywordSchema, RequiredByBoth): _one_of = (Variant1, Variant2) [...alternatively, field required by all variants here...]
In the above example, the validation (ie:
deserialize
) process will succeed if only one of the_one_of
variants’ validator completely succeed, and will fail if every variant fails validation execution. The operation will also fail if more than one validation succeeds.Note
Class
OneOfWithRequiredFields
in the example is a shortcut variant to generate a specification that represents the pseudo-codeoneOf([<list-of-objects-with-same-base>])
.The real OpenAPI method to implement the above very commonly occurring situation is as presented by the following pseudo-code:
oneOf[allOf[RequiredByBoth, Variant1], allOf[RequiredByBoth, Variant2]]
This is both painful to read and is a lot of extra code to write when you actually expand it all into classes (each
oneOf/allOf
is another class). ClassOneOfKeywordSchema
will actually simplify this by automatically making theallOf
definitions for you if it detects other schema nodes thanoneOf
specified in the class bases. You can still do the fulloneOf/allOf
classes expansion manually though, it will result into the same specification.Warning
When
oneOf/allOf
automatic expansion occurs during schema generationWarning
When calling
deserialize()
, because the validation process requires exactly one of the variants to succeed to consider the whole object to evaluate as valid, it is important to insert more permissive validators later in the_one_of
iterator (orvalidator
keyword). For example, having a variant with all fields defined as optional (ie: withmissing=drop
) inserted as first item in_one_of
will make it always succeed regardless of following variants (since an empty schema with everything dropped is valid for optional-only elements). This would have as side effect of potentially failing the validation if other object are also valid depending on the received schema because the schema cannot be discriminated between many. If this occurs, it means the your schemas are too permissive.In the event that you have very similar schemas that can sometime match except one identifier (e.g.: field
type
defining the type of object), consider adding avalidator
to each sub-node with explicit values to solve the discrimination problem.As a shortcut, the OpenAPI keyword
discriminator
can be provided to try matching as a last resort.For example:
class Animal(ExtendedMappingSchema): name = ExtendedSchemaNode(String()) type = ExtendedSchemaNode(String()) # with explicit definition, this shouldn't be here ## With explicit definitions, each below 'Animal' class should be defined as follows ## type = ExtendedSchemaNode(String(), validator=colander.OneOf(['<animal>'])) class Cat(Animal): [...] # many **OPTIONAL** fields class Dog(Animal): [...] # many **OPTIONAL** fields # With the discriminator keyword, following is possible # (each schema must provide the same property name) class SomeAnimal(OneOfMappingSchema): discriminator = "type" _one_of = [ Cat(), Dog(), ] # If more specific mapping resolutions than 1-to-1 by name are needed, # an explicit dictionary can be specified instead. class SomeAnimal(OneOfMappingSchema): discriminator = { "propertyName": "type", # correspond to 'type' of 'Animal' "mapping": { "cat": Cat, "dog": Dog # map expected values to target schemas } } _one_of = [ Cat(), Dog(), ]
Note
Keyword
discriminator
supports a map of key-string to schemas-type as presented in the example, and the key must be located at the top level of the mapping. If onlydiscriminator = "<field>"
is provided, the definition will be created automatically using theexample
(which should be only the matching value) of the corresponding field of each node within the_one_of
mapping.When multiple valid schemas are matched against the input data, the error will be raised and returned with corresponding erroneous elements for each sub-schema (fully listed).
See also
AllOfKeywordSchema
AnyOfKeywordSchema
NotKeywordSchema
- class weaver.wps_restapi.swagger_definitions.DeployInputTypeDefinition(*args, **kwargs)[source]
Allows specifying multiple supported mapping schemas variants for an underlying schema definition.
Corresponds to the
oneOf
specifier of OpenAPI specification.Example:
class Variant1(MappingSchema): [...fields of Variant1...] class Variant2(MappingSchema): [...fields of Variant2...] class RequiredByBoth(MappingSchema): [...fields required by both Variant1 and Variant2...] class OneOfWithRequiredFields(OneOfKeywordSchema, RequiredByBoth): _one_of = (Variant1, Variant2) [...alternatively, field required by all variants here...]
In the above example, the validation (ie:
deserialize
) process will succeed if only one of the_one_of
variants’ validator completely succeed, and will fail if every variant fails validation execution. The operation will also fail if more than one validation succeeds.Note
Class
OneOfWithRequiredFields
in the example is a shortcut variant to generate a specification that represents the pseudo-codeoneOf([<list-of-objects-with-same-base>])
.The real OpenAPI method to implement the above very commonly occurring situation is as presented by the following pseudo-code:
oneOf[allOf[RequiredByBoth, Variant1], allOf[RequiredByBoth, Variant2]]
This is both painful to read and is a lot of extra code to write when you actually expand it all into classes (each
oneOf/allOf
is another class). ClassOneOfKeywordSchema
will actually simplify this by automatically making theallOf
definitions for you if it detects other schema nodes thanoneOf
specified in the class bases. You can still do the fulloneOf/allOf
classes expansion manually though, it will result into the same specification.Warning
When
oneOf/allOf
automatic expansion occurs during schema generationWarning
When calling
deserialize()
, because the validation process requires exactly one of the variants to succeed to consider the whole object to evaluate as valid, it is important to insert more permissive validators later in the_one_of
iterator (orvalidator
keyword). For example, having a variant with all fields defined as optional (ie: withmissing=drop
) inserted as first item in_one_of
will make it always succeed regardless of following variants (since an empty schema with everything dropped is valid for optional-only elements). This would have as side effect of potentially failing the validation if other object are also valid depending on the received schema because the schema cannot be discriminated between many. If this occurs, it means the your schemas are too permissive.In the event that you have very similar schemas that can sometime match except one identifier (e.g.: field
type
defining the type of object), consider adding avalidator
to each sub-node with explicit values to solve the discrimination problem.As a shortcut, the OpenAPI keyword
discriminator
can be provided to try matching as a last resort.For example:
class Animal(ExtendedMappingSchema): name = ExtendedSchemaNode(String()) type = ExtendedSchemaNode(String()) # with explicit definition, this shouldn't be here ## With explicit definitions, each below 'Animal' class should be defined as follows ## type = ExtendedSchemaNode(String(), validator=colander.OneOf(['<animal>'])) class Cat(Animal): [...] # many **OPTIONAL** fields class Dog(Animal): [...] # many **OPTIONAL** fields # With the discriminator keyword, following is possible # (each schema must provide the same property name) class SomeAnimal(OneOfMappingSchema): discriminator = "type" _one_of = [ Cat(), Dog(), ] # If more specific mapping resolutions than 1-to-1 by name are needed, # an explicit dictionary can be specified instead. class SomeAnimal(OneOfMappingSchema): discriminator = { "propertyName": "type", # correspond to 'type' of 'Animal' "mapping": { "cat": Cat, "dog": Dog # map expected values to target schemas } } _one_of = [ Cat(), Dog(), ]
Note
Keyword
discriminator
supports a map of key-string to schemas-type as presented in the example, and the key must be located at the top level of the mapping. If onlydiscriminator = "<field>"
is provided, the definition will be created automatically using theexample
(which should be only the matching value) of the corresponding field of each node within the_one_of
mapping.When multiple valid schemas are matched against the input data, the error will be raised and returned with corresponding erroneous elements for each sub-schema (fully listed).
See also
AllOfKeywordSchema
AnyOfKeywordSchema
NotKeywordSchema
- class weaver.wps_restapi.swagger_definitions.DescribeInputType(*args, **kwargs)[source]
Allows specifying all the required partial mapping schemas for an underlying complete schema definition.
Corresponds to the
allOf
specifier of OpenAPI specification.Example:
class RequiredItem(ExtendedMappingSchema): item = ExtendedSchemaNode(String()) class RequiredType(ExtendedMappingSchema): type = ExtendedSchemaNode(String()) class AllRequired(AnyKeywordSchema): _all_of = [RequiredItem(), RequiredType()]
Value parsed with schema this definition will be valid only when every since one of the sub-schemas is valid. Any sub-schema raising an invalid error for any reason with make the whole schema validation fail.
See also
OneOfKeywordSchema
AnyOfKeywordSchema
NotKeywordSchema
- class weaver.wps_restapi.swagger_definitions.DescribeInputTypeWithID(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.DeployInputType(*args, **kwargs)[source]
Allows specifying all the required partial mapping schemas for an underlying complete schema definition.
Corresponds to the
allOf
specifier of OpenAPI specification.Example:
class RequiredItem(ExtendedMappingSchema): item = ExtendedSchemaNode(String()) class RequiredType(ExtendedMappingSchema): type = ExtendedSchemaNode(String()) class AllRequired(AnyKeywordSchema): _all_of = [RequiredItem(), RequiredType()]
Value parsed with schema this definition will be valid only when every since one of the sub-schemas is valid. Any sub-schema raising an invalid error for any reason with make the whole schema validation fail.
See also
OneOfKeywordSchema
AnyOfKeywordSchema
NotKeywordSchema
- class weaver.wps_restapi.swagger_definitions.DeployInputTypeWithID(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.DescribeInputTypeList(*args, **kwargs)[source]
Listing of process inputs descriptions.
- class weaver.wps_restapi.swagger_definitions.DescribeInputTypeMap(*args: Any, **kwargs: Any)[source]
Description of all process inputs under mapping.
- class weaver.wps_restapi.swagger_definitions.DeployInputTypeList(*args, **kwargs)[source]
Listing of process input definitions to deploy.
- class weaver.wps_restapi.swagger_definitions.DeployInputTypeMap(*args: Any, **kwargs: Any)[source]
Definition of all process inputs under mapping.
- class weaver.wps_restapi.swagger_definitions.DeployInputTypeAny(*args, **kwargs)[source]
Allows specifying multiple supported mapping schemas variants for an underlying schema definition.
Corresponds to the
oneOf
specifier of OpenAPI specification.Example:
class Variant1(MappingSchema): [...fields of Variant1...] class Variant2(MappingSchema): [...fields of Variant2...] class RequiredByBoth(MappingSchema): [...fields required by both Variant1 and Variant2...] class OneOfWithRequiredFields(OneOfKeywordSchema, RequiredByBoth): _one_of = (Variant1, Variant2) [...alternatively, field required by all variants here...]
In the above example, the validation (ie:
deserialize
) process will succeed if only one of the_one_of
variants’ validator completely succeed, and will fail if every variant fails validation execution. The operation will also fail if more than one validation succeeds.Note
Class
OneOfWithRequiredFields
in the example is a shortcut variant to generate a specification that represents the pseudo-codeoneOf([<list-of-objects-with-same-base>])
.The real OpenAPI method to implement the above very commonly occurring situation is as presented by the following pseudo-code:
oneOf[allOf[RequiredByBoth, Variant1], allOf[RequiredByBoth, Variant2]]
This is both painful to read and is a lot of extra code to write when you actually expand it all into classes (each
oneOf/allOf
is another class). ClassOneOfKeywordSchema
will actually simplify this by automatically making theallOf
definitions for you if it detects other schema nodes thanoneOf
specified in the class bases. You can still do the fulloneOf/allOf
classes expansion manually though, it will result into the same specification.Warning
When
oneOf/allOf
automatic expansion occurs during schema generationWarning
When calling
deserialize()
, because the validation process requires exactly one of the variants to succeed to consider the whole object to evaluate as valid, it is important to insert more permissive validators later in the_one_of
iterator (orvalidator
keyword). For example, having a variant with all fields defined as optional (ie: withmissing=drop
) inserted as first item in_one_of
will make it always succeed regardless of following variants (since an empty schema with everything dropped is valid for optional-only elements). This would have as side effect of potentially failing the validation if other object are also valid depending on the received schema because the schema cannot be discriminated between many. If this occurs, it means the your schemas are too permissive.In the event that you have very similar schemas that can sometime match except one identifier (e.g.: field
type
defining the type of object), consider adding avalidator
to each sub-node with explicit values to solve the discrimination problem.As a shortcut, the OpenAPI keyword
discriminator
can be provided to try matching as a last resort.For example:
class Animal(ExtendedMappingSchema): name = ExtendedSchemaNode(String()) type = ExtendedSchemaNode(String()) # with explicit definition, this shouldn't be here ## With explicit definitions, each below 'Animal' class should be defined as follows ## type = ExtendedSchemaNode(String(), validator=colander.OneOf(['<animal>'])) class Cat(Animal): [...] # many **OPTIONAL** fields class Dog(Animal): [...] # many **OPTIONAL** fields # With the discriminator keyword, following is possible # (each schema must provide the same property name) class SomeAnimal(OneOfMappingSchema): discriminator = "type" _one_of = [ Cat(), Dog(), ] # If more specific mapping resolutions than 1-to-1 by name are needed, # an explicit dictionary can be specified instead. class SomeAnimal(OneOfMappingSchema): discriminator = { "propertyName": "type", # correspond to 'type' of 'Animal' "mapping": { "cat": Cat, "dog": Dog # map expected values to target schemas } } _one_of = [ Cat(), Dog(), ]
Note
Keyword
discriminator
supports a map of key-string to schemas-type as presented in the example, and the key must be located at the top level of the mapping. If onlydiscriminator = "<field>"
is provided, the definition will be created automatically using theexample
(which should be only the matching value) of the corresponding field of each node within the_one_of
mapping.When multiple valid schemas are matched against the input data, the error will be raised and returned with corresponding erroneous elements for each sub-schema (fully listed).
See also
AllOfKeywordSchema
AnyOfKeywordSchema
NotKeywordSchema
- class weaver.wps_restapi.swagger_definitions.LiteralOutputType(*args, **kwargs)[source]
Allows specifying specific schema conditions that fails underlying schema definition validation if present.
Corresponds to the
not
specifier of OpenAPI specification.Example:
class RequiredItem(ExtendedMappingSchema): item = ExtendedSchemaNode(String()) class MappingWithType(ExtendedMappingSchema): type = ExtendedSchemaNode(String()) class MappingWithoutType(NotKeywordSchema, RequiredItem): _not = [MappingWithType()] class MappingOnlyNotType(NotKeywordSchema): _not = [MappingWithType()] # following will raise invalid error even if 'item' is valid because 'type' is also present MappingWithoutType().deserialize({"type": "invalid", "item": "valid"}) # following will return successfully with only 'item' because 'type' was not present MappingWithoutType().deserialize({"item": "valid", "value": "ignore"}) # result: {"item": "valid"} # following will return an empty mapping dropping 'item' since it only needs to ensure 'type' was not present, # but did not provide any additional fields requirement from other class inheritances MappingOnlyNotType().deserialize({"item": "valid"}) # result: {}
See also
OneOfKeywordSchema
AllOfKeywordSchema
AnyOfKeywordSchema
- class weaver.wps_restapi.swagger_definitions.BoundingBoxOutputType(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.DescribeComplexOutputType(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.DeployComplexOutputType(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.DescribeOutputTypeDefinition(*args, **kwargs)[source]
Allows specifying multiple supported mapping schemas variants for an underlying schema definition.
Corresponds to the
oneOf
specifier of OpenAPI specification.Example:
class Variant1(MappingSchema): [...fields of Variant1...] class Variant2(MappingSchema): [...fields of Variant2...] class RequiredByBoth(MappingSchema): [...fields required by both Variant1 and Variant2...] class OneOfWithRequiredFields(OneOfKeywordSchema, RequiredByBoth): _one_of = (Variant1, Variant2) [...alternatively, field required by all variants here...]
In the above example, the validation (ie:
deserialize
) process will succeed if only one of the_one_of
variants’ validator completely succeed, and will fail if every variant fails validation execution. The operation will also fail if more than one validation succeeds.Note
Class
OneOfWithRequiredFields
in the example is a shortcut variant to generate a specification that represents the pseudo-codeoneOf([<list-of-objects-with-same-base>])
.The real OpenAPI method to implement the above very commonly occurring situation is as presented by the following pseudo-code:
oneOf[allOf[RequiredByBoth, Variant1], allOf[RequiredByBoth, Variant2]]
This is both painful to read and is a lot of extra code to write when you actually expand it all into classes (each
oneOf/allOf
is another class). ClassOneOfKeywordSchema
will actually simplify this by automatically making theallOf
definitions for you if it detects other schema nodes thanoneOf
specified in the class bases. You can still do the fulloneOf/allOf
classes expansion manually though, it will result into the same specification.Warning
When
oneOf/allOf
automatic expansion occurs during schema generationWarning
When calling
deserialize()
, because the validation process requires exactly one of the variants to succeed to consider the whole object to evaluate as valid, it is important to insert more permissive validators later in the_one_of
iterator (orvalidator
keyword). For example, having a variant with all fields defined as optional (ie: withmissing=drop
) inserted as first item in_one_of
will make it always succeed regardless of following variants (since an empty schema with everything dropped is valid for optional-only elements). This would have as side effect of potentially failing the validation if other object are also valid depending on the received schema because the schema cannot be discriminated between many. If this occurs, it means the your schemas are too permissive.In the event that you have very similar schemas that can sometime match except one identifier (e.g.: field
type
defining the type of object), consider adding avalidator
to each sub-node with explicit values to solve the discrimination problem.As a shortcut, the OpenAPI keyword
discriminator
can be provided to try matching as a last resort.For example:
class Animal(ExtendedMappingSchema): name = ExtendedSchemaNode(String()) type = ExtendedSchemaNode(String()) # with explicit definition, this shouldn't be here ## With explicit definitions, each below 'Animal' class should be defined as follows ## type = ExtendedSchemaNode(String(), validator=colander.OneOf(['<animal>'])) class Cat(Animal): [...] # many **OPTIONAL** fields class Dog(Animal): [...] # many **OPTIONAL** fields # With the discriminator keyword, following is possible # (each schema must provide the same property name) class SomeAnimal(OneOfMappingSchema): discriminator = "type" _one_of = [ Cat(), Dog(), ] # If more specific mapping resolutions than 1-to-1 by name are needed, # an explicit dictionary can be specified instead. class SomeAnimal(OneOfMappingSchema): discriminator = { "propertyName": "type", # correspond to 'type' of 'Animal' "mapping": { "cat": Cat, "dog": Dog # map expected values to target schemas } } _one_of = [ Cat(), Dog(), ]
Note
Keyword
discriminator
supports a map of key-string to schemas-type as presented in the example, and the key must be located at the top level of the mapping. If onlydiscriminator = "<field>"
is provided, the definition will be created automatically using theexample
(which should be only the matching value) of the corresponding field of each node within the_one_of
mapping.When multiple valid schemas are matched against the input data, the error will be raised and returned with corresponding erroneous elements for each sub-schema (fully listed).
See also
AllOfKeywordSchema
AnyOfKeywordSchema
NotKeywordSchema
- class weaver.wps_restapi.swagger_definitions.DeployOutputTypeDefinition(*args, **kwargs)[source]
Allows specifying multiple supported mapping schemas variants for an underlying schema definition.
Corresponds to the
oneOf
specifier of OpenAPI specification.Example:
class Variant1(MappingSchema): [...fields of Variant1...] class Variant2(MappingSchema): [...fields of Variant2...] class RequiredByBoth(MappingSchema): [...fields required by both Variant1 and Variant2...] class OneOfWithRequiredFields(OneOfKeywordSchema, RequiredByBoth): _one_of = (Variant1, Variant2) [...alternatively, field required by all variants here...]
In the above example, the validation (ie:
deserialize
) process will succeed if only one of the_one_of
variants’ validator completely succeed, and will fail if every variant fails validation execution. The operation will also fail if more than one validation succeeds.Note
Class
OneOfWithRequiredFields
in the example is a shortcut variant to generate a specification that represents the pseudo-codeoneOf([<list-of-objects-with-same-base>])
.The real OpenAPI method to implement the above very commonly occurring situation is as presented by the following pseudo-code:
oneOf[allOf[RequiredByBoth, Variant1], allOf[RequiredByBoth, Variant2]]
This is both painful to read and is a lot of extra code to write when you actually expand it all into classes (each
oneOf/allOf
is another class). ClassOneOfKeywordSchema
will actually simplify this by automatically making theallOf
definitions for you if it detects other schema nodes thanoneOf
specified in the class bases. You can still do the fulloneOf/allOf
classes expansion manually though, it will result into the same specification.Warning
When
oneOf/allOf
automatic expansion occurs during schema generationWarning
When calling
deserialize()
, because the validation process requires exactly one of the variants to succeed to consider the whole object to evaluate as valid, it is important to insert more permissive validators later in the_one_of
iterator (orvalidator
keyword). For example, having a variant with all fields defined as optional (ie: withmissing=drop
) inserted as first item in_one_of
will make it always succeed regardless of following variants (since an empty schema with everything dropped is valid for optional-only elements). This would have as side effect of potentially failing the validation if other object are also valid depending on the received schema because the schema cannot be discriminated between many. If this occurs, it means the your schemas are too permissive.In the event that you have very similar schemas that can sometime match except one identifier (e.g.: field
type
defining the type of object), consider adding avalidator
to each sub-node with explicit values to solve the discrimination problem.As a shortcut, the OpenAPI keyword
discriminator
can be provided to try matching as a last resort.For example:
class Animal(ExtendedMappingSchema): name = ExtendedSchemaNode(String()) type = ExtendedSchemaNode(String()) # with explicit definition, this shouldn't be here ## With explicit definitions, each below 'Animal' class should be defined as follows ## type = ExtendedSchemaNode(String(), validator=colander.OneOf(['<animal>'])) class Cat(Animal): [...] # many **OPTIONAL** fields class Dog(Animal): [...] # many **OPTIONAL** fields # With the discriminator keyword, following is possible # (each schema must provide the same property name) class SomeAnimal(OneOfMappingSchema): discriminator = "type" _one_of = [ Cat(), Dog(), ] # If more specific mapping resolutions than 1-to-1 by name are needed, # an explicit dictionary can be specified instead. class SomeAnimal(OneOfMappingSchema): discriminator = { "propertyName": "type", # correspond to 'type' of 'Animal' "mapping": { "cat": Cat, "dog": Dog # map expected values to target schemas } } _one_of = [ Cat(), Dog(), ]
Note
Keyword
discriminator
supports a map of key-string to schemas-type as presented in the example, and the key must be located at the top level of the mapping. If onlydiscriminator = "<field>"
is provided, the definition will be created automatically using theexample
(which should be only the matching value) of the corresponding field of each node within the_one_of
mapping.When multiple valid schemas are matched against the input data, the error will be raised and returned with corresponding erroneous elements for each sub-schema (fully listed).
See also
AllOfKeywordSchema
AnyOfKeywordSchema
NotKeywordSchema
- class weaver.wps_restapi.swagger_definitions.DescribeOutputType(*args, **kwargs)[source]
Allows specifying all the required partial mapping schemas for an underlying complete schema definition.
Corresponds to the
allOf
specifier of OpenAPI specification.Example:
class RequiredItem(ExtendedMappingSchema): item = ExtendedSchemaNode(String()) class RequiredType(ExtendedMappingSchema): type = ExtendedSchemaNode(String()) class AllRequired(AnyKeywordSchema): _all_of = [RequiredItem(), RequiredType()]
Value parsed with schema this definition will be valid only when every since one of the sub-schemas is valid. Any sub-schema raising an invalid error for any reason with make the whole schema validation fail.
See also
OneOfKeywordSchema
AnyOfKeywordSchema
NotKeywordSchema
- class weaver.wps_restapi.swagger_definitions.DescribeOutputTypeWithID(*args, **kwargs)[source]
Combines multiple extensions of
colander.MappingSchema
handle their corresponding keywords.Resolution is done so that
default
keyword is used first to resolve a missing object duringdeserialize()
call, and then removes the node completely if nodefault
was provided.See also
DefaultSchemaNode
DropableSchemaNode
VariableSchemaNode
ExtendedSchemaNode
ExtendedSequenceSchema
SchemaRefMappingSchema
SortableMappingSchema
PermissiveMappingSchema
- class weaver.wps_restapi.swagger_definitions.DescribeOutputTypeList(