Skip to content

ref(schema): Unify model schema definitions - #527

Draft
Lms24 wants to merge 11 commits into
mainfrom
issue-512-schema-unification-design
Draft

ref(schema): Unify model schema definitions#527
Lms24 wants to merge 11 commits into
mainfrom
issue-512-schema-unification-design

Conversation

@Lms24

@Lms24 Lms24 commented Jul 24, 2026

Copy link
Copy Markdown
Member

Make Zod 4 the single hand-written definition for all six model document formats. TypeScript input types are now inferred from those schemas, while the existing Draft 7 files remain committed, deterministically generated compatibility artifacts.

This removes drift between JSON Schema, Astro's embedded Zod definitions, and scripts/types.ts. Code generation and maintenance scripts now validate JSON before use and report actionable paths, and Astro consumes the same canonical schemas. Generated schemas preserve legacy anchors and authoring descriptions for existing external consumers.

We considered keeping JSON Schema canonical and generating Zod, but translating the existing conditional rules into useful Astro schemas would add another fragile generation layer. A staged migration was also considered; landing the consumers and parity checks together prevents an intermediate period with competing sources of truth.

The generated attribute schema is structurally larger because type/example relationships are represented as explicit unions. Reviewers should pay particular attention to the generated-schema compatibility wrappers and the explicit Zod/AJV semantic-oracle tests.

Fixes #512

Made with Cursor

Lms24 and others added 10 commits July 24, 2026 12:47
Define the approved Zod-first architecture and its task-level implementation
plan for GH-512.

Refs #512
Co-Authored-By: Claude <noreply@anthropic.com>

Co-authored-by: Cursor <cursoragent@cursor.com>
Establish canonical Zod models and inferred types for non-attribute
schema consumers.

Co-Authored-By: Claude <noreply@anthropic.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Use canonical Zod schemas for fail-fast loading across scripts and model tests,
removing duplicate hand-maintained model types.

Co-Authored-By: Claude <noreply@anthropic.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Generate committed JSON Schemas from the canonical Zod definitions and
verify equivalent validation behavior with AJV.

Co-Authored-By: Claude <noreply@anthropic.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Share model validation between Astro and the generated compatibility schemas,
and verify the documentation build once on Ubuntu pull-request CI.

Co-Authored-By: Claude <noreply@anthropic.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Cover plural dynamic-suffix examples and deprecations missing required
status in Zod/AJV parity checks. Remove whitespace found by final diff
verification.

Refs GH-512
Co-Authored-By: Cursor <cursoragent@cursor.com>

Co-authored-by: Cursor <cursoragent@cursor.com>
Assert the expected Zod and AJV results for plural dynamic examples and
deprecations missing status so agreement on incorrect behavior fails.

Refs GH-512
Co-Authored-By: Cursor <cursoragent@cursor.com>

Co-authored-by: Cursor <cursoragent@cursor.com>
Preserve actionable validation paths, legacy schema anchors, and authoring
metadata while making parity fixtures assert explicit semantics.

Refs #512
Co-Authored-By: Cursor <cursoragent@cursor.com>

Co-authored-by: Cursor <cursoragent@cursor.com>
Cover the remaining nested and top-level strict-object failures with explicit
false oracles for both Zod and AJV.

Refs #512
Co-Authored-By: Cursor <cursoragent@cursor.com>

Co-authored-by: Cursor <cursoragent@cursor.com>
@github-actions

github-actions Bot commented Jul 24, 2026

Copy link
Copy Markdown

Semver Impact of This PR

🟢 Patch (bug fixes)

📋 Changelog Preview

This is how your changes will appear in the changelog.
Entries from this PR are highlighted with a left border (blockquote style).


New Features ✨

Attributes

  • Add aws.request.url (deprecated) in favor of url.full by sentrivana in #488
  • Add subprocess.pid (deprecated) in favor of process.pid by sentrivana in #487
  • Add litestar.middleware_name (deprecated) in favor of middleware.name by sentrivana in #486
  • Add starlette.middleware_name (deprecated) in favor of middleware.name by sentrivana in #485
  • Add redis.key (deprecated) in favor of db.redis.key by sentrivana in #484
  • Add db.mongodb.collection (deprecated) in favor of db.collection.name by sentrivana in #483
  • Add Kafka messaging attributes by chargome in #474
  • Deprecate rpc.grpc.status_code in favor of rpc.response.status_code by lucas-zimerman in #494
  • Add deprecated messaging.destination_kind by andreiborza in #509
  • Add sentry.segment.name.source attribute by Lms24 in #466
  • Add attribute transformations by constantinius in #465
  • Add stable app vitals attributes by buenaflor in #493
  • Deprecate sentry.frames.* attributes by buenaflor in #500
  • Add missing AI legacy aliases from Relay SpanData by vgrozdanic in #498

Other

  • (conventions) Support multiple examples by Lms24 in #505
  • (descriptions) Add http.route description template for http.server span description inference by Lms24 in #518

Internal Changes 🔧

Attribute

  • Add more examples for valid sentry.kind values by Lms24 in #517
  • Improve db.statement example and add deprecation reason by Lms24 in #501

Attributes

  • Improve description of sentry.segment.name.source by Lms24 in #511
  • Deprecate sentry.span.source and change backfill status of sentry.source by Lms24 in #510

Deps

  • Bump fast-uri from 3.1.2 to 3.1.4 by dependabot in #526
  • Bump svgo from 4.0.1 to 4.0.2 by dependabot in #524
  • Bump js-yaml from 4.2.0 to 4.3.0 by dependabot in #516
  • Bump astro from 6.4.7 to 7.1.0 in /docs by dependabot in #514

Other

  • (attrs) Backport attributes and normalizations from Relay by Dav1dde in #497
  • (codeowners) Assign telemetry-experience to gen_ai/ai attributes by vgrozdanic in #506
  • (deps-dev) Bump tar from 7.5.16 to 7.5.19 by dependabot in #515
  • (release) Show version in workflow run title by constantinius in #504
  • (schema) Unify model schema definitions by Lms24 in #527

🤖 This preview updates automatically when you update the PR.

@cursor cursor Bot 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.

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Fix All in Cursor

❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.

Reviewed by Cursor Bugbot for commit 7dbadc9. Configure here.

Comment thread scripts/attribute_examples.ts
Keep committed JSON Schemas readable by inlining anonymous reused nodes while
preserving explicitly named compatibility definitions.

Refs #512
Co-Authored-By: Claude <noreply@anthropic.com>

Co-authored-by: Cursor <cursoragent@cursor.com>
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.

Clean up schemas and type definitions

1 participant