Merge pull request #26 from swaggest/error-inspect

error readability

Author: vearutop

README.md

@@ -102,6 +102,29 @@ $schema = Schema::import(true); // permissive schema, always validates
 $schema = Schema::import(false); // restrictive schema, always invalidates
 ```
 
+### Understanding error cause
+
+With complex schemas it may be hard to find out what's wrong with your data. Exception message can look like:
+
+```
+No valid results for oneOf {
+ 0: Enum failed, enum: ["a"], data: "f" at #->properties:root->patternProperties[^[a-zA-Z0-9_]+$]:zoo->oneOf[0]
+ 1: Enum failed, enum: ["b"], data: "f" at #->properties:root->patternProperties[^[a-zA-Z0-9_]+$]:zoo->oneOf[1]
+ 2: No valid results for anyOf {
+   0: Enum failed, enum: ["c"], data: "f" at #->properties:root->patternProperties[^[a-zA-Z0-9_]+$]:zoo->oneOf[2]->$ref[#/cde]->anyOf[0]
+   1: Enum failed, enum: ["d"], data: "f" at #->properties:root->patternProperties[^[a-zA-Z0-9_]+$]:zoo->oneOf[2]->$ref[#/cde]->anyOf[1]
+   2: Enum failed, enum: ["e"], data: "f" at #->properties:root->patternProperties[^[a-zA-Z0-9_]+$]:zoo->oneOf[2]->$ref[#/cde]->anyOf[2]
+ } at #->properties:root->patternProperties[^[a-zA-Z0-9_]+$]:zoo->oneOf[2]->$ref[#/cde]
+} at #->properties:root->patternProperties[^[a-zA-Z0-9_]+$]:zoo
+```
+
+For ambiguous schemas defined with `oneOf`/`anyOf` message is indented multi-line string.
+
+Processing path is a combination of schema and data pointers. You can use `InvalidValue->getSchemaPointer()`
+and `InvalidValue->getDataPointer()` to extract schema/data pointer.
+
+You can build error tree using `InvalidValue->inspect()`.
+
 ### PHP structured classes with validation
 
 ```php

composer.lock

@@ -0,0 +1,19 @@
+<?php
+
+namespace Swaggest\JsonSchema\Exception;
+
+use Swaggest\JsonSchema\InvalidValue;
+
+class Error
+{
+    /** @var string */
+    public $error;
+    /** @var string[] */
+    public $schemaPointers;
+    /** @var string */
+    public $dataPointer;
+    /** @var string */
+    public $processingPath;
+    /** @var Error[] */
+    public $subErrors;
+}

src/Exception/Error.php

@@ -6,5 +6,6 @@
 
 class LogicException extends InvalidValue
 {
-
+    /** @var InvalidValue[] */
+    public $subErrors;
 }

src/Exception/LogicException.php

@@ -59,6 +59,8 @@ public static function resolveURI($parent, $current)
                 }
             } elseif (false !== $pos = strrpos($parentParts[0], '/')) {
                 $resultParts[0] = substr($parentParts[0], 0, $pos + 1) . $currentParts[0];
+            } else {
+                $resultParts[0] = $currentParts[0];
             }
         }
 

src/Helper.php

@@ -2,13 +2,51 @@
 
 namespace Swaggest\JsonSchema;
 
+use Swaggest\JsonSchema\Exception\Error;
+use Swaggest\JsonSchema\Exception\LogicException;
+use Swaggest\JsonSchema\Path\PointerUtil;
+
 class InvalidValue extends Exception
 {
+    public $error;
+    public $path;
+
     public function addPath($path)
     {
+        if ($this->error === null) {
+            $this->error = $this->message;
+        }
+        $this->path = $path;
         $this->message .= ' at ' . $path;
     }
 
     const INVALID_VALUE = 1;
     const NOT_IMPLEMENTED = 2;
+
+
+    public function inspect()
+    {
+        $error = new Error();
+        $error->error = $this->error;
+        $error->processingPath = $this->path;
+        $error->dataPointer = PointerUtil::getDataPointer($error->processingPath);
+        $error->schemaPointers = PointerUtil::getSchemaPointers($error->processingPath);
+        if ($this instanceof LogicException) {
+            foreach ($this->subErrors as $subError) {
+                $error->subErrors[] = $subError->inspect();
+            }
+        }
+        return $error;
+    }
+
+    public function getSchemaPointer()
+    {
+        return PointerUtil::getSchemaPointer($this->path);
+    }
+
+    public function getDataPointer()
+    {
+        return PointerUtil::getDataPointer($this->path);
+    }
+
 }

src/InvalidValue.php

@@ -3,27 +3,87 @@
 namespace Swaggest\JsonSchema\Path;
 
 use Swaggest\JsonDiff\JsonPointer;
+use Swaggest\JsonSchema\Schema;
 
 class PointerUtil
 {
+    /**
+     * Builds JSON pointer to schema from processing path
+     * Path example: #->properties:responses->additionalProperties:envvar->properties:schema
+     * @param string $path
+     * @param bool $isURIFragmentId
+     * @return string
+     */
+    public static function getSchemaPointer($path, $isURIFragmentId = false)
+    {
+        $result = self::getSchemaPointers($path, $isURIFragmentId);
+        return array_pop($result);
+    }
+
+    /**
+     * Builds JSON pointer to schema from processing path
+     * Path example: #->properties:responses->additionalProperties:envvar->properties:schema
+     * @param string $path
+     * @param bool $isURIFragmentId
+     * @return string[]
+     */
+    public static function getSchemaPointers($path, $isURIFragmentId = false)
+    {
+        $items = explode('->', $path);
+        unset($items[0]);
+        $result = array();
+        $pointer = $isURIFragmentId ? '#' : '';
+        foreach ($items as $item) {
+            $parts = explode(':', $item);
+            if (isset($parts[0])) {
+                $schemaPaths = explode('[', $parts[0], 2);
+                if ($schemaPaths[0] === Schema::PROP_REF) {
+                    $result[] = $pointer . '/' . JsonPointer::escapeSegment(Schema::PROP_REF, $isURIFragmentId);
+                    $pointer = self::rebuildPointer(substr($schemaPaths[1], 0, -1), $isURIFragmentId);
+                    continue;
+                }
+                $pointer .= '/' . JsonPointer::escapeSegment($schemaPaths[0], $isURIFragmentId);
+                if (isset($schemaPaths[1])) {
+                    $pointer .= '/' . JsonPointer::escapeSegment(substr($schemaPaths[1], 0, -1), $isURIFragmentId);
+                } elseif ($parts[1]) {
+                    $pointer .= '/' . JsonPointer::escapeSegment($parts[1], $isURIFragmentId);
+                }
+            }
+        }
+        $result[] = $pointer;
+        return $result;
+    }
+
+
     /**
      * Builds JSON pointer to data from processing path
      * Path example: #->properties:responses->additionalProperties:envvar->properties:schema
      * @param string $path
+     * @param bool $isURIFragmentId
      * @return string
-     * @todo proper path items escaping/moving to native JSON pointers
      */
-    public static function getDataPointer($path) {
+    public static function getDataPointer($path, $isURIFragmentId = false)
+    {
         $items = explode('->', $path);
         unset($items[0]);
-        $result = '#';
+        $result = $isURIFragmentId ? '#' : '';
         foreach ($items as $item) {
             $parts = explode(':', $item);
             if (isset($parts[1])) {
-                $result .= '/' . JsonPointer::escapeSegment($parts[1], true);
+                $result .= '/' . JsonPointer::escapeSegment($parts[1], $isURIFragmentId);
             }
         }
         return $result;
     }
 
+    private static function rebuildPointer($pointer, $isURIFragmentId = false)
+    {
+        $parts = JsonPointer::splitPath($pointer);
+        $result = $isURIFragmentId ? '#' : '';
+        foreach ($parts as $item) {
+            $result .= '/' . JsonPointer::escapeSegment($item, $isURIFragmentId);
+        }
+        return $result;
+    }
+
 }

src/Path/PointerUtil.php

@@ -39,6 +39,10 @@ public function getResolutionScope()
     }
 
 
+    /**
+     * @param string $id
+     * @return string
+     */
     public function updateResolutionScope($id)
     {
         $id = rtrim($id, '#');