>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3587673. --> Reported by: [penyaskito](https://www.drupal.org/user/959536) Related to !1012 >>> <h3 id="overview">Overview</h3> <p><em>Splitting from <a href="https://git.drupalcode.org/project/canvas/-/merge_requests/992/diffs#note_813491">https://git.drupalcode.org/project/canvas/-/merge_requests/992/diffs#note_813491</a></em></p> <p>Canvas-provided JSON Schema object refs (e.g. <code>json-schema-definitions://canvas.module/image</code>, <code>json-schema-definitions://canvas.module/video</code>) are repeated as raw string literals across PHP source, tests, and config schema. Today the same URI string is hand-typed in ~12 distinct ref values across 144 PHP occurrences, with no central definition. This makes typos undetectable until runtime, hides which call sites need to change when a ref is renamed, and obscures the set of "well-known" refs Canvas exposes.</p> <h3 id="proposed-resolution">Proposed resolution</h3> <p>Introduce <code>Drupal\canvas\JsonSchemaInterpreter\JsonSchemaObjectRef</code>, a string-backed PHP enum whose cases hold the canonical URI for each Canvas-provided object ref declared in <code>schema.json</code>. Refactor every PHP call site to reference an enum case instead of a string literal &mdash; both in production code (<code>JsonSchemaType::computeStorablePropShape()</code>, <code>ImageAdapter</code>, <code>ImageAndStyleAdapter</code>, <code>ShapeMatchingHooks::mediaLibraryStorablePropShapeAlter()</code>, &hellip;) and in tests.</p> <p>The enum exposes a <code>propShape()</code> helper returning the full <code>{type: object, $ref: &lt;URI&gt;</code> array, so existing shape-identity comparisons via <code>PropShape::normalizePropSchema()</code> need only minimal call-site changes.</p> <p>The scope is explicitly and only for those <code>type: object</code>: <code>Image</code> and <code>Video</code>. </p> <p>YAML config schema (<code>config/schema/canvas.json_schema.yml</code>) cannot reference the PHP enum as of today, so a comment pointing at the enum is sufficient there. In the future we might want to use the constants in yaml files too: <span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-14"><a href="https://www.drupal.org/project/drupal/issues/2951046" title="Status: Reviewed &amp; tested by the community">#2951046: Allow parsing and writing PHP class constants and enums in YAML files</a></span>.</p> <h3 id="remaining-tasks">Remaining tasks</h3> <ul> <li>Add the enum and the <code>propShape()</code> helper.</li> <li>Refactor every PHP call site (production + tests) to use enum cases.</li> <li>Add a @see comment in <code>config/schema/canvas.json_schema.yml</code>.</li> <li>Confirm no functional change via existing PHPUnit coverage.</li> </ul> <h3 id="ui-changes">User interface changes</h3> <p>None.</p> > Related issue: [Issue #3586613](https://www.drupal.org/node/3586613)