Skip to content

Keep author-set schema titles and accept Tag objects on operations - #20

Merged
tymondesigns merged 1 commit into
mainfrom
cursor/keep-deliberate-schema-titles-and-accept-tag-objects-bbee
Sep 15, 2026
Merged

tymondesigns merged 1 commit into
mainfrom
cursor/keep-deliberate-schema-titles-and-accept-tag-objects-bbee

Conversation

@tymondesigns

Copy link
Copy Markdown
Contributor

Summary

Implements OA-1 and OA-2 from the OpenAPI 3.1 porting feedback. JSON Schema items (JS-*) are out of scope.

OA-1 — Keep deliberate titles when embedding a JsonSchema

BuildsArray::unwrapValue() always passed includeTitle: false, which dropped both factory/constructor titles and titles set with ->title().

cortexphp/json-schema 1.3.0 already distinguishes them: getInitialTitle() is the constructor argument and getTitle() is the current value. They differ only when the author called ->title() with a different string.

Embedding now:

  • strips $schema (unchanged)
  • strips constructor/factory titles on inline schemas (unchanged)
  • keeps a title when getTitle() !== null && getTitle() !== getInitialTitle()

Reproductions from the feedback:

MediaType::json()->schema(Schema::object('Consult')->title('consults'))->toArray();
// schema.title is "consults"

Parameter::query('when')->schema(Schema::string('IsoDateTime'))->toArray();
// schema has no title

OA-2 — Operation::tags() accepts Tag|string

Callers that already hold a Tag no longer need ->getName(). String tags remain valid.

$operation->tags(Tag::create('Users'));
$operation->tags('Users');
$operation->tags(Tag::create('Users'), 'Admin');

Other

One-line Rector cleanup on Response::$description so composer format:check passes with the current Rector version.

Test plan

  • Pest (192 tests)
  • PHPStan level 10
  • Type coverage 100%
  • composer format:check (Rector + ECS)
  • CI on this PR
Open in Web Open in Cursor 

When embedding a JsonSchema, strip constructor titles but keep titles
set via title() that differ from getInitialTitle(). Operation::tags()
now accepts Tag|string and resolves Tag objects to their names.

Co-authored-by: Sean Tymon <tymondesigns@users.noreply.github.com>
@tymondesigns
tymondesigns merged commit 379ea3c into main Sep 15, 2026
17 checks passed
@tymondesigns
tymondesigns deleted the cursor/keep-deliberate-schema-titles-and-accept-tag-objects-bbee branch September 15, 2026 22:00
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.

2 participants