schemas array.
*
* @var string
*/
public $schema = Generator::UNDEFINED;
/**
* Can be used to decorate a user interface with information about the data produced by this user interface.
*
* Preferably short; use description for more details.
*
* @var string
*/
public $title = Generator::UNDEFINED;
/**
* A description will provide explanation about the purpose of the instance described by this schema.
*
* @var string
*/
public $description = Generator::UNDEFINED;
/**
* The maximum number of properties allowed in an object instance.
* An object instance is valid against this property if its number of properties is less than, or equal to, the
* value of this attribute.
*
* @var int
*/
public $maxProperties = Generator::UNDEFINED;
/**
* The minimum number of properties allowed in an object instance.
* An object instance is valid against this property if its number of properties is greater than, or equal to, the
* value of this attribute.
*
* @var int
*/
public $minProperties = Generator::UNDEFINED;
/**
* An object instance is valid against this property if its property set contains all elements in this property's
* array value.
*
* @var list
*/
public $required = Generator::UNDEFINED;
/**
* A collection of properties to define for an object.
*
* Each property is represented as an instance of the Property class.
*
* @var list
*/
public $properties = Generator::UNDEFINED;
/**
* The type of the schema/property.
*
* OpenApi v3.0: The value MUST be one of "string", "number", "integer", "boolean", "array" or "object".
*
* Since OpenApi v3.1 an array of types may be used.
*
* @var string|non-empty-array
*/
public $type = Generator::UNDEFINED;
/**
* The extending format for the previously mentioned type.
*
* @see [Data Types](https://spec.openapis.org/oas/v3.1.1.html#data-types)
*
* @var string
*/
public $format = Generator::UNDEFINED;
/**
* Required if type is "array". Describes the type of items in the array.
*
* @var Items
*/
public $items = Generator::UNDEFINED;
/**
* Determines the format of the array if type array is used.
*
* Possible values are:
* - csv: comma separated values foo,bar.
* - ssv: space separated values foo bar.
* - tsv: tab separated values foo\tbar.
* - pipes: pipe separated values foo|bar.
* - multi: corresponds to multiple parameter instances instead of multiple values for a single instance
* foo=bar&foo=baz. This is valid only for parameters of type query or formData. Default
* value is csv.
*
* @var string
*/
public $collectionFormat = Generator::UNDEFINED;
/**
* A string instance is considered valid if the regular expression matches the instance successfully.
*
* @var string
*/
public $pattern = Generator::UNDEFINED;
/**
* A numeric instance is valid against "multipleOf" if the result of the division of the instance by this
* property's value is an integer.
*
* @var int|float
*/
public $multipleOf = Generator::UNDEFINED;
/**
* Adds support for polymorphism.
*
* The discriminator is an object name that is used to differentiate between other schemas which may satisfy the
* payload description. See Composition and Inheritance for more details.
*
* @var Discriminator
*/
public $discriminator = Generator::UNDEFINED;
/**
* Declares the property as "read only".
*
* Relevant only for Schema "properties" definitions.
*
* This means that it may be sent as part of a response but should not be sent as part of the request.
* If the property is marked as readOnly being true and is in the required list, the required will take effect on
* the response only. A property must not be marked as both readOnly and writeOnly being true. Default value is
* false.
*
* @var bool
*/
public $readOnly = Generator::UNDEFINED;
/**
* Declares the property as "write only".
*
* Relevant only for Schema "properties" definitions.
* Therefore, it may be sent as part of a request but should not be sent as part of the response.
* If the property is marked as writeOnly being true and is in the required list, the required will take effect on
* the request only. A property must not be marked as both readOnly and writeOnly being true. Default value is
* false.
*
* @var bool
*/
public $writeOnly = Generator::UNDEFINED;
/**
* This may be used only on properties schemas.
*
* It has no effect on root schemas.
* Adds additional metadata to describe the XML representation of this property.
*
* @var Xml
*/
public $xml = Generator::UNDEFINED;
/**
* Additional external documentation for this schema.
*
* @var ExternalDocumentation
*/
public $externalDocs = Generator::UNDEFINED;
/**
* A free-form property to include an example of an instance for this schema.
*
* To represent examples that cannot naturally be represented in JSON or YAML, a string value can be used to
* contain the example with escaping where necessary.
*
* @var mixed
*/
public $example = Generator::UNDEFINED;
/**
* Examples of the schema.
*
* Each example should contain a value in the correct format as specified in the parameter encoding.
* The examples object is mutually exclusive of the example object.
* Furthermore, if referencing a schema which contains an example, the examples value shall override the example provided by the schema.
*
* @since OpenAPI 3.1.0
* @var array
*/
public $examples = Generator::UNDEFINED;
/**
* Allows sending a null value for the defined schema.
* Default value is false.
*
* This must not be used when using OpenApi version 3.1,
* instead make the "type" property an array and add "null" as a possible type.
*
* @var bool
*
* @see https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0
*/
public $nullable = Generator::UNDEFINED;
/**
* Specifies that a schema is deprecated and should be transitioned out of usage.
* Default value is false.
*
* @var bool
*/
public $deprecated = Generator::UNDEFINED;
/**
* An instance validates successfully against this property if it validates successfully against all schemas
* defined by this property's value.
*
* @var array
*/
public $allOf = Generator::UNDEFINED;
/**
* An instance validates successfully against this property if it validates successfully against at least one
* schema defined by this property's value.
*
* @var array
*/
public $anyOf = Generator::UNDEFINED;
/**
* An instance validates successfully against this property if it validates successfully against exactly one schema
* defined by this property's value.
*
* @var array
*/
public $oneOf = Generator::UNDEFINED;
/**
* https://spec.openapis.org/oas/v3.1.0.html#considerations-for-file-uploads
* https://json-schema.org/draft/2020-12/draft-bhutton-json-schema-validation-00#rfc.section.8.3.
*
* @var string
*/
public $contentEncoding = Generator::UNDEFINED;
/**
* https://spec.openapis.org/oas/v3.1.0.html#considerations-for-file-uploads
* https://json-schema.org/draft/2020-12/draft-bhutton-json-schema-validation-00#rfc.section.8.4.
*
* @var string
*/
public $contentMediaType = Generator::UNDEFINED;
/**
* @inheritdoc
*/
public static $_types = [
'title' => 'string',
'description' => 'string',
'required' => '[string]',
'format' => 'string',
'collectionFormat' => ['csv', 'ssv', 'tsv', 'pipes', 'multi'],
'maximum' => 'number',
'exclusiveMaximum' => 'boolean|number',
'minimum' => 'number',
'exclusiveMinimum' => 'boolean|number',
'maxLength' => 'integer',
'minLength' => 'integer',
'pattern' => 'string',
'maxItems' => 'integer',
'minItems' => 'integer',
'uniqueItems' => 'boolean',
'multipleOf' => 'integer',
'allOf' => '[' . Schema::class . ']',
'oneOf' => '[' . Schema::class . ']',
'anyOf' => '[' . Schema::class . ']',
'contentEncoding' => 'string',
'contentMediaType' => 'string',
];
/**
* @inheritdoc
*/
public static $_nested = [
Discriminator::class => 'discriminator',
Items::class => 'items',
Property::class => ['properties', 'property'],
ExternalDocumentation::class => 'externalDocs',
Examples::class => ['examples', 'example'],
Xml::class => 'xml',
AdditionalProperties::class => 'additionalProperties',
Attachable::class => ['attachables'],
];
/**
* @inheritdoc
*/
public static $_parents = [
Components::class,
Parameter::class,
PathParameter::class,
MediaType::class,
Header::class,
];
/**
* Type safe nullable check.
*
* Defaults to `false` when nullable is not set.
*/
public function isNullable(): bool
{
return !Generator::isDefault($this->nullable) && $this->nullable;
}
/**
* Check if the given type is valid for this schema.
*/
public function hasType(string $type): bool
{
return in_array($type, (array) $this->type, strict: true);
}
public function jsonSerialize(): \stdClass
{
$data = parent::jsonSerialize();
if ($this->_context->isVersion('3.0.x')) {
unset($data->examples);
if (isset($data->const)) {
$data->enum = [$data->const];
unset($data->const);
}
}
return $data;
}
#[\Override]
public function validate(?Analysis $analysis = null, string $version = OpenApi::DEFAULT_VERSION, ?object $context = null): bool
{
$isValid = parent::validate($analysis, $version, $context);
if ($this->hasType('array') && Generator::isDefault($this->items)) {
$this->_context->logger->warning('@OA\\Items() is required when ' . $this->identity() . ' has type "array" in ' . $this->_context);
$isValid = false;
}
if (OpenApi::versionMatch($version, '3.0.x')) {
if (!Generator::isDefault($this->examples)) {
$this->_context->logger->warning(static::shorten(static::class) . '::examples is only allowed as of 3.1.0 in ' . $this->_context);
$isValid = false;
}
}
return $isValid;
}
}