Skip to content

fix(json-schema-2020-12): render property schema title - #11062

Open
joshuablac wants to merge 1 commit into
swagger-api:mainfrom
joshuablac:fix/json-schema-2020-12-property-title
Open

joshuablac wants to merge 1 commit into
swagger-api:mainfrom
joshuablac:fix/json-schema-2020-12-property-title

Conversation

@joshuablac

Copy link
Copy Markdown

Description

In OpenAPI 3.1 / JSON Schema 2020-12 rendering, a title set on a property schema was never shown.

Properties renders each property through JSONSchema with name={propertyName}. JSONSchema then passes that name as the title prop of KeywordTitle. Title rendered title || fn.getTitle(schema), so the property key always won and the schema's own title was dropped.

This PR keeps the property key as the primary label. When the schema has its own title, Title also renders it next to the key as a secondary label (json-schema-2020-12__title-secondary, normal weight, italic).

  • The lookup uses getTitle(schema, { lookup: "basic" }). This means only a real title keyword is shown, never $anchor/$id fallbacks.
  • The secondary label is skipped when the primary label already contains the title (case-insensitive). That covers top-level models (where the label already is the title), combinator labels such as #0 Cat, and properties whose title just repeats the key (color with title: color, which getTitle would upper-case to Color).

Behavior note: a $ref'd schema that has a title and is rendered under its component key (e.g. a request/response body referencing #/components/schemas/Pet with title: My Pet) now shows Pet followed by My Pet. Previously only the key was shown.

Motivation and Context

Fixes #11053

How Has This Been Tested?

  • Added two e2e tests in schema-title.cy.js, plus nickname (title: Pet nickname) and color (title: color) properties to its fixture.
    • The first test fails on main (Expected to find content: 'Pet nickname') and passes with this change.
    • The second test checks that color gets no repeated secondary label.
  • Ran all Cypress specs under features/plugins/json-schema-2020-12, oas31 and oas32 locally: 17 specs, 88 tests, all passing.
  • npm run lint-errors passes, stylelint passes on the changed SCSS, and npm run build succeeds.
  • npm run test:unit: the only failures are 18 tests in test/unit/core/utils.js (Cannot delete property 'location' of #<Window>). They fail identically without this change. The cause is my local Node/jsdom version, not this PR.

Screenshots (if appropriate):

Fixture json-schema-2020-12-title.yaml, model Pet expanded (before / after):

Checklist

My PR contains...

  • No code changes (src/ is unmodified: changes to documentation, CI, metadata, etc.)
  • Dependency changes (any modification to dependencies in package.json)
  • Bug fixes (non-breaking change which fixes an issue)
  • Improvements (misc. changes to existing features)
  • Features (non-breaking change which adds functionality)

My changes...

  • are breaking changes to a public API (config options, System API, major UI change, etc).
  • are breaking changes to a private API (Redux, component props, utility functions, etc.).
  • are breaking changes to a developer API (npm script behavior changes, new dev system dependencies, etc).
  • are not breaking changes.

Documentation

  • My changes do not require a change to the project documentation.
  • My changes require a change to the project documentation.
  • If yes to above: I have updated the documentation accordingly.

Automated tests

  • My changes can not or do not need to be tested.
  • My changes can and should be tested by unit and/or integration tests.
  • If yes to above: I have added tests to cover my changes.
  • If yes to above: I have taken care to cover edge cases in my tests.
  • All new and existing tests passed.

🤖 Generated with Claude Code

What was wrong:
When an API describes a field and gives it a friendly name (a "title"),
for example a field called "nickname" titled "Pet nickname", Swagger UI
showed only "nickname" for OpenAPI 3.1 documents. The friendly name was
silently thrown away.

What this changes:
Swagger UI now shows the friendly name in italics next to the field name,
e.g. "nickname  Pet nickname". If the friendly name is just the field
name again (like "color" titled "color"), it is not repeated.

Also adds automated tests that check both cases.

Fixes swagger-api#11053

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Copilot AI lite review requested due to automatic review settings September 21, 2026 11:17

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot review overview

🟢 Approval recommended

The implementation matches the stated behavior and includes focused regression coverage.

Review effort: Lite
Findings: None

What changed in this PR

Fixes OpenAPI 3.1 property-schema title rendering while preserving property names as primary labels.

Changes:

  • Adds secondary schema titles with duplicate suppression.
  • Adds styling for secondary labels.
  • Adds fixture data and Cypress coverage.
File Description
Title.jsx Renders explicit schema titles beside primary labels.
_title.scss Styles secondary titles.
schema-title.cy.js Tests rendering and deduplication.
json-schema-2020-12-title.yaml Adds titled properties to the fixture.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Property-level title keyword is silently dropped for OpenAPI 3.1 schemas

2 participants