rspec-openapi 0.25.0 → 0.26.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 65e97b91c81a4798c7907d907174d8c7efe874ad26dd3d630db2c86db97f913d
-  data.tar.gz: a593eaf58214a7bc5578f3cee065d263d7b494507727ac05c60111d01b0a2a7d
+  metadata.gz: 254e5e91a3965a417ad69c8b61d4bfdde6af42ab7aba14854d5531d73f4a793d
+  data.tar.gz: 3fa43709cf02b95bb1f4815eb4eebefde3ad5e5e2aabf0439267dce2c06cba36
 SHA512:
-  metadata.gz: 3e88fae82f5452b748d2ade83adc141fff0e888946c48ec3219999012bd75a7162e678d89af1e1ccb584e14250739715e0ffd53ec1b1ff101080ca2abd44ba82
-  data.tar.gz: e49fdd879b02d43fe0f8ac4ef2d443b7a0366c5f133d5012f771be380c706b9fa28597f6bd6e6e111bee599bee26e5ae71f8dec262e4bf6070c679790e42d654
+  metadata.gz: 486180ee4a5b04de2f3539864e6f5be519ea262f0b30afc661377aa2da69c9c6fba883128ff02c006a9b073766848fc8b2ef5ad99cbb2fc55f8201de1a5975de
+  data.tar.gz: a074396a8847d7d9950fc414591e68da5c1def3121fdae896aa6e626e512c5860dc58b5be83248979bb6612628f224d367d066a8d5939991fbe98f8000626934

data/.github/workflows/create_release.yml

@@ -4,7 +4,7 @@ on:
   workflow_dispatch:
     inputs:
       version:
-        description: 'Version to release (e.g. 0.25.1 or 0.26.0)'
+        description: 'Version to release (e.g. 0.26.1 or 0.27.0)'
         required: true
 
 jobs:

data/.github/workflows/publish.yml

@@ -39,7 +39,7 @@ jobs:
       - uses: rubygems/release-gem@v1
 
       - name: Create GitHub release
-        uses: softprops/action-gh-release@v2
+        uses: softprops/action-gh-release@v3
         with:
           tag_name: ${{ github.ref_name }}
           name: ${{ github.ref_name }}

data/.github/workflows/test.yml

@@ -42,7 +42,7 @@ jobs:
       - run: git config --global --add safe.directory "$GITHUB_WORKSPACE"
         name: codecov-action@v4 workaround
       - name: Upload coverage reports
-        uses: codecov/codecov-action@v5
+        uses: codecov/codecov-action@v6
         if: matrix.coverage == 'coverage'
         with:
           fail_ci_if_error: true

data/.github/workflows/validate-openapi.yml

@@ -0,0 +1,21 @@
+name: validate-openapi
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    types:
+      - opened
+      - synchronize
+      - reopened
+
+jobs:
+  redocly-lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+      - run: npx --yes @redocly/cli@2.30.4 lint

data/.gitignore

@@ -14,3 +14,5 @@
 .rspec_status
 
 spec/apps/rails/log/
+
+/mise.toml

data/.rubocop_todo.yml

@@ -24,7 +24,7 @@ Metrics/CyclomaticComplexity:
 # Offense count: 22
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
-  Max: 36
+  Max: 37
 
 # Offense count: 5
 # Configuration parameters: AllowedMethods, AllowedPatterns.

data/README.md

@@ -1,6 +1,5 @@
 # rspec-openapi [![Gem Version](https://badge.fury.io/rb/rspec-openapi.svg)](https://rubygems.org/gems/rspec-openapi) [![test](https://github.com/exoego/rspec-openapi/actions/workflows/test.yml/badge.svg)](https://github.com/exoego/rspec-openapi/actions/workflows/test.yml) [![codecov](https://codecov.io/gh/exoego/rspec-openapi/branch/master/graph/badge.svg?token=egYm6AlxkD)](https://codecov.io/gh/exoego/rspec-openapi) [![Ruby-toolbox](https://img.shields.io/badge/ruby-toolbox-a61414?cacheSeconds=31536000)](https://www.ruby-toolbox.com/projects/rspec-openapi) [![DeepWiki](https://img.shields.io/badge/See_on-DeepWiki-blue)](https://deepwiki.com/exoego/rspec-openapi)
 
-
 Generate OpenAPI schema from RSpec request specs.
 
 ## What's this?
@@ -8,7 +7,8 @@ Generate OpenAPI schema from RSpec request specs.
 There are some gems which generate OpenAPI specs from RSpec request specs.
 However, they require a special DSL specific to these gems, and we can't reuse existing request specs as they are.
 
-Unlike such [existing gems](#links), rspec-openapi can generate OpenAPI specs from request specs without requiring any special DSL.
+Unlike such [existing gems](#links), rspec-openapi can generate OpenAPI specs from request specs without requiring any
+special DSL.
 Furthermore, rspec-openapi keeps manual modifications when it merges automated changes to OpenAPI specs
 in case we can't generate everything from request specs.
 
@@ -30,7 +30,9 @@ $ OPENAPI=1 bundle exec rspec
 
 ### Example
 
-Let's say you have [a request spec](https://github.com/exoego/rspec-openapi/blob/24e5c567c2e90945c7a41f19f71634ac028cc314/spec/requests/rails_spec.rb#L38) like this:
+Let's say you
+have [a request spec](https://github.com/exoego/rspec-openapi/blob/24e5c567c2e90945c7a41f19f71634ac028cc314/spec/requests/rails_spec.rb#L38)
+like this:
 
 ```rb
 RSpec.describe 'Tables', type: :request do
@@ -67,18 +69,18 @@ paths:
     get:
       summary: index
       tags:
-      - Table
+        - Table
       parameters:
-      - name: page
-        in: query
-        schema:
-          type: integer
-        example: 1
-      - name: per
-        in: query
-        schema:
-          type: integer
-        example: 10
+        - name: page
+          in: query
+          schema:
+            type: integer
+          example: 1
+        - name: per
+          in: query
+          schema:
+            type: integer
+          example: 10
       responses:
         '200':
           description: returns a list of tables
@@ -96,11 +98,11 @@ paths:
                     # ...
 ```
 
-and the schema file can be used as an input of [Swagger UI](https://github.com/swagger-api/swagger-ui) or [Redoc](https://github.com/Redocly/redoc).
+and the schema file can be used as an input of [Swagger UI](https://github.com/swagger-api/swagger-ui)
+or [Redoc](https://github.com/Redocly/redoc).
 
 ![Redoc example](./spec/apps/rails/doc/screenshot.png)
 
-
 ### Configuration
 
 The following configurations are optional.
@@ -251,7 +253,8 @@ paths:
 # Note) #/components/schemas is not needed to be defined.
 ```
 
-3. Then, re-run rspec-openapi. It will generate `#/components/schemas` with the referenced schema (`User` for example) newly-generated or updated.
+3. Then, re-run rspec-openapi. It will generate `#/components/schemas` with the referenced schema (`User` for example)
+   newly-generated or updated.
 
 ```yaml
 paths:
@@ -354,21 +357,22 @@ Some examples' attributes can be overwritten via RSpec metadata options. Example
 
 ```rb
   describe 'GET /api/v1/posts', openapi: {
-    summary: 'list all posts',
-    description: 'list all posts ordered by pub_date',
-    tags: %w[v1 posts],
-    required_request_params: %w[limit],
-    security: [{"MyToken" => []}],
-  } do
-    # ...
-  end
+  summary: 'list all posts',
+  description: 'list all posts ordered by pub_date',
+  tags: %w[v1 posts],
+  required_request_params: %w[limit],
+  security: [{ "MyToken" => [] }],
+} do
+  # ...
+end
 ```
 
 **NOTE**: `description` key will override also the one provided by `RSpec::OpenAPI.description_builder` method.
 
 ### Enum Support
 
-You can specify enum values for string properties that should have a fixed set of allowed values. Since enums cannot be reliably inferred from test data, you can define them via the `enum` metadata option:
+You can specify enum values for string properties that should have a fixed set of allowed values. Since enums cannot be
+reliably inferred from test data, you can define them via the `enum` metadata option:
 
 ```rb
 it 'returns user status', openapi: {
@@ -431,7 +435,8 @@ end
 
 #### Request vs Response Enums
 
-By default, `enum` applies to both request and response bodies. If you need different enum values for request and response, use `request_enum` and `response_enum`:
+By default, `enum` applies to both request and response bodies. If you need different enum values for request and
+response, use `request_enum` and `response_enum`:
 
 ```rb
 it 'creates a task', openapi: {
@@ -447,6 +452,173 @@ it 'creates a task', openapi: {
 end
 ```
 
+### Dynamic-key Object Support (`additionalProperties`)
+
+When an endpoint returns (or accepts) an object whose keys are not part of its
+schema — for example a permissions map `{ "can_edit": true, "can_delete": false }`
+where new permissions can appear without an API change — rspec-openapi would
+otherwise capture the test response literally and emit each observed key as a
+fixed property. You can override this with the `additional_properties` metadata,
+which replaces the captured `properties` / `required` of the matched object with
+[`additionalProperties`](https://swagger.io/docs/specification/data-models/dictionaries/).
+
+Keys are dot-notation paths (the same scheme as `enum`); the empty string `''`
+targets the body root.
+
+```rb
+it 'returns a permission map', openapi: {
+  additional_properties: { 'data' => { type: 'boolean' } },
+} do
+  get '/api/v1/permissions'
+  # Response: { "data": { "can_edit": true, "can_delete": false } }
+  expect(response.status).to eq(200)
+end
+```
+
+This generates:
+
+```yaml
+schema:
+  type: object
+  properties:
+    data:
+      type: object
+      additionalProperties:
+        type: boolean
+  required:
+    - data
+```
+
+#### Root-level dynamic keys
+
+When the entire body is a dynamic dict, use `''` as the path:
+
+```rb
+it 'lists organisation memberships', openapi: {
+  additional_properties: { '' => { type: 'boolean' } },
+} do
+  get '/api/v1/organisations/acme/check_memberships'
+  # Response: { "user-hash-a": true, "user-hash-b": false }
+  expect(response.status).to eq(200)
+end
+```
+
+```yaml
+schema:
+  type: object
+  additionalProperties:
+    type: boolean
+```
+
+#### Schemas referenced via `$ref`
+
+The value of `additionalProperties` can be any schema, including a `$ref`:
+
+```rb
+it 'returns tags by id', openapi: {
+  additional_properties: { '' => { '$ref' => '#/components/schemas/Tag' } },
+} do
+  get '/tags'
+  expect(response.status).to eq(200)
+end
+```
+
+```yaml
+schema:
+  type: object
+  additionalProperties:
+    $ref: '#/components/schemas/Tag'
+```
+
+#### Request vs Response
+
+`additional_properties` applies to both request and response by default. Use
+`request_additional_properties` / `response_additional_properties` to scope to
+one side:
+
+```rb
+it 'records arbitrary metrics', openapi: {
+  request_additional_properties: { '' => { type: 'integer' } },
+} do
+  post '/metrics', params: { 'page_views' => 100, 'signups' => 5 }
+  expect(response.status).to eq(201)
+end
+```
+
+#### Forbidding extras with `false` (or `true`)
+
+Attaching `additionalProperties: false` forbid dynamic keys while `: true` (default)
+explicitly allow those.
+This is useful mostly for the `false` case, to prevent unexpected extras:
+
+```rb
+it 'returns a closed object', openapi: {
+  additional_properties: { '' => false },
+} do
+  get '/api/v1/profile'
+  # Response: { "id": 1, "name": "alice" }
+  expect(response.status).to eq(200)
+end
+```
+
+```yaml
+schema:
+  type: object
+  properties:
+    id: { type: integer }
+    name: { type: string }
+  required: [ id, name ]
+  additionalProperties: false
+```
+
+#### Hybrid objects (known keys + dynamic keys)
+
+When an object has both a fixed shape and dynamic keys, use `hybrid_additional_properties`
+(`request_hybrid_additional_properties` and `response_hybrid_additional_properties` to scope
+to one side). Captured properties stay; the supplied schema is attached as `additionalProperties`.
+
+At the root (whole body is the hybrid object):
+
+```rb
+it 'returns an item with custom attributes', openapi: {
+  hybrid_additional_properties: { '' => { type: 'string' } },
+} do
+  get '/api/v1/items/42'
+  # Response: { "id": 42, "attr_color": "red", "attr_size": "large" }
+  expect(response.status).to eq(200)
+end
+```
+
+```yaml
+schema:
+  type: object
+  properties:
+    id: { type: integer }
+    attr_color: { type: string }
+    attr_size: { type: string }
+  required: [ id, attr_color, attr_size ]
+  additionalProperties:
+    type: string
+```
+
+#### Notes on behavior
+
+- A hash schema in `additional_properties` fully replaces the captured
+  `properties` / `required` at the matched node. To keep observed properties
+  alongside `additionalProperties`, use `hybrid_additional_properties` or pass
+  a boolean.
+- Recursion stops once `additional_properties` matches a path with a hash
+  schema: nested overrides underneath (e.g. setting both `'data'` and
+  `'data.meta'`) won't be applied, because the supplied dictionary value
+  schema describes every child uniformly and isn't traversed further.
+  `hybrid_additional_properties` keeps observed properties so children are
+  still walked normally.
+- When migrating an existing schema (one previously generated with concrete
+  `properties` / `required`) by adding this metadata, the next regeneration
+  prunes the stale `properties` / `required` automatically. If you had
+  manually added `additionalProperties` to an object that also has
+  `properties`, that hybrid shape is preserved.
+
 ### Multiple Examples Mode
 
 You can generate multiple named examples for the same endpoint using `example_mode`:
@@ -480,23 +652,144 @@ responses:
             value: { ... }
 ```
 
+
 Available `example_mode` values:
+
 - `:single` (default) - generates single `example` field
 - `:multiple` - generates named `examples` with test descriptions as keys
 - `:none` - generates only schema, no examples
 
+`example_mode` also accepts a hash form so you can configure the request body and the response independently:
+
+```rb
+describe 'POST /sign_in', openapi: { example_mode: { request: :multiple, response: :multiple } } do
+  ...
+end
+```
+
+Missing keys default to `:single`, so `{ example_mode: { request: :multiple } }` keeps the response on `:single`.
+
+The bare symbol form maps as follows:
+
+| `example_mode` value                          | request side | response side |
+|-----------------------------------------------|--------------|---------------|
+| `:single` (default)                           | `:single`    | `:single`     |
+| `:none`                                       | `:none`      | `:none`       |
+| `:multiple`                                   | `:single` ⚠️ | `:multiple`   |
+| `{ request: :multiple, response: :multiple }` | `:multiple`  | `:multiple`   |
+
+⚠️ The bare `:multiple` shorthand is currently **response-only** to preserve the behavior that existed before
+request-side multi-examples were introduced. A future major release will change it to mean
+`{ request: :multiple, response: :multiple }`.
+
 The mode is inherited by nested contexts and can be overridden at any level.
 
 **Note:** If multiple examples resolve to the same example key for a single endpoint, the last one wins (overwrites).
 
+#### Request Body Multiple Examples
+
+With `example_mode: { request: :multiple }`, the generator produces named `examples:` for `requestBody`.
+This is useful when the same endpoint accepts mutually exclusive request shapes (e.g. OTP vs email/password sign-in),
+where merging them into a single `example:` would produce a nonsensical mixed payload.
+
+```rb
+describe 'POST /sign_in',
+         openapi: { example_mode: { request: :multiple, response: :multiple } } do
+  it 'with otp' do
+    post '/sign_in',
+         params: { auth_type: 'otp', otp: '123456' }.to_json,
+         headers: { 'CONTENT_TYPE' => 'application/json' }
+    expect(response.status).to eq(200)
+  end
+
+  it 'with email password' do
+    post '/sign_in',
+         params: { auth_type: 'email', email: 'a@b.c', password: 'pw' }.to_json,
+         headers: { 'CONTENT_TYPE' => 'application/json' }
+    expect(response.status).to eq(200)
+  end
+end
+```
+
+The generated `requestBody` keeps each shape as its own keyed example:
+
+```yaml
+requestBody:
+  content:
+    application/json:
+      schema:
+        type: object
+        properties:
+          auth_type: { type: string }
+          otp: { type: string }
+          email: { type: string }
+          password: { type: string }
+        required:
+          - auth_type
+      examples:
+        with_otp:
+          summary: with otp
+          value: { auth_type: otp, otp: '123456' }
+        with_email_password:
+          summary: with email password
+          value: { auth_type: email, email: a@b.c, password: pw }
+```
+
+The keys default to the test's description (normalized to lowercase + underscores).
+Override with `openapi: { example_key: 'custom_key', example_name: 'Custom Summary' }`,
+just like for response examples.
+
+##### Capturing 4xx requestBody examples
+
+When `request_example_mode` is `:single` (the default), tests with `status >= 400`
+are intentionally skipped for `requestBody` so that error payloads don't pollute
+the request schema. When `request: :multiple` is set, this short-circuit is lifted:
+each failing test contributes its own keyed example, so you can document
+validation-failure shapes alongside success shapes:
+
+```rb
+describe 'POST /sign_in',
+         openapi: { example_mode: { request: :multiple, response: :multiple } } do
+  it 'with otp' do
+    post '/sign_in', params: { auth_type: 'otp', otp: '123456' }.to_json,
+         headers: { 'CONTENT_TYPE' => 'application/json' }
+    expect(response.status).to eq(200)
+  end
+
+  it 'with missing fields' do
+    post '/sign_in', params: { auth_type: 'email' }.to_json,
+         headers: { 'CONTENT_TYPE' => 'application/json' }
+    expect(response.status).to eq(400)
+  end
+end
+```
+
+```yaml
+requestBody:
+  content:
+    application/json:
+      examples:
+        with_otp: { summary: with otp, value: { ... } }
+        with_missing_fields: { summary: with missing fields, value: { ... } }
+responses:
+  '200': { ... }
+  '400': { ... }
+```
+
+Mixing `:single` (some tests) with `:multiple` (others) on the same endpoint also works for `requestBody` - 
+the merger up-converts the singular `example:` into the `examples:` map automatically
+(see [Merge Behavior with Mixed Modes](#merge-behavior-with-mixed-modes) below).
+
 #### Merge Behavior with Mixed Modes
 
-When multiple tests target the same endpoint with different `example_mode` settings (even from different spec files), the merger automatically converts to `examples` format:
+When multiple tests target the same endpoint with different `example_mode` settings (even from different spec files),
+the merger automatically converts to `examples` format:
 
 ```rb
 # spec/requests/api_spec.rb
 describe 'GET /users' do
-  it 'returns users' do  # default :single mode
+  it 'returns users' do
+    # default :single mode
     get '/users'
     expect(response.status).to eq(200)
   end
@@ -512,6 +805,7 @@ end
 ```
 
 Result - both examples merged into `examples`:
+
 ```yaml
 responses:
   '200':
@@ -541,6 +835,7 @@ Even if you are not using `rspec` this gem might help you with its experimental
 Example:
 
 ```rb
+
 class TablesTest < ActionDispatch::IntegrationTest
   openapi!
 
@@ -558,9 +853,11 @@ class TablesTest < ActionDispatch::IntegrationTest
 end
 ```
 
-It should work with both classes inheriting from `ActionDispatch::IntegrationTest` and with classes using `Rack::Test` directly, as long as you call `openapi!` in your test class.
+It should work with both classes inheriting from `ActionDispatch::IntegrationTest` and with classes using `Rack::Test`
+directly, as long as you call `openapi!` in your test class.
 
-Please note that not all features present in the rspec integration work with minitest (yet). For example, custom per test case metadata is not supported. A custom `description_builder` will not work either.
+Please note that not all features present in the rspec integration work with minitest (yet). For example, custom per
+test case metadata is not supported. A custom `description_builder` will not work either.
 
 Run minitest with OPENAPI=1 to generate `doc/openapi.yaml` for your request specs.
 
@@ -579,15 +876,19 @@ Existing RSpec plugins which have OpenAPI integration:
 ## Acknowledgements
 
 * Heavily inspired by [r7kamura/autodoc](https://github.com/r7kamura/autodoc)
-* Orignally created by [k0kubun](https://github.com/k0kubun) and the ownership was transferred to [exoego](https://github.com/exoego) in 2022-11-29.
-
+* Orignally created by [k0kubun](https://github.com/k0kubun) and the ownership was transferred
+  to [exoego](https://github.com/exoego) in 2022-11-29.
 
 ## Releasing
 
-1. Ensure RubyGems trusted publishing is configured for this repo and gem ownership (see [Trusted publishing](https://guides.rubygems.org/trusted-publishing/)).
-2. In GitHub Actions, run the `prepare release` workflow manually. It bumps `lib/rspec/openapi/version.rb`, pushes `release/v<version>` to origin, and opens a PR.
+1. Ensure RubyGems trusted publishing is configured for this repo and gem ownership (
+   see [Trusted publishing](https://guides.rubygems.org/trusted-publishing/)).
+2. In GitHub Actions, run the `prepare release` workflow manually. It bumps `lib/rspec/openapi/version.rb`, pushes
+   `release/v<version>` to origin, and opens a PR.
 3. Review and merge the release PR into the default branch.
-4. Create and push a tag `v<version>` on the merged commit (via the GitHub UI or `git tag v<version>; git push origin v<version>`). Tag creation triggers the `Publish to RubyGems` workflow, which publishes the gem and creates the GitHub release notes automatically.
+4. Create and push a tag `v<version>` on the merged commit (via the GitHub UI or
+   `git tag v<version>; git push origin v<version>`). Tag creation triggers the `Publish to RubyGems` workflow, which
+   publishes the gem and creates the GitHub release notes automatically.
 
 ## License
 

data/lib/rspec/openapi/components_updater.rb

@@ -3,6 +3,8 @@
 require_relative 'hash_helper'
 
 class << RSpec::OpenAPI::ComponentsUpdater = Object.new
+  SCHEMA_REF_PREFIX = '#/components/schemas/'
+
   # @param [Hash] base
   # @param [Hash] fresh
   def update!(base, fresh)
@@ -30,7 +32,7 @@ class << RSpec::OpenAPI::ComponentsUpdater = Object.new
       # Skip if the property using $ref is not found in the parent schema. The property may be removed.
       next if nested_schema.nil?
 
-      schema_name = base.dig(*paths)&.gsub('#/components/schemas/', '')&.to_sym
+      schema_name = extract_schema_name(base.dig(*paths))&.to_sym
       fresh_schemas[schema_name] ||= {}
       RSpec::OpenAPI::SchemaMerger.merge!(fresh_schemas[schema_name], nested_schema)
     end
@@ -44,8 +46,8 @@ class << RSpec::OpenAPI::ComponentsUpdater = Object.new
   def build_fresh_schemas(references, base, fresh)
     references.inject({}) do |acc, paths|
       ref_link = dig_schema(base, paths)[:$ref]
-      schema_name = ref_link.to_s.gsub('#/components/schemas/', '')
-      schema_body = dig_schema(fresh, paths.reject { |path| path.is_a?(Integer) })
+      schema_name = extract_schema_name(ref_link)
+      schema_body = dig_schema(fresh, paths.grep_v(Integer))
 
       RSpec::OpenAPI::SchemaMerger.merge!(acc, { schema_name => schema_body })
     end
@@ -81,18 +83,29 @@ class << RSpec::OpenAPI::ComponentsUpdater = Object.new
     # Reject already-generated schemas to reduce unnecessary loop
     nested_refs.reject do |paths|
       ref_link = base.dig(*paths)
-      schema_name = ref_link.gsub('#/components/schemas/', '')
+      schema_name = extract_schema_name(ref_link)
       generated_names.include?(schema_name)
     end
   end
 
   def find_one_of_refs(base, paths)
-    dig_schema(base, paths)&.dig(:oneOf)&.map&.with_index do |schema, index|
-      paths + [index] if schema&.dig(:$ref)&.start_with?('#/components/schemas/')
-    end&.compact
+    one_of = dig_schema(base, paths)&.dig(:oneOf)
+    return unless one_of
+
+    one_of.each_with_index.filter_map do |schema, index|
+      paths + [index] if schema_ref?(schema&.dig(:$ref))
+    end
   end
 
   def find_object_refs(base, paths)
-    [paths] if dig_schema(base, paths)&.dig(:$ref)&.start_with?('#/components/schemas/')
+    [paths] if schema_ref?(dig_schema(base, paths)&.dig(:$ref))
+  end
+
+  def extract_schema_name(ref_link)
+    ref_link&.delete_prefix(SCHEMA_REF_PREFIX)
+  end
+
+  def schema_ref?(ref_link)
+    ref_link&.start_with?(SCHEMA_REF_PREFIX)
   end
 end