event-spec

📋

Event Contract Layer

Define events once in YAML with versioning, JSON Schema validation, and breaking-change detection using SchemaVer.

🔌

SDK Runtime Layer

Pluggable analytics destinations behind a stable Provider interface. Hooks, context propagation, queueing, and dispatch included.

⚡

Codegen Layer

Generate language-native typed wrappers from your event registry for Go, TypeScript, and Kotlin (Swift, Python planned).

🏛️

Governance Layer

Registry server with REST API, audit tooling to scan codebases for event usage, and automatic catalog generation.

Provider Ecosystem

✓Amplitude

○PostHogsoon

○Mixpanelsoon

○Segmentsoon

○GA4soon

○RudderStacksoon

SDK Support

✓ Go✓ TypeScript✓ Kotlin○ Swift○ Python○ Rust

From spec to instrumented in minutes

1. Define
2. Generate
3. Use (Go)
3. Use (TypeScript)
3. Use (Kotlin)

specs/ecommerce/product_viewed/1-0-0.yaml
# specs/ecommerce/product_viewed/1-0-0.yaml
$schema: "https://event-spec.io/schemas/event/v1"
name: product_viewed
display_name: "Product Viewed"
version: "1-0-0"
status: active
namespace: ecommerce
type: track
event_name: "Product Viewed"

properties:
  product_id:
    type: string
    required: true
  category:
    type: string
    required: true
    enum: [clothing, electronics, other]
  currency:
    type: string
    required: false
    default: "USD"

Terminal
# Generate Go wrappers
event-spec generate --lang go --out ./generated

# Generate TypeScript wrappers
event-spec generate --lang typescript --out ./src/analytics/generated

# Generate Kotlin wrappers
event-spec generate --lang kotlin --out ./generated

main.go
import (
    core "github.com/dejanradmanovic/event-spec/analytics"
    "github.com/dejanradmanovic/event-spec/provider/amplitude"
    generated "your-module/generated"
)

amp, _ := amplitude.New(amplitude.Config{
    ProviderConfig: provider.ProviderConfig{
        APIKey:     "${AMPLITUDE_API_KEY}",
        SecretType: provider.SecretEnvVar,
    },
})

client := core.NewClient(core.WithProviders(amp))
es := generated.New(client)

es.ProductViewed(ctx, generated.ProductViewedProperties{
    Category:  generated.ProductViewedCategoryElectronics,
    ProductId: "SKU-123",
})

index.ts
import { Client } from '@dejanradmanovic/event-spec-api';
import { AmplitudeProvider } from '@dejanradmanovic/event-spec-provider-amplitude';
import { productViewed, ProductViewedCategory } from './generated/product_viewed';

const amp = new AmplitudeProvider({ apiKey: process.env.AMPLITUDE_API_KEY! });
const client = new Client({ providers: [amp] });

await client.productViewed({
    category: ProductViewedCategory.Electronics,
    productId: 'SKU-123',
});

main.kt
import io.eventspec.analytics.Client
import io.eventspec.analytics.ClientOptions
import io.eventspec.analytics.amplitude.AmplitudeConfig
import io.eventspec.analytics.amplitude.AmplitudeProvider
import analytics.EventSpec
import analytics.ProductViewedProperties
import analytics.ProductViewedCategory

val amp = AmplitudeProvider(AmplitudeConfig(apiKey = System.getenv("AMPLITUDE_API_KEY")!!))
val client = Client(ClientOptions(providers = listOf(amp)))
val es = EventSpec(client)

es.productViewed(ProductViewedProperties(
    category = ProductViewedCategory.ELECTRONICS,
    productId = "SKU-123",
))