Add BooleanSchema

Author: charjr

docs/object-simplifications.md

@@ -0,0 +1,56 @@
+# How The Reader Simplifies Your OpenAPI
+
+Besides simply parsing your OpenAPI into `Validated` objects,
+the reader is designed to _simplify the developer experience_ of other OpenAPI tools.
+
+## Standard Simplifications
+
+### Never Worry About Uninitialized Properties
+Properties should be safe to access:
+All properties have a value.
+`null` represents an omitted field _if_ no other value can be safely assumed.
+
+### Strong Typehints
+Data structures should be easily discoverable.
+All properties should have strong typehints.
+
+## Opinionated Simplifications
+
+## Narrow Typehints
+Typehints are narrowed, if and only if, it has no impact on expressiveness.
+
+### String Metadata Is Always String
+
+Optional metadata is expressed in two ways;
+1. There is data
+2. There is not
+
+As such, the Reader structures metadata in two ways:
+1. A string containing non-whitespace characters
+2. An empty string `''`
+
+When accessing string metadata only one check is necessary:
+
+```php
+if ($metadata !== '') {
+    // do something...
+}
+```
+
+## Combined Fields
+Data is combined, if and only if, it has no impact on expressiveness.
+
+### Maximum|Minimum are combined with ExclusiveMaximum|ExclusiveMinimum
+
+The structure of numeric maximums and minimums vary between versions.
+However, both versions only express two things:
+- Is there a limit
+- Is it exclusive
+
+As such the Reader combines the fields into:
+- A `Limit|null $maximum`. 
+- A `Limit|null $minimum`.
+
+Where A `Limit` has two properties:
+- `float|int $limit` 
+- `bool $exclusive`

docs/validation-deviations.md

@@ -0,0 +1,77 @@
+# Validation And How It Deviates From OpenAPI Specification
+This page documents where validation deviates from the OpenAPI Specification.
+
+## Stricter Requirements
+It is stricter when it comes to providing an unambiguous specification.
+This helps to avoid confusion as well as simplify development for other OpenAPI tools.
+
+### OperationId Is Required
+
+Operations MUST have an [operationId](https://github.com/OAI/OpenAPI-Specification/blob/3.1.0/versions/3.0.3.md#fixed-fields-8).
+
+`operationId` is a unique string used to identify an operation.
+By making it required, it serves as a _reliable_ method of identification.
+
+### Query Strings Must Be Unambiguous
+
+Operations MUST NOT use more than one _ambiguous parameter_.
+
+In this context, an _ambiguous parameter_ is defined as being `in:query` with one of the following combinations:
+- `type:object` with `style:form` and `explode:true`
+- `type:object` or `type:array` with `style:spaceDelimited`
+- `type:object` or `type:array` with `style:pipeDelimited`
+
+If everything else can be identified; then through a process of elimination, the ambiguous segment belongs to the _ambiguous parameter_
+
+If an operation contains two or more _ambiguous parameters_, then there are multiple ways of interpreting the ambiguous segment.
+This ambiguity means the query string cannot be resolved deterministically.
+As such, it is not allowed.
+
+## Looser Requirements
+
+These requirements are looser than the OpenAPI Specification.
+Where the OpenAPI Specification would be invalid, the reader will add a warning to the `Validated` object.
+
+### MultipleOf Can Be Negative
+
+Normally `multipleOf` MUST be a positive non-zero number.
+
+The Reader allows `multipleOf` to be any non-zero number.
+A multiple of a negative number is also a multiple of its absolute value.
+It's more confusing, but what is expressed is identical.
+
+Therefore, if a negative value is given:
+- You will receive a Warning
+- The absolute value will be used
+
+### AllOf, AnyOf and OneOf Can Be Empty
+
+Normally, `allOf`, `anyOf` and `oneOf` MUST be non-empty.
+
+The Reader allows them to be empty.
+
+[] and null express basically the same thing, no value.
+By replacing null with [], we can narrow the typehint from `array|null` to `array`.
+Simplifies code using it.
+
+### Required Can Be Empty 
+
+OpenAPI 3.0 states `required` MUST be non-empty.  
+OpenAPI 3.1 allows `required` to be empty and defaults to empty if omitted. 
+
+The Reader always allows `required` to be empty and defaults to empty if omitted.
+This allows us to narrow the typehint for `required` to always being an array.
+
+If an empty array is given:
+- If your API is using 3.0, you will receive a Warning
+- An empty array will be used
+
+### Required Can Contain Duplicates
+
+Normally `required` MUST contain unique values.
+
+The Reader allows `required` to contain duplicates.
+
+If a duplicate item is found:
+- You will receive a Warning
+- The duplicate will be removed.

docs/validation.md

@@ -20,8 +20,8 @@ public function __construct(
          * 3.0 https://datatracker.ietf.org/doc/html/draft-wright-json-schema-validation-00#autoid-11
          * 3.1 https://json-schema.org/draft/2020-12/json-schema-validation#name-validation-keywords-for-any
          */
-        /** @var null|string|array<string> */
-        public null|string|array $type = null,
+        /** @var string[]|string|null */
+        public array|string|null $type = null,
         /** @var array<Value>|null */
         public array|null $enum = null,
         public Value|null $const = null,
@@ -81,7 +81,7 @@ public function __construct(
         public array|null $anyOf = null,
         /** @var array<Schema>|null */
         public array|null $oneOf = null,
-        public Schema|null $not = null,
+        public bool|Schema|null $not = null,
         /**
          * Keywords for applying subschemas conditionally
          * 3.0 https://datatracker.ietf.org/doc/html/draft-wright-json-schema-validation-00#section-5.22

src/ValueObject/Partial/Schema.php

@@ -6,5 +6,4 @@
 
 interface Schema
 {
-
 }

src/ValueObject/Valid/Schema.php

@@ -63,9 +63,10 @@ final class Keywords extends Validated implements Valid\Schema
 
     public function __construct(
         Identifier $identifier,
+        Valid\Warnings $warnings,
         Partial\Schema $schema
     ) {
-        parent::__construct($identifier);
+        parent::__construct($identifier, $warnings);
 
         $this->types = $this->validateTypes($schema->type, $schema->nullable);
         $this->enum = $this->reviewEnum($this->types, $schema->enum);
@@ -102,11 +103,11 @@ public function __construct(
         $this->properties = $this->validateProperties($schema->properties);
         $this->additionalProperties = new Schema(
             $this->appendedIdentifier('additionalProperties'),
-            $schema->additionalProperties
+            $schema->additionalProperties,
         );
 
 
-        // make empty arrays instead of null
+        //TODO throw ShouldBeBooleanSchema::false if allOf contains false schema
         $this->allOf = $this->validateSubSchemas('allOf', $schema->allOf);
         $this->anyOf = $this->validateSubSchemas('anyOf', $schema->anyOf);
         $this->oneOf = $this->validateSubSchemas('oneOf', $schema->oneOf);
@@ -297,7 +298,7 @@ private function validateMinMax(
         if (is_float($exclusiveMinMax) || is_integer($exclusiveMinMax)) {
             throw InvalidOpenAPI::numericExclusiveMinMaxIn30(
                 $this->getIdentifier(),
-                $keyword,
+                $exclusiveKeyword,
             );
         }
 
@@ -349,7 +350,7 @@ private function reviewItems(
 
         return new Schema(
             $this->getIdentifier()->append('items'),
-            $items ?? new Partial\Schema(),
+            $items ?? true,
         );
     }
 
@@ -393,12 +394,13 @@ private function validateSubSchemas(string $keyword, ?array $subSchemas): array
         }
 
         $result = [];
-        //TODO if all subschemas have a title, use that instead of their index
         foreach ($subSchemas as $index => $subSchema) {
-            $result[] = new Schema(
-                $this->getIdentifier()->append("$keyword($index)"),
-                $subSchema
-            );
+            $identifier = $this->appendedIdentifier($keyword, sprintf(
+                empty(trim($subSchema->title ?? '')) ? '%s' : '%2$s[%1$s]',
+                $index,
+                trim($subSchema->title ?? ''),
+            ));
+            $result[] = new Schema($identifier, $subSchema);
         }
 
         return $result;

src/ValueObject/Valid/V30/Keywords.php

@@ -26,7 +26,11 @@ public function __construct(
             $this->value = $schema;
         } else {
             try {
-                $this->value = new Keywords($identifier, $schema);
+                $this->value = new Keywords(
+                    $this->getIdentifier(),
+                    $this->getWarnings(),
+                    $schema
+                );
             } catch (SchemaShouldBeBoolean $e) {
                 $this->addWarning($e->getMessage(), Valid\Warning::IMPOSSIBLE_SCHEMA);
                 $this->value = $e->getCode() === SchemaShouldBeBoolean::ALWAYS_TRUE;

src/ValueObject/Valid/V30/Schema.php

@@ -5,7 +5,7 @@
 namespace Membrane\OpenAPIReader\ValueObject\Valid;
 
 /**
- * A Validated object **may** make _opinionated optimizations_ to improve DX.
+ * A Validated object **may** make _opinionated simplifications_ to improve DX.
  * - It **may** change _appearance_ from its OpenAPI counterpart.
  * - It **must** express the same _intent_ as its OpenAPI counterpart.
  */
@@ -15,8 +15,9 @@ abstract class Validated implements HasIdentifier, HasWarnings
 
     public function __construct(
         private readonly Identifier $identifier,
+        Warnings|null $warnings = null,
     ) {
-        $this->warnings = new Warnings($this->identifier);
+        $this->warnings = $warnings ?? new Warnings($this->identifier);
     }
 
     public function getIdentifier(): Identifier

src/ValueObject/Valid/Validated.php

@@ -45,5 +45,4 @@ public function __toString(): string
         return json_encode($this->value) ?:
             throw new RuntimeException('Failed to encode value');
     }
-
 }