# Event Schemas
> Avro-based event schemas for TypeScript and Python services
This repository contains Apache Avro schemas for event-driven communication between services, with auto-generated TypeScript and Python types.
## 📦 Installation
### TypeScript / JavaScript
```bash
npm install @godjigame/event-schemas
```
### Python
```bash
pip install godjigame-event-schemas
```
## 🚀 Usage
### TypeScript
```typescript
import { UserCreatedEvent, UserUpdatedEvent, EventMetadata } from '@godjigame/event-schemas';
// Create event metadata
const metadata: EventMetadata = {
correlationId: '123e4567-e89b-12d3-a456-426614174000',
causationId: '456e7890-e89b-12d3-a456-426614174001',
traceId: '789e1234-e89b-12d3-a456-426614174002'
};
// Create user created event
const userCreatedEvent: UserCreatedEvent = {
eventId: '550e8400-e29b-41d4-a716-446655440000',
eventType: 'user.created',
version: '1.0.0',
timestamp: new Date().toISOString(),
source: 'gamer-id',
metadata,
data: {
userId: 'user123',
email: 'user@example.com',
username: 'johndoe',
displayName: 'John Doe',
createdAt: new Date().toISOString(),
updatedAt: null
}
};
// Use in Kafka consumer
async function handleUserCreated(event: UserCreatedEvent) {
console.log(`User created: ${event.data.userId}`);
// Process event...
}
```
### Python
```python
from event_types import UserCreatedEvent, UserUpdatedEvent, EventMetadata
from datetime import datetime
import uuid
# Create event metadata
metadata = EventMetadata(
correlationId=str(uuid.uuid4()),
causationId=str(uuid.uuid4()),
traceId=str(uuid.uuid4())
)
# Create user created event
user_created_event = UserCreatedEvent(
eventId=str(uuid.uuid4()),
eventType="user.created",
version="1.0.0",
timestamp=datetime.utcnow().isoformat(),
source="gamer-id",
metadata=metadata,
data=UserPayload(
userId="user123",
email="user@example.com",
username="johndoe",
displayName="John Doe",
createdAt=datetime.utcnow().isoformat(),
updatedAt=None
)
)
# Use in Kafka producer
def publish_user_created(user_data):
event = UserCreatedEvent(
eventId=str(uuid.uuid4()),
eventType="user.created",
version="1.0.0",
timestamp=datetime.utcnow().isoformat(),
source="gamer-id",
metadata=create_metadata(),
data=user_data
)
# Send to Kafka...
```
## 📋 Available Types
### Event Types
- `UserCreatedEvent` - Emitted when a new user is created
- `UserUpdatedEvent` - Emitted when a user is updated
- `UserDeletedEvent` - Emitted when a user is deleted
### Common Types
- `EventMetadata` - Common metadata for all events
- `BaseEvent` - Base event structure
- `UserPayload` - User data payload
- `DeletedUserPayload` - Payload for deleted user events
## 🔧 Development
### Prerequisites
- Node.js 20+
- Python 3.8+
### Setup
```bash
# Clone the repository
git clone https://github.com/goodgameteamit/event-schemas.git
cd event-schemas
# Install dependencies
npm install
# Generate types
npm run generate
```
### Commands
```bash
# Generate TypeScript and Python types
npm run generate
# Validate schemas
npm run test:schemas
# Validate generated types
npm run test:types
# Run all tests
npm test
# Bump version
npm run version:bump
```
### Schema Development
1. **Add new schemas** in the `schemas/` directory
2. **Follow naming conventions**: Use kebab-case for file names
3. **Update dependencies**: Add new schema files to the generation script
4. **Test thoroughly**: Run validation and generation after changes
### Schema Evolution
When evolving schemas:
- ✅ **Add new optional fields** with default values
- ✅ **Add new event types**
- ✅ **Update documentation**
- ❌ **Don't remove existing fields**
- ❌ **Don't rename existing fields**
- ❌ **Don't change field types**
## 📁 Repository Structure
```
event-schemas/
├── schemas/ # Avro schema definitions
│ ├── metadata.avsc
│ ├── base-event.avsc
│ └── user-events.avsc
├── generated/ # Generated types
│ ├── typescript/
│ │ └── index.ts
│ └── python/
│ └── __init__.py
├── scripts/ # Build scripts
│ ├── generate-types.sh
│ └── validate-schemas.js
├── .github/workflows/ # CI/CD pipeline
│ └── release.yml
├── package.json # NPM package config
├── setup.py # Python package config
└── pyproject.toml # Modern Python config
```
## 🔄 CI/CD Pipeline
The repository includes automated CI/CD with GitHub Actions:
- **Pull Requests**: Schema validation and type generation checks
- **Main Branch**: Automatic NPM publishing and continuous validation
### Publishing
To publish a new version:
```bash
# Bump version in package.json and pyproject.toml
npm run version:bump
# Commit and push changes
git add package.json pyproject.toml
git commit -m "Bump version to x.x.x"
git push
```
## 📖 Schema Documentation
### Event Metadata
All events include common metadata for tracing and correlation:
```json
{
"correlationId": "Unique identifier for tracking related events",
"causationId": "Identifier of the event that caused this event",
"traceId": "Distributed tracing identifier"
}
```
### Base Event Structure
All events extend the base event structure:
```json
{
"eventId": "Unique identifier for this event",
"eventType": "Type of event (e.g., user.created)",
"version": "Schema version",
"timestamp": "ISO 8601 timestamp",
"source": "Service that generated the event",
"metadata": "Event metadata object",
"data": "Event-specific data"
}
```
## 🤝 Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new schemas
5. Submit a pull request
## 📄 License
MIT License - see [LICENSE](LICENSE) file for details.
## 🔗 Related Projects
- [Apache Avro](https://avro.apache.org/) - Data serialization system
- [Confluent Schema Registry](https://docs.confluent.io/platform/current/schema-registry/) - Schema management
- [Kafka](https://kafka.apache.org/) - Event streaming platform
Raw data
{
"_id": null,
"home_page": "https://github.com/goodgameteamit/event-schemas",
"name": "godjigame-event-schemas",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "avro, schemas, events, typescript, kafka, event-driven",
"author": "Godji Game",
"author_email": "Godji Game <team@goodgameteamit.com>",
"download_url": "https://files.pythonhosted.org/packages/d4/8a/40d4fde48e0cab23216b595d369bb503bdf7ec412ff9cb41e76eff8d631b/godjigame_event_schemas-1.5.0.tar.gz",
"platform": null,
"description": "# Event Schemas\n\n> Avro-based event schemas for TypeScript and Python services\n\nThis repository contains Apache Avro schemas for event-driven communication between services, with auto-generated TypeScript and Python types.\n\n## \ud83d\udce6 Installation\n\n### TypeScript / JavaScript\n\n```bash\nnpm install @godjigame/event-schemas\n```\n\n### Python\n\n```bash\npip install godjigame-event-schemas\n```\n\n## \ud83d\ude80 Usage\n\n### TypeScript\n\n```typescript\nimport { UserCreatedEvent, UserUpdatedEvent, EventMetadata } from '@godjigame/event-schemas';\n\n// Create event metadata\nconst metadata: EventMetadata = {\n correlationId: '123e4567-e89b-12d3-a456-426614174000',\n causationId: '456e7890-e89b-12d3-a456-426614174001',\n traceId: '789e1234-e89b-12d3-a456-426614174002'\n};\n\n// Create user created event\nconst userCreatedEvent: UserCreatedEvent = {\n eventId: '550e8400-e29b-41d4-a716-446655440000',\n eventType: 'user.created',\n version: '1.0.0',\n timestamp: new Date().toISOString(),\n source: 'gamer-id',\n metadata,\n data: {\n userId: 'user123',\n email: 'user@example.com',\n username: 'johndoe',\n displayName: 'John Doe',\n createdAt: new Date().toISOString(),\n updatedAt: null\n }\n};\n\n// Use in Kafka consumer\nasync function handleUserCreated(event: UserCreatedEvent) {\n console.log(`User created: ${event.data.userId}`);\n // Process event...\n}\n```\n\n### Python\n\n```python\nfrom event_types import UserCreatedEvent, UserUpdatedEvent, EventMetadata\nfrom datetime import datetime\nimport uuid\n\n# Create event metadata\nmetadata = EventMetadata(\n correlationId=str(uuid.uuid4()),\n causationId=str(uuid.uuid4()),\n traceId=str(uuid.uuid4())\n)\n\n# Create user created event\nuser_created_event = UserCreatedEvent(\n eventId=str(uuid.uuid4()),\n eventType=\"user.created\",\n version=\"1.0.0\",\n timestamp=datetime.utcnow().isoformat(),\n source=\"gamer-id\",\n metadata=metadata,\n data=UserPayload(\n userId=\"user123\",\n email=\"user@example.com\",\n username=\"johndoe\",\n displayName=\"John Doe\",\n createdAt=datetime.utcnow().isoformat(),\n updatedAt=None\n )\n)\n\n# Use in Kafka producer\ndef publish_user_created(user_data):\n event = UserCreatedEvent(\n eventId=str(uuid.uuid4()),\n eventType=\"user.created\",\n version=\"1.0.0\",\n timestamp=datetime.utcnow().isoformat(),\n source=\"gamer-id\",\n metadata=create_metadata(),\n data=user_data\n )\n # Send to Kafka...\n```\n\n## \ud83d\udccb Available Types\n\n### Event Types\n\n- `UserCreatedEvent` - Emitted when a new user is created\n- `UserUpdatedEvent` - Emitted when a user is updated\n- `UserDeletedEvent` - Emitted when a user is deleted\n\n### Common Types\n\n- `EventMetadata` - Common metadata for all events\n- `BaseEvent` - Base event structure\n- `UserPayload` - User data payload\n- `DeletedUserPayload` - Payload for deleted user events\n\n## \ud83d\udd27 Development\n\n### Prerequisites\n\n- Node.js 20+\n- Python 3.8+\n\n### Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/goodgameteamit/event-schemas.git\ncd event-schemas\n\n# Install dependencies\nnpm install\n\n# Generate types\nnpm run generate\n```\n\n### Commands\n\n```bash\n# Generate TypeScript and Python types\nnpm run generate\n\n# Validate schemas\nnpm run test:schemas\n\n# Validate generated types\nnpm run test:types\n\n# Run all tests\nnpm test\n\n# Bump version\nnpm run version:bump\n```\n\n### Schema Development\n\n1. **Add new schemas** in the `schemas/` directory\n2. **Follow naming conventions**: Use kebab-case for file names\n3. **Update dependencies**: Add new schema files to the generation script\n4. **Test thoroughly**: Run validation and generation after changes\n\n### Schema Evolution\n\nWhen evolving schemas:\n\n- \u2705 **Add new optional fields** with default values\n- \u2705 **Add new event types**\n- \u2705 **Update documentation**\n- \u274c **Don't remove existing fields**\n- \u274c **Don't rename existing fields**\n- \u274c **Don't change field types**\n\n## \ud83d\udcc1 Repository Structure\n\n```\nevent-schemas/\n\u251c\u2500\u2500 schemas/ # Avro schema definitions\n\u2502 \u251c\u2500\u2500 metadata.avsc\n\u2502 \u251c\u2500\u2500 base-event.avsc\n\u2502 \u2514\u2500\u2500 user-events.avsc\n\u251c\u2500\u2500 generated/ # Generated types\n\u2502 \u251c\u2500\u2500 typescript/\n\u2502 \u2502 \u2514\u2500\u2500 index.ts\n\u2502 \u2514\u2500\u2500 python/\n\u2502 \u2514\u2500\u2500 __init__.py\n\u251c\u2500\u2500 scripts/ # Build scripts\n\u2502 \u251c\u2500\u2500 generate-types.sh\n\u2502 \u2514\u2500\u2500 validate-schemas.js\n\u251c\u2500\u2500 .github/workflows/ # CI/CD pipeline\n\u2502 \u2514\u2500\u2500 release.yml\n\u251c\u2500\u2500 package.json # NPM package config\n\u251c\u2500\u2500 setup.py # Python package config\n\u2514\u2500\u2500 pyproject.toml # Modern Python config\n```\n\n## \ud83d\udd04 CI/CD Pipeline\n\nThe repository includes automated CI/CD with GitHub Actions:\n\n- **Pull Requests**: Schema validation and type generation checks\n- **Main Branch**: Automatic NPM publishing and continuous validation\n\n### Publishing\n\nTo publish a new version:\n\n```bash\n# Bump version in package.json and pyproject.toml\nnpm run version:bump\n\n# Commit and push changes\ngit add package.json pyproject.toml\ngit commit -m \"Bump version to x.x.x\"\ngit push\n```\n\n## \ud83d\udcd6 Schema Documentation\n\n### Event Metadata\n\nAll events include common metadata for tracing and correlation:\n\n```json\n{\n \"correlationId\": \"Unique identifier for tracking related events\",\n \"causationId\": \"Identifier of the event that caused this event\",\n \"traceId\": \"Distributed tracing identifier\"\n}\n```\n\n### Base Event Structure\n\nAll events extend the base event structure:\n\n```json\n{\n \"eventId\": \"Unique identifier for this event\",\n \"eventType\": \"Type of event (e.g., user.created)\",\n \"version\": \"Schema version\",\n \"timestamp\": \"ISO 8601 timestamp\",\n \"source\": \"Service that generated the event\",\n \"metadata\": \"Event metadata object\",\n \"data\": \"Event-specific data\"\n}\n```\n\n## \ud83e\udd1d Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests for new schemas\n5. Submit a pull request\n\n## \ud83d\udcc4 License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## \ud83d\udd17 Related Projects\n\n- [Apache Avro](https://avro.apache.org/) - Data serialization system\n- [Confluent Schema Registry](https://docs.confluent.io/platform/current/schema-registry/) - Schema management\n- [Kafka](https://kafka.apache.org/) - Event streaming platform\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Avro-based event schemas for TypeScript and Python services",
"version": "1.5.0",
"project_urls": {
"Bug Reports": "https://github.com/goodgameteamit/event-schemas/issues",
"Documentation": "https://github.com/goodgameteamit/event-schemas#readme",
"Homepage": "https://github.com/goodgameteamit/event-schemas",
"Source": "https://github.com/goodgameteamit/event-schemas"
},
"split_keywords": [
"avro",
" schemas",
" events",
" typescript",
" kafka",
" event-driven"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "6be97099b89410381fcca0943e8eb70b16d97c6455936a95e06ca55d3363c02d",
"md5": "062374a747683d83b7676575f2217712",
"sha256": "462659e3269821b6657497dc576d13f3b3a8af75278aa25878cdb9426c4032bf"
},
"downloads": -1,
"filename": "godjigame_event_schemas-1.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "062374a747683d83b7676575f2217712",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 5097,
"upload_time": "2025-07-16T12:41:05",
"upload_time_iso_8601": "2025-07-16T12:41:05.194391Z",
"url": "https://files.pythonhosted.org/packages/6b/e9/7099b89410381fcca0943e8eb70b16d97c6455936a95e06ca55d3363c02d/godjigame_event_schemas-1.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "d48a40d4fde48e0cab23216b595d369bb503bdf7ec412ff9cb41e76eff8d631b",
"md5": "12e5dbf3090caa4f96fa97573b612e49",
"sha256": "ea45da5f106989b2f431b1f65d5e106987d8ad55eec730ed0a07142aaccf5c51"
},
"downloads": -1,
"filename": "godjigame_event_schemas-1.5.0.tar.gz",
"has_sig": false,
"md5_digest": "12e5dbf3090caa4f96fa97573b612e49",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 5936,
"upload_time": "2025-07-16T12:41:06",
"upload_time_iso_8601": "2025-07-16T12:41:06.166758Z",
"url": "https://files.pythonhosted.org/packages/d4/8a/40d4fde48e0cab23216b595d369bb503bdf7ec412ff9cb41e76eff8d631b/godjigame_event_schemas-1.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-16 12:41:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "goodgameteamit",
"github_project": "event-schemas",
"github_not_found": true,
"lcname": "godjigame-event-schemas"
}
JSON
