Fix OpenAPI3 import: support JSON Schema sibling keywords with $ref

[Copilot]

OpenAPI 3.1+ uses JSON Schema 2020-12, which permits sibling keywords alongside $ref. The importer ignored these keywords, dropping default values, constraints (min/max length/items/value), descriptions, and deprecation flags when schemas referenced other schemas with overrides.

Example that now works correctly:

parameters:
  - name: order
    in: query
    schema:
      $ref: "#/components/schemas/OrderEnum"
      default: "desc"
      deprecated: true

Generates:

#deprecated @query order?: OrderEnum = OrderEnum.desc

Changes

• Decorator/directive extraction - getDecoratorsForSchema() and getDirectivesForSchema() now check for sibling keywords when $ref is present, resolve the reference to determine schema type, then apply constraint decorators based on the resolved type
• Default value handling - generateTypeFromRefableSchema() extracts default values from schemas with $ref, generating proper enum member references (e.g., OrderEnum.desc) for enum types
• Parameter directives - Added directives field to TypeSpecOperationParameter interface, populated from schema during transformation, rendered in operation generation
• Context propagation - Updated transform functions to pass Context through the call chain, enabling $ref resolution during decorator extraction

Supports all sibling keywords that map to TypeSpec: default, minItems/maxItems, minimum/maximum/exclusiveMinimum/exclusiveMaximum, minLength/maxLength, deprecated, description, title.

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: /home/REDACTED/work/_temp/ghcca-node/node/bin/node node /home/REDACTED/work/typespec/typespec/website/node_modules/.bin/../astro/astro.js build sh -c ebsite/src/conte--llmstxt sed .0_tmp_4071/node../../website/src/content/docs/docs/emitters/openapi3/reference --no-emit bash /.bin/node sh /nod�� tsc -p tsconfig.build.json sh tools/pnpm/10.23.0_tmp_4071/node--output-dir --no-emit l/reference s/.bin/tspd sh (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 tool - peer JsonSchema reference keywords are NOT being considered, default</issue_title>
<issue_description>### Describe the bug

when importing the following OpenAPI description (3.1, 3.2), JsonSchema sibling keyword alongside $ref are not being used.

Json schema supports doing so since 2020-12 which is in use since OpenAPI 3.1 and above.

For a default value this matters since I can have

openapi:3.1.0
paths:
  /foo:
    get:
      parameters:
      - name: order
        schema:
          $ref: "#/components/schemas/OrderEnum"
          default: "desc"
components:
  schemas:
    OrderEnum:
      enum:
      - asc
      - desc

This should result in

op getFoo(@query order: OrderEnum = OrderEnum.desc): Bar

But the default value assignment is missing.

This is also a problem for model properties.

Default is not the only keyword that's impacted by this behaviour (we should however only consider the ones that lead to the application of decorators or additional metadata like default values, descriptions, etc...):

• maxItems
• minItems
• maximum
• exclusiveMaximum
• minimum
• exclusiveMinimum
• deprecated
• examples
• description
• maxLength
• minLength
• maxProperties
• minProperties
• readOnly
• required
• writeOnly

Reproduction

1. import an OpenAPI description with a $ref and one of the sibling keyword.
2. notice the equivalent semantic from the sibling keyword is either absent, or has a value from the target schema.

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>

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

• Fixes [Bug]: import tool - peer JsonSchema reference keywords are NOT being considered, default #9633

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.