Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

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

Cerrado
  • ¿Algo no está bien?
#237 1 comentario 0 reacciones 0 asignados Ver en GitHub

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
2/5
Tiempo estimado
1-3 horas
Aptitud para principiantes
25/100
Tipo de issue
Error
Claridad
Bien especificado
Estado de actividad
Estancado
Stack tecnológico
javascript, yaml
Área
cli, tooling

Línea de trabajo

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.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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
Lenguaje dominante
JavaScript
Estrellas
178
Forks
29
Merge medio
2 h 20 min
PR fusionados (30 d)
4

Preparar el entorno

  • Incluye un Dockerfile o un archivo de Docker Compose
  • Sin plantilla de pull request
  • Sin guía de contribución

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de thim81/openapi-format

Todos los issues de thim81/openapi-format

Issues similares

Más issues de JavaScript

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.