Fix: Allow definitions/properties named 'enum' or 'const' during ref expansion #850

Copilot · 2025-11-03T18:53:12Z

The validator throws UnresolvableJsonPointerException when schemas contain definitions or properties named 'enum' or 'const' (common in OpenAPI specs). The code unconditionally skipped these properties during reference expansion, treating them as JSON Schema keywords rather than potentially valid property names.

Root Cause

SchemaStorage.php skipped ANY property named 'enum'/'const' in two locations:

expandRefs() line 104-107
scanForSubschemas() line 210-212

This prevented refs inside such definitions from being resolved.

Changes

Added isSchemaObject() helper to distinguish schema objects (with validation keywords) from pure containers (definitions, properties objects)
Modified skip condition: only skip 'enum'/'const' when parent is a schema object
Added SCHEMA_KEYWORDS constant containing 33 JSON Schema keywords organized by category

Example

This now works:

{
  "definitions": {
    "enum": {
      "$ref": "http://json-schema.org/draft-04/schema#/properties/enum"
    }
  }
}

While still correctly skipping actual keywords:

{
  "type": "string",
  "enum": ["red", "green", "blue"]
}

Testing

Added regression test testDefinitionNamedEnumIsResolved() covering both scenarios.

Fixes issue reported at https://github.com/mxr576/oas-validation-issue-on-v6

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

https://api.github.com/repos/FriendsOfPHP/PHP-CS-Fixer/zipball/0ad2f84130e8fec8655682532e6d39553054831c
- Triggering command: /usr/bin/php8.3 -n -c /tmp/Pc9DfP /usr/bin/composer install --no-interaction (http block)
https://api.github.com/repos/PHP-CS-Fixer/diff/zipball/29dc0d507e838c4580d018bd8b5cb412474f7ec3
- Triggering command: /usr/bin/php8.3 -n -c /tmp/Pc9DfP /usr/bin/composer install --no-interaction (http block)
https://api.github.com/repos/composer/pcre/zipball/67a32d7d6f9f560b726ab25a061b38ff3a80c560
- Triggering command: /usr/bin/php8.3 -n -c /tmp/jNDR7s /usr/bin/composer install (http block)
- Triggering command: /usr/bin/php8.3 -n -c /tmp/Pc9DfP /usr/bin/composer install --no-interaction (http block)
https://api.github.com/repos/composer/semver/zipball/198166618906cb2de69b95d7d47e5fa8aa1b2b95
- Triggering command: /usr/bin/php8.3 -n -c /tmp/Pc9DfP /usr/bin/composer install --no-interaction (http block)
https://api.github.com/repos/composer/xdebug-handler/zipball/9e36aeed4616366d2b690bdce11f71e9178c579a
- Triggering command: /usr/bin/php8.3 -n -c /tmp/Pc9DfP /usr/bin/composer install --no-interaction (http block)
https://api.github.com/repos/doctrine/annotations/zipball/253dca476f70808a5aeed3a47cc2cc88c5cab915
- Triggering command: /usr/bin/php8.3 -n -c /tmp/Pc9DfP /usr/bin/composer install --no-interaction (http block)
https://api.github.com/repos/doctrine/deprecations/zipball/459c2f5dd3d6a4633d3b5f46ee2b1c40f57d3f38
- Triggering command: /usr/bin/php8.3 -n -c /tmp/jNDR7s /usr/bin/composer install (http block)
- Triggering command: /usr/bin/php8.3 -n -c /tmp/Pc9DfP /usr/bin/composer install --no-interaction (http block)
https://api.github.com/repos/doctrine/lexer/zipball/861c870e8b75f7c8f69c146c7f89cc1c0f1b49b6
- Triggering command: /usr/bin/php8.3 -n -c /tmp/jNDR7s /usr/bin/composer install (http block)
- Triggering command: /usr/bin/php8.3 -n -c /tmp/Pc9DfP /usr/bin/composer install --no-interaction (http block)
https://api.github.com/repos/jsonrainbow/json-schema/zipball/68ba7677532803cc0c5900dd5a4d730537f2b2f3
- Triggering command: /usr/bin/php8.3 -n -c /tmp/c983hR /usr/bin/composer install (http block)
https://api.github.com/repos/marc-mabe/php-enum-phpstan/zipball/63d391c16e3a7753bb928f61d1989438ee63eebc
- Triggering command: /usr/bin/php8.3 -n -c /tmp/Pc9DfP /usr/bin/composer install --no-interaction (http block)
https://api.github.com/repos/marc-mabe/php-enum/zipball/bb426fcdd65c60fb3638ef741e8782508fda7eef
- Triggering command: /usr/bin/php8.3 -n -c /tmp/c983hR /usr/bin/composer install (http block)
- Triggering command: /usr/bin/php8.3 -n -c /tmp/Pc9DfP /usr/bin/composer install --no-interaction (http block)
https://api.github.com/repos/php-fig/cache/zipball/aa5030cfa5405eccfdcb1083ce040c2cb8d253bf
- Triggering command: /usr/bin/php8.3 -n -c /tmp/Pc9DfP /usr/bin/composer install --no-interaction (http block)
https://api.github.com/repos/php-fig/container/zipball/c71ecc56dfe541dbd90c5360474fbc405f8d5963
- Triggering command: /usr/bin/php8.3 -n -c /tmp/jNDR7s /usr/bin/composer install (http block)
- Triggering command: /usr/bin/php8.3 -n -c /tmp/Pc9DfP /usr/bin/composer install --no-interaction (http block)
https://api.github.com/repos/php-fig/event-dispatcher/zipball/dbefd12671e8a14ec7f180cab83036ed26714bb0
- Triggering command: /usr/bin/php8.3 -n -c /tmp/Pc9DfP /usr/bin/composer install --no-interaction (http block)
https://api.github.com/repos/php-fig/log/zipball/ef29f6d262798707a9edd554e2b82517ef3a9376
- Triggering command: /usr/bin/php8.3 -n -c /tmp/Pc9DfP /usr/bin/composer install --no-interaction (http block)
https://api.github.com/repos/phpDocumentor/ReflectionCommon/zipball/1d01c49d4ed62f25aa84a747ad35d5a16924662b
- Triggering command: /usr/bin/php8.3 -n -c /tmp/Pc9DfP /usr/bin/composer install --no-interaction (http block)
https://api.github.com/repos/phpDocumentor/TypeResolver/zipball/679e3ce485b99e84c775d28e2e96fade9a7fb50a
- Triggering command: /usr/bin/php8.3 -n -c /tmp/Pc9DfP /usr/bin/composer install --no-interaction (http block)
https://api.github.com/repos/phpstan/phpdoc-parser/zipball/1e0cd5370df5dd2e556a36b9c62f62e555870495
- Triggering command: /usr/bin/php8.3 -n -c /tmp/Pc9DfP /usr/bin/composer install --no-interaction (http block)
https://api.github.com/repos/phpstan/phpstan/zipball/2770dcdf5078d0b0d53f94317e06affe88419aa8
- Triggering command: /usr/bin/php8.3 -n -c /tmp/Pc9DfP /usr/bin/composer install --no-interaction (http block)
https://api.github.com/repos/sebastianbergmann/comparator/zipball/4b3c947888c81708b20fb081bb653a2ba68f989a
- Triggering command: /usr/bin/php8.3 -n -c /tmp/Pc9DfP /usr/bin/composer install --no-interaction (http block)
https://api.github.com/repos/sebastianbergmann/diff/zipball/98ff311ca519c3aa73ccd3de053bdb377171d7b6
- Triggering command: /usr/bin/php8.3 -n -c /tmp/Pc9DfP /usr/bin/composer install --no-interaction (http block)
https://api.github.com/repos/sebastianbergmann/exporter/zipball/64cfeaa341951ceb2019d7b98232399d57bb2296
- Triggering command: /usr/bin/php8.3 -n -c /tmp/Pc9DfP /usr/bin/composer install --no-interaction (http block)
https://api.github.com/repos/sebastianbergmann/recursion-context/zipball/8fe7e75986a9d24b4cceae847314035df7703a5a
- Triggering command: /usr/bin/php8.3 -n -c /tmp/Pc9DfP /usr/bin/composer install --no-interaction (http block)
https://api.github.com/repos/symfony/console/zipball/c4ba980ca61a9eb18ee6bcc73f28e475852bb1ed
- Triggering command: /usr/bin/php8.3 -n -c /tmp/Pc9DfP /usr/bin/composer install --no-interaction (http block)
https://api.github.com/repos/symfony/deprecation-contracts/zipball/63afe740e99a13ba87ec199bb07bbdee937a5b62
- Triggering command: /usr/bin/php8.3 -n -c /tmp/jNDR7s /usr/bin/composer install (http block)
- Triggering command: /usr/bin/php8.3 -n -c /tmp/c983hR /usr/bin/composer install (http block)
- Triggering command: /usr/bin/php8.3 -n -c /tmp/Pc9DfP /usr/bin/composer install --no-interaction (http block)
https://api.github.com/repos/symfony/event-dispatcher-contracts/zipball/59eb412e93815df44f05f342958efa9f46b1e586
- Triggering command: /usr/bin/php8.3 -n -c /tmp/Pc9DfP /usr/bin/composer install --no-interaction (http block)
https://api.github.com/repos/symfony/event-dispatcher/zipball/72982eb416f61003e9bb6e91f8b3213600dcf9e9
- Triggering command: /usr/bin/php8.3 -n -c /tmp/Pc9DfP /usr/bin/composer install --no-interaction (http block)
https://api.github.com/repos/symfony/filesystem/zipball/57c8294ed37d4a055b77057827c67f9558c95c54
- Triggering command: /usr/bin/php8.3 -n -c /tmp/Pc9DfP /usr/bin/composer install --no-interaction (http block)
https://api.github.com/repos/symfony/finder/zipball/63741784cd7b9967975eec610b256eed3ede022b
- Triggering command: /usr/bin/php8.3 -n -c /tmp/Pc9DfP /usr/bin/composer install --no-interaction (http block)
https://api.github.com/repos/symfony/options-resolver/zipball/74e5b6f0db3e8589e6cfd5efb317a1fc2bb52fb6
- Triggering command: /usr/bin/php8.3 -n -c /tmp/Pc9DfP /usr/bin/composer install --no-interaction (http block)
https://api.github.com/repos/symfony/polyfill-ctype/zipball/a3cc8b044a6ea513310cbd48ef7333b384945638
- Triggering command: /usr/bin/php8.3 -n -c /tmp/c983hR /usr/bin/composer install (http block)
- Triggering command: /usr/bin/php8.3 -n -c /tmp/Pc9DfP /usr/bin/composer install --no-interaction (http block)
https://api.github.com/repos/symfony/polyfill-intl-grapheme/zipball/380872130d3a5dd3ace2f4010d95125fde5d5c70
- Triggering command: /usr/bin/php8.3 -n -c /tmp/Pc9DfP /usr/bin/composer install --no-interaction (http block)
https://api.github.com/repos/symfony/polyfill-intl-normalizer/zipball/3833d7255cc303546435cb650316bff708a1c75c
- Triggering command: /usr/bin/php8.3 -n -c /tmp/Pc9DfP /usr/bin/composer install --no-interaction (http block)
https://api.github.com/repos/symfony/polyfill-mbstring/zipball/6d857f4d76bd4b343eac26d6b539585d2bc56493
- Triggering command: /usr/bin/php8.3 -n -c /tmp/Pc9DfP /usr/bin/composer install --no-interaction (http block)
https://api.github.com/repos/symfony/polyfill-php73/zipball/0f68c03565dcaaf25a890667542e8bd75fe7e5bb
- Triggering command: /usr/bin/php8.3 -n -c /tmp/Pc9DfP /usr/bin/composer install --no-interaction (http block)
https://api.github.com/repos/symfony/polyfill-php80/zipball/0cc9dd0f17f61d8131e7df6b84bd344899fe2608
- Triggering command: /usr/bin/php8.3 -n -c /tmp/jNDR7s /usr/bin/composer install (http block)
- Triggering command: /usr/bin/php8.3 -n -c /tmp/Pc9DfP /usr/bin/composer install --no-interaction (http block)
https://api.github.com/repos/symfony/polyfill-php81/zipball/4a4cfc2d253c21a5ad0e53071df248ed48c6ce5c
- Triggering command: /usr/bin/php8.3 -n -c /tmp/Pc9DfP /usr/bin/composer install --no-interaction (http block)
https://api.github.com/repos/symfony/process/zipball/5d1662fb32ebc94f17ddb8d635454a776066733d
- Triggering command: /usr/bin/php8.3 -n -c /tmp/Pc9DfP /usr/bin/composer install --no-interaction (http block)
https://api.github.com/repos/symfony/service-contracts/zipball/f021b05a130d35510bd6b25fe9053c2a8a15d5d4
- Triggering command: /usr/bin/php8.3 -n -c /tmp/jNDR7s /usr/bin/composer install (http block)
- Triggering command: /usr/bin/php8.3 -n -c /tmp/Pc9DfP /usr/bin/composer install --no-interaction (http block)
https://api.github.com/repos/symfony/stopwatch/zipball/fb2c199cf302eb207f8c23e7ee174c1c31a5c004
- Triggering command: /usr/bin/php8.3 -n -c /tmp/jNDR7s /usr/bin/composer install (http block)
- Triggering command: /usr/bin/php8.3 -n -c /tmp/Pc9DfP /usr/bin/composer install --no-interaction (http block)
https://api.github.com/repos/symfony/string/zipball/5621f039a71a11c87c106c1c598bdcd04a19aeea
- Triggering command: /usr/bin/php8.3 -n -c /tmp/Pc9DfP /usr/bin/composer install --no-interaction (http block)
https://api.github.com/repos/symfony/yaml/zipball/90208e2fc6f68f613eae7ca25a2458a931b1bacc
- Triggering command: /usr/bin/php8.3 -n -c /tmp/c983hR /usr/bin/composer install (http block)
https://api.github.com/repos/webmozarts/assert/zipball/9be6926d8b485f55b9229203f962b51ed377ba68
- Triggering command: /usr/bin/php8.3 -n -c /tmp/Pc9DfP /usr/bin/composer install --no-interaction (http block)

If you need me to access, download, or install something from one of these locations, you can either:

Configure Actions setup steps to set up my environment, which run before the firewall is enabled
Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

This section details on the original issue you should resolve

<issue_title>JsonSchema\Exception\UnresolvableJsonPointerException: Could not resolve fragment '#/definitions/enum': no file is define</issue_title>
<issue_description>I’m migrating a codebase from version 5 to version 6 that performs JSON Schema validation on OpenAPI specifications. After the upgrade, I’m consistently encountering the following error:
JsonSchema\Exception\UnresolvableJsonPointerException: Could not resolve fragment '#/definitions/enum': no file is defined
I’ve tried several approaches to resolve this issue but none have worked. I also reviewed how other large projects handled the v6 upgrade, such as [Composer’s migration](composer/composer@fc5a3dd), but found nothing that explains or resolves this behavior.

At this point, I’m unsure whether I’m missing something in the migration process or if this could be a genuine bug in the library. (It is Monday, so anything is possible 😶‍🌫️ )

Steps to reproduce:
https://github.com/mxr576/oas-validation-issue-on-v6

Expected behavior:
The schema should resolve references correctly without throwing an UnresolvableJsonPointerException.

Actual behavior:
The validator fails with the error above.
</issue_description>

<agent_instructions>The issue reporter is right. My comment contains a lot of additional info.

See if you can create a PR with minimal changes. The code added in #828 is there for a reason so don’t just delete it. </agent_instructions>

Comments on the Issue (you are @copilot in this section)
@DannyvdSluijs I've been doing some debugging and I've noticed something weird at https://github.com/jsonrainbow/json-schema/blob/main/src/JsonSchema/Constraints/ObjectConstraint.php#L134 as the fallback returns the undefined constraint and not a property or null when not found.
Although this might be a red-herring. Other references are resolved before to full url's such as http://swagger.io/v2/schema.json#/definitions/pathItem. Following this possibility leads me to https://github.com/jsonrainbow/json-schema/blob/main/src/JsonSchema/SchemaStorage.php#L104-L107 which was added in ac58d3f / #828 and reported in #827

Uncommenting these lines resolves the issue reported here. So perhaps that fix isn't complete. It was introduced in version 6.4.2. So Version 6.4.1 should not affect you ATM.

To conclude on the above: it looks like you’ve found a bug. Perhaps you want to create a PR? I’m rather busy at the moment making it difficult to commit to a date. If I find some time I’ll continue to have a look.

I’ll also give CoPilot a change to see if it can provide additional insights or even surprise us with a fix. </comment_new>

Fixes JsonSchema\Exception\UnresolvableJsonPointerException: Could not resolve fragment '#/definitions/enum': no file is define #849

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

Add conditional check to only skip enum/const when they are schema keywords, not property/definition names. This fixes the issue where definitions named 'enum' or 'const' were being skipped during ref expansion. Co-authored-by: DannyvdSluijs <618940+DannyvdSluijs@users.noreply.github.com>

Apply the same conditional check to scanForSubschemas to ensure consistency. This prevents definitions named 'enum' or 'const' from being skipped during subschema scanning. Co-authored-by: DannyvdSluijs <618940+DannyvdSluijs@users.noreply.github.com>

- Move schema keywords to class constant for better performance - Remove $ref from keywords list to avoid potential circular dependencies - Add documentation to constant Co-authored-by: DannyvdSluijs <618940+DannyvdSluijs@users.noreply.github.com>

- Update test comment with actual reproduction repo link - Add clarification about 'properties' keyword in SCHEMA_KEYWORDS - Improve documentation for better understanding Co-authored-by: DannyvdSluijs <618940+DannyvdSluijs@users.noreply.github.com>

Reorganize the schema keywords array into logical categories (core identifiers, type/structure, validation, composition, metadata) for better readability and maintainability. Co-authored-by: DannyvdSluijs <618940+DannyvdSluijs@users.noreply.github.com>

Add missing keywords for completeness: $comment, definitions, $defs, contains, if/then/else, readOnly, writeOnly. Note that enum and const are intentionally excluded as they are handled specially by this fix. Co-authored-by: DannyvdSluijs <618940+DannyvdSluijs@users.noreply.github.com>

mxr576 · 2025-11-04T16:10:28Z

Copilot, it seems you have work to do here.

DannyvdSluijs · 2025-11-05T21:20:43Z

Indeed Copilot didn't create the solution but it helpen me in understanding the issue at hand. Closing this PR as I've opened #851

Initial plan

5f291dc

Copilot AI assigned Copilot and DannyvdSluijs Nov 3, 2025

Copilot started work on behalf of DannyvdSluijs November 3, 2025 18:53 View session

Copilot AI and others added 6 commits November 3, 2025 19:15

Address code review feedback

68ceb58

- Move schema keywords to class constant for better performance - Remove $ref from keywords list to avoid potential circular dependencies - Add documentation to constant Co-authored-by: DannyvdSluijs <618940+DannyvdSluijs@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] Fix unresolvable JsonPointer exception during JSON Schema validation~~ Fix: Allow definitions/properties named 'enum' or 'const' during ref expansion Nov 3, 2025

Copilot AI requested a review from DannyvdSluijs November 3, 2025 19:30

Copilot finished work on behalf of DannyvdSluijs November 3, 2025 19:30

DannyvdSluijs closed this Nov 5, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Fix: Allow definitions/properties named 'enum' or 'const' during ref expansion #850

Fix: Allow definitions/properties named 'enum' or 'const' during ref expansion #850

Uh oh!

Copilot AI commented Nov 3, 2025 •

edited

Loading

Uh oh!

mxr576 commented Nov 4, 2025 •

edited

Loading

Uh oh!

DannyvdSluijs commented Nov 5, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Fix: Allow definitions/properties named 'enum' or 'const' during ref expansion #850

Fix: Allow definitions/properties named 'enum' or 'const' during ref expansion #850

Uh oh!

Conversation

Copilot AI commented Nov 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

I tried to connect to the following addresses, but was blocked by firewall rules:

Comments on the Issue (you are @copilot in this section)

Uh oh!

mxr576 commented Nov 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

DannyvdSluijs commented Nov 5, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Nov 3, 2025 •

edited

Loading

mxr576 commented Nov 4, 2025 •

edited

Loading