fix(openapi3): use escaped string literals in object values to prevent triple-quote syntax errors

[Copilot]

Extension properties containing multi-line strings (e.g., JSON examples with embedded triple-quotes) were converted using TypeSpec's triple-quoted string format, causing syntax errors when the content itself contained """.

Changes

• Added escapedStringLiteral() function in common.ts that always uses single-line format with proper escaping of newlines, quotes, backslashes, and template literal syntax
• Updated normalizeObjectValueToTSValueExpression() in decorators.ts to use escaped literals for all string values in object literals instead of auto-selecting triple-quoted format

Example

Given an OpenAPI extension with JSON content containing Python docstrings:

x-oaiMeta:
  example: |
    {
      "source": """
    def grade():
        """Returns 1.0"""
        return 1.0
    """,
    }

Before: Invalid syntax with nested triple-quotes

example: """
{
  "source": """
def grade():

After: Valid escaped string literal

example: "{\n  \"source\": \"\"\"\ndef grade():\n    \"\"\"Returns 1.0\"\"\"\n    return 1.0\n\"\"\",\n}\n"

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• telemetry.astro.build
  • Triggering command: /usr/local/bin/node node /home/REDACTED/work/typespec/typespec/website/node_modules/.bin/../astro/astro.js build sh nts/�� ebsite/src/content/docs/docs/emitters/openapi3/reference node /.bin/sh -p . ents/reference node js lmstxt --output-dir ../../websit--output-dir node (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Bug]: import - json in a string property is being interpreted as JSON</issue_title>
<issue_description>### Describe the bug

#9228 introduced a regression.

The following description leads to this invalid TypeSpec definition after being imported.

@extension("x-oaiMeta", #{name: "Python Grader", group: "graders", example: """
{
  "type": "python",
  "name": "Example python grader",
  "image_tag": "2025-05-08",
  "source": """
def grade(sample: dict, item: dict) -> float:
    \"""
    Returns 1.0 if `output_text` equals `label`, otherwise 0.0.
    \"""
    output = sample.get("output_text")
    label = item.get("label")
    return 1.0 if output == label else 0.0
""",
}

When in fact it should result in the following.

@extension(
  "x-oaiMeta",
  #{
    name: "Python Grader",
    group: "graders",
    example: "{\n  \"type\": \"python\",\n  \"name\": \"Example python grader\",\n  \"image_tag\": \"2025-05-08\",\n  \"source\": \"\"\"\ndef grade(sample: dict, item: dict) -> float:\n    \\\"\"\"\n    Returns 1.0 if `output_text` equals `label`, otherwise 0.0.\n    \\\"\"\"\n    output = sample.get(\"output_text\")\n    label = item.get(\"label\")\n    return 1.0 if output == label else 0.0\n\"\"\",\n}\n",
  }
)

Reproduction

components:
  schemas:
    GraderPython:
      x-oaiMeta:
        name: Python Grader
        group: graders
        example: |
          {
            "type": "python",
            "name": "Example python grader",
            "image_tag": "2025-05-08",
            "source": """
          def grade(sample: dict, item: dict) -> float:
              \"""
              Returns 1.0 if `output_text` equals `label`, otherwise 0.0.
              \"""
              output = sample.get("output_text")
              label = item.get("label")
              return 1.0 if output == label else 0.0
          """,
          }

Here the example property in the extension should be considered a literal string, and not JSON that needs to be parsed.

Checklist

• Follow our Code of Conduct
• Check that there isn't already an issue that request the same bug to avoid creating a duplicate.
• Check that this is a concrete bug. For Q&A open a GitHub Discussion.
• The provided reproduction is a minimal reproducible example of the bug.</issue_description>

<agent_instructions>use conventional commits.
before each commit, run the formatting command.
when you're done, run npx @chronus/chronus add to add a bugfix entry to the changelog.
start by defining the unit tests first.</agent_instructions>

Comments on the Issue (you are @copilot in this section)

• Fixes [Bug]: import - json in a string property is being interpreted as JSON #9235

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/microsoft/typespec/@typespec/openapi@9236

npm i https://pkg.pr.new/microsoft/typespec/@typespec/openapi3@9236

commit: 86f17e7

[timotheeguerin]

what is the difference with the function above?

[baywet]

this method accounts for backslashes, additional "blankspace characters" (t, r).
Even though copilot made this change, I didn't "nudge" it to change the function above because I was worried that it would have a larger impact than anticipated. Happy to refactor.

Another thing we'd need to fix for is the presence of triple double quotes """ in the string literal (in the original method)

[baywet]

I just pushed changes to the main method, let me know if you need me to change anything else.

[github-actions]

All changed packages have been documented.

• ✅ @typespec/openapi3

Show changes

@typespec/openapi3 - fix ✏️

Fix extension properties with JSON-like strings using escaped string literals to prevent triple-quote syntax issues