Skip to main content

Introducing ModelGraphGenerator

· 2 min read
Sharang Verma

We're excited to announce the open-source release of ModelGraphGenerator — a command-line tool that automatically generates JSON Schema from your annotated Swift models.

The Problem​

If you've ever maintained a Swift API or SDK, you know the pain: your Swift models and their JSON Schema representations drift apart over time. Schema changes require manual updates in two separate places. It's easy to miss a field, get a type wrong, or forget to add a constraint to the schema.

We built ModelGraphGenerator internally at PhonePe to solve this. Today, we're sharing it with the community.

How It Works​

Annotate any Swift struct or class with @ChimeraSchema, add @ChimeraProperty annotations to your properties, and run the CLI:

@ChimeraMetaData(description: "A payment transaction")
@ChimeraSchema(key: "payment")
struct Payment {
    @ChimeraProperty(description: "Transaction ID")
    let transactionId: String

    @ChimeraProperty(description: "Amount in USD", min: 0.0)
    let amount: Double

    @ChimeraProperty(description: "Payment status")
    let status: PaymentStatus
}
model-graph-generator --source-path ./Sources --output schema.json --json-schema

That's it. You get a complete JSON Schema Draft 2020-12 document.

Key Features​

Multi-Strategy Discovery
ModelGraphGenerator finds your annotated types using both macro scanning and IndexStoreDB, giving you flexibility in how you structure your project.

Polymorphic Types
Support for oneOf schemas via @PolymorphicMapping, with discriminator fields for code generators and validators.

CodingKeys Support
If you've defined custom CodingKeys, ModelGraphGenerator respects them in the generated schema.

Cycle Detection
Circular model references are detected and handled gracefully — no infinite loops.

What's Next​

This is v1.0.0 — the foundation. Here's what we're planning:

  • DocC integration — Browse the API docs alongside the CLI docs
  • Interactive schema explorer — Explore generated schemas directly in the browser
  • OpenAPI export — First-class OpenAPI 3.1 components output
  • Xcode plugin — Generate schemas directly from Xcode's build phases

Get Started​

git clone https://github.com/PhonePe/ModelGraphGenerator.git
cd ModelGraphGenerator
swift build -c release

Read the full Getting Started guide or dive into the annotation reference.

We'd love your feedback — open an issue, start a discussion, or send a PR. Thank you for checking it out.