Hacktoberfest 2026：メンテナが10月に向けて印を付けた、オープンで初心者向けの issue。 Hacktoberfest の issue を見る

YAML output is silently replaced with `{}` when a schema property is literally named $ref

オープン
  • 何か問題がありますか？
#237 コメント 1 件 リアクション 0 件 担当者 0 名 GitHub で見る

まだ誰も着手していません。

評価

難易度
2/5
見積もり時間
1〜3時間
初心者へのやさしさ
25/100
issue の種類
バグ
明瞭さ
明確に書かれている
活発さ
停滞
技術スタック
javascript, yaml
領域
cli, tooling

調査の方向性

Read utils/file.js, especially addQuotesToRefInString(), and trace parseString() to understand how YAML errors become the formatted result. Review PR #236 and its tests first; done means the SCIM-style fixture preserves a literal $ref property, JSON References still format correctly, and the CLI no longer writes {} silently.

索引モデルが issue の本文から書いたものです。

説明

Description

openapi-format silently replaces the entire YAML output with {} when the input document contains a schema property literally named $ref. The command exits 0 with no error on stderr. This is a data-loss bug.

This affects specs that model SCIM resources (RFC 7643), where $ref is a standard field name on Group member objects.

Minimal reproduction

Create input.yaml:

openapi: 3.0.3
info:
  title: SCIM API
  version: 1.0.0
paths: {}
components:
  schemas:
    member:
      type: object
      properties:
        value:
          type: string
        "$ref":
          type: string
          format: uri
          description: The URI of the member resource.

Run:

openapi-format input.yaml -o output.yaml
cat output.yaml
# => {}

Expected behavior

The output should be the formatted OpenAPI document with the $ref property preserved:

openapi: 3.0.3
info:
  title: SCIM API
  version: 1.0.0
paths: {}
components:
  schemas:
    member:
      type: object
      properties:
        value:
          type: string
        $ref:
          description: The URI of the member resource.
          type: string
          format: uri

Actual behavior

The output file contains only {}. The CLI reports success.

Root cause

addQuotesToRefInString() in utils/file.js uses the regex:

/(\$ref:\s*)([^"'\s>]+)/g

The \s* quantifier includes \n, so when $ref: is a YAML mapping key (property name) with its value on the next line, the regex matches across the newline and wraps the following line's key in quotes:

# Before addQuotesToRefInString:
              $ref:
                description: The URI of the member resource.

# After addQuotesToRefInString:
              $ref:
                'description:' The URI of the member resource.

This produces invalid YAML. In >=1.33.6, the doc.errors.length > 0 check in parseString() returns a SyntaxError object instead of the parsed document. The caller treats this error object as the formatted result, which serializes to {}.

The bug was latent since addQuotesToRefInString was introduced but became fatal in 1.33.6 when the error check was added (3d1220f).

Suggested fix

Replace \s* with [ \t]* so the regex only matches horizontal whitespace. When $ref is used as a property name, the value is a block mapping on the next line, so the regex correctly skips it. When $ref is a JSON Reference, the value is on the same line and still gets quoted as intended.

I have a PR with the fix and tests: #236

Versions affected

  • Works correctly on 1.33.5 (bug was latent, errors silently ignored)
  • Produces {} on 1.33.6 and 1.33.7

Environment

  • openapi-format: 1.33.7
  • Node.js: 24.18.0
  • OS: macOS
主要言語
JavaScript
スター
177
フォーク
30
30日以内にマージされた PR はありません

環境構築

  • Dockerfile または Docker Compose ファイルあり
  • プルリクエストのテンプレートなし
  • コントリビューションガイドなし

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

thim81/openapi-format のほかの issue

thim81/openapi-format の issue をすべて見る

似ている issue

JavaScript の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。