Add JSON Pointer to structure classes

src/Concerns/HasASchema.php

@@ -17,6 +17,6 @@ public function schema(): Schema|Reference
             return new Reference($schema['$ref']);
         }
 
-        return new Schema($schema);
+        return new Schema($schema, $this->pointer?->append('schema'));
     }
 }

src/References/JsonPointer.php

@@ -4,6 +4,8 @@
 
 class JsonPointer
 {
+    private string $value;
+
     private string $filename;
 
     /**
@@ -13,6 +15,8 @@ class JsonPointer
 
     public function __construct(string $value)
     {
+        $this->value = $value;
+
         $splitRef = explode('#', $value, 2);
 
         $this->filename = $splitRef[0];
@@ -22,6 +26,22 @@ public function __construct(string $value)
         }
     }
 
+    public function value(): string
+    {
+        return $this->value;
+    }
+
+    public function append(string ...$values): self
+    {
+        $properties = $this->propertyPaths;
+
+        foreach ($values as $value) {
+            array_push($properties, $this->encodePath($value));
+        }
+
+        return new self($this->filename . '/' .  implode('/', $properties));
+    }
+
     /**
      * @return array<array-key,string>
      */
@@ -39,6 +59,11 @@ private function decodePropertyPaths(string $propertyPathString): array
         return $paths;
     }
 
+    private function encodePath(string $path): string
+    {
+        return strtr($path, ['/' => '~1', '~' => '~0', '%' => '%25']);
+    }
+
     private function decodePath(string $path): string
     {
         return strtr($path, ['~1' => '/', '~0' => '~', '%25' => '%']);

src/Structure/Callbacks.php

@@ -5,6 +5,7 @@
 use Apiboard\OpenAPI\Concerns\CanBeUsedAsArray;
 use Apiboard\OpenAPI\Concerns\HasReferences;
 use Apiboard\OpenAPI\Concerns\HasVendorExtensions;
+use Apiboard\OpenAPI\References\JsonPointer;
 use Apiboard\OpenAPI\References\Reference;
 use ArrayAccess;
 use Countable;
@@ -16,7 +17,7 @@ final class Callbacks extends Structure implements ArrayAccess, Countable, Itera
     use HasReferences;
     use HasVendorExtensions;
 
-    public function __construct(array $data)
+    public function __construct(array $data, JsonPointer $pointer = null)
     {
         foreach ($data as $expression => $value) {
             $data[$expression] = match (true) {
@@ -26,7 +27,7 @@ public function __construct(array $data)
             };
         }
 
-        $this->data = $data;
+        parent::__construct($data, $pointer);
     }
 
     public function offsetGet(mixed $expression): PathItem|Reference|null

src/Structure/Components.php

@@ -3,6 +3,7 @@
 namespace Apiboard\OpenAPI\Structure;
 
 use Apiboard\OpenAPI\Concerns\HasVendorExtensions;
+use Apiboard\OpenAPI\References\JsonPointer;
 
 final class Components extends Structure
 {
@@ -16,7 +17,9 @@ public function schemas(): ?Schemas
             return null;
         }
 
-        return new Schemas($schemas);
+        $pointer = new JsonPointer('/components/schemas');
+
+        return new Schemas($schemas, $pointer);
     }
 
     public function responses(): ?Responses
@@ -27,7 +30,9 @@ public function responses(): ?Responses
             return null;
         }
 
-        return new Responses($responses);
+        $pointer = new JsonPointer('/components/responses');
+
+        return new Responses($responses, $pointer);
     }
 
     public function parameters(): ?Parameters
@@ -38,7 +43,9 @@ public function parameters(): ?Parameters
             return null;
         }
 
-        return new Parameters($parameters);
+        $pointer = new JsonPointer('/components/parameters');
+
+        return new Parameters($parameters, $pointer);
     }
 
     public function examples(): ?Examples
@@ -49,7 +56,9 @@ public function examples(): ?Examples
             return null;
         }
 
-        return new Examples($examples);
+        $pointer = new JsonPointer('/components/examples');
+
+        return new Examples($examples, $pointer);
     }
 
     public function requestBodies(): ?RequestBodies
@@ -60,7 +69,9 @@ public function requestBodies(): ?RequestBodies
             return null;
         }
 
-        return new RequestBodies($requestBodies);
+        $pointer = new JsonPointer('/components/requestBodies');
+
+        return new RequestBodies($requestBodies, $pointer);
     }
 
     public function headers(): ?Headers
@@ -71,7 +82,9 @@ public function headers(): ?Headers
             return null;
         }
 
-        return new Headers($headers);
+        $pointer = new JsonPointer('/components/headers');
+
+        return new Headers($headers, $pointer);
     }
 
     public function securitySchemes(): ?SecuritySchemes
@@ -82,7 +95,9 @@ public function securitySchemes(): ?SecuritySchemes
             return null;
         }
 
-        return new SecuritySchemes($securitySchemes);
+        $pointer = new JsonPointer('/components/securitySchemes');
+
+        return new SecuritySchemes($securitySchemes, $pointer);
     }
 
     public function links(): ?Links
@@ -93,7 +108,9 @@ public function links(): ?Links
             return null;
         }
 
-        return new Links($links);
+        $pointer = new JsonPointer('/components/links');
+
+        return new Links($links, $pointer);
     }
 
     public function callbacks(): ?Callbacks
@@ -104,7 +121,9 @@ public function callbacks(): ?Callbacks
             return null;
         }
 
-        return new Callbacks($callbacks);
+        $pointer = new JsonPointer('/components/callbacks');
+
+        return new Callbacks($callbacks, $pointer);
     }
 
     public function pathItems(): ?Paths
@@ -115,6 +134,8 @@ public function pathItems(): ?Paths
             return null;
         }
 
-        return new Paths($pathItems);
+        $pointer = new JsonPointer('/components/pathItems');
+
+        return new Paths($pathItems, $pointer);
     }
 }

src/Structure/Contact.php

@@ -3,6 +3,7 @@
 namespace Apiboard\OpenAPI\Structure;
 
 use Apiboard\OpenAPI\Concerns\HasVendorExtensions;
+use Apiboard\OpenAPI\References\JsonPointer;
 
 final class Contact extends Structure
 {
@@ -22,4 +23,9 @@ public function email(): string
     {
         return $this->data['email'];
     }
+
+    public function pointer(): ?JsonPointer
+    {
+        return new JsonPointer('/info/contact');
+    }
 }

src/Structure/Document.php

@@ -5,6 +5,7 @@
 use Apiboard\OpenAPI\Concerns\HasVendorExtensions;
 use Apiboard\OpenAPI\Contents\Json;
 use Apiboard\OpenAPI\Contents\Yaml;
+use Apiboard\OpenAPI\References\JsonPointer;
 use Stringable;
 
 final class Document extends Structure implements Stringable
@@ -41,7 +42,9 @@ public function info(): Info
 
     public function paths(): Paths
     {
-        return new Paths($this->data['paths']);
+        $pointer = new JsonPointer('/paths');
+
+        return new Paths($this->data['paths'], $pointer);
     }
 
     public function servers(): ?Servers
@@ -52,7 +55,9 @@ public function servers(): ?Servers
             return null;
         }
 
-        return new Servers($servers);
+        $pointer = new JsonPointer('/servers');
+
+        return new Servers($servers, $pointer);
     }
 
     public function components(): ?Components
@@ -63,7 +68,9 @@ public function components(): ?Components
             return null;
         }
 
-        return new Components($components);
+        $pointer = new JsonPointer('/components');
+
+        return new Components($components, $pointer);
     }
 
     public function security(): ?Security
@@ -74,7 +81,9 @@ public function security(): ?Security
             return null;
         }
 
-        return new Security($security);
+        $pointer = new JsonPointer('/security');
+
+        return new Security($security, $pointer);
     }
 
     public function webhooks(): ?Webhooks
@@ -85,7 +94,9 @@ public function webhooks(): ?Webhooks
             return null;
         }
 
-        return new Webhooks($webhooks);
+        $pointer = new JsonPointer('/webhooks');
+
+        return new Webhooks($webhooks, $pointer);
     }
 
     public function tags(): ?Tags
@@ -96,6 +107,8 @@ public function tags(): ?Tags
             return null;
         }
 
-        return new Tags($tags);
+        $pointer = new JsonPointer('/tags');
+
+        return new Tags($tags, $pointer);
     }
 }

src/Structure/Examples.php

@@ -4,6 +4,7 @@
 
 use Apiboard\OpenAPI\Concerns\CanBeUsedAsArray;
 use Apiboard\OpenAPI\Concerns\HasReferences;
+use Apiboard\OpenAPI\References\JsonPointer;
 use Apiboard\OpenAPI\References\Reference;
 use ArrayAccess;
 use Countable;
@@ -14,16 +15,16 @@ final class Examples extends Structure implements ArrayAccess, Countable, Iterat
     use CanBeUsedAsArray;
     use HasReferences;
 
-    public function __construct(array $data)
+    public function __construct(array $data, JsonPointer $pointer = null)
     {
         foreach ($data as $key => $value) {
             $data[$key] = match ($this->isReference($value)) {
                 true => new Reference($value['$ref']),
-                default => new Example($value),
+                default => new Example($value, $pointer?->append($key)),
             };
         }
 
-        $this->data = $data;
+        parent::__construct($data, $pointer);
     }
 
     public function offsetGet(mixed $offset): Example|Reference|null

src/Structure/Header.php

@@ -7,6 +7,7 @@
 use Apiboard\OpenAPI\Concerns\CanBeRequired;
 use Apiboard\OpenAPI\Concerns\HasASchema;
 use Apiboard\OpenAPI\Concerns\HasVendorExtensions;
+use Apiboard\OpenAPI\References\JsonPointer;
 
 final class Header extends Structure
 {
@@ -18,10 +19,10 @@ final class Header extends Structure
 
     private string $name;
 
-    public function __construct(string $name, array $data)
+    public function __construct(string $name, array $data, JsonPointer $pointer = null)
     {
         $this->name = $name;
-        $this->data = $data;
+        parent::__construct($data, $pointer);
     }
 
     public function name(): string

src/Structure/Headers.php

@@ -4,6 +4,7 @@
 
 use Apiboard\OpenAPI\Concerns\CanBeUsedAsArray;
 use Apiboard\OpenAPI\Concerns\HasReferences;
+use Apiboard\OpenAPI\References\JsonPointer;
 use Apiboard\OpenAPI\References\Reference;
 use ArrayAccess;
 use Countable;
@@ -14,16 +15,16 @@ final class Headers extends Structure implements ArrayAccess, Countable, Iterato
     use CanBeUsedAsArray;
     use HasReferences;
 
-    public function __construct(array $data)
+    public function __construct(array $data, JsonPointer $pointer = null)
     {
         foreach ($data as $name => $value) {
             $data[$name] = match ($this->isReference($value)) {
                 true => new Reference($value['$ref']),
-                default => new Header($name, $value),
+                default => new Header($name, $value, $pointer?->append($name)),
             };
         }
 
-        $this->data = $data;
+        parent::__construct($data, $pointer);
     }
 
     public function offsetGet(mixed $name): Header|Reference|null

src/Structure/Info.php

@@ -4,6 +4,7 @@
 
 use Apiboard\OpenAPI\Concerns\CanBeDescribed;
 use Apiboard\OpenAPI\Concerns\HasVendorExtensions;
+use Apiboard\OpenAPI\References\JsonPointer;
 
 final class Info extends Structure
 {
@@ -46,4 +47,9 @@ public function contact(): ?Contact
 
         return new Contact($contact);
     }
+
+    public function pointer(): ?JsonPointer
+    {
+        return new JsonPointer('/info');
+    }
 }