Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

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

Đã đóng
  • Có gì không ổn?
#237 1 bình luận 0 reaction 0 người được giao Xem trên GitHub

Chưa có ai nhận issue này.

Đánh giá

Độ khó
2/5
Thời gian dự kiến
1-3 giờ
Mức phù hợp với người mới
25/100
Loại issue
Lỗi
Độ rõ ràng
Đặc tả rõ ràng
Mức độ hoạt động
Đình trệ
Công nghệ
javascript, yaml
Lĩnh vực
cli, tooling

Hướng nghiên cứu

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.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

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
Ngôn ngữ chính
JavaScript
Star
178
Fork
29
Merge trung bình
2 giờ 20 phút
Pull request đã merge (30 ngày)
4

Chuẩn bị môi trường

  • Có Dockerfile hoặc tệp Docker Compose
  • Không có mẫu pull request
  • Không có hướng dẫn đóng góp

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của thim81/openapi-format

Tất cả issue của thim81/openapi-format

Issue tương tự

Thêm issue về JavaScript

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.