loxa-spec

README

LOXA Spec

LOXA Spec defines the shared contract between SDKs and collectors.

• loxa-go emits LOXA events that follow this spec.
• loxa-collector accepts LOXA events that follow this spec.
• This repository is the source of truth for schemas, ingest payload formats, compatibility rules, and wire-level examples.

Current Versions

• Schema Version: v1.0.0
• Ingest API Version: v1
• Status: Active

Repository Structure

loxa-spec/
├── v1/                          # Version 1 schema definitions
│   ├── event.schema.json        # Core event schema
│   ├── README.md                # v1 documentation
│   ├── compatibility.md         # v1 compatibility matrix
│   └── examples/                # Example events
│       ├── user_login.json      # User authentication example
│       └── api_request.json     # API request example
├── schema/                      # Legacy schema location (deprecated)
├── openapi/                     # OpenAPI specifications
│   └── collector.openapi.yaml   # Collector API spec
├── examples/                    # Additional examples
│   ├── events/                  # Event examples
│   ├── golden/                  # Golden test files
│   └── ingest/                  # Ingest payload examples
├── docs/                        # Documentation
│   ├── compatibility.md         # Compatibility guide
│   ├── SCHEMA_EVOLUTION_POLICY.md
│   └── ...
├── proto/                       # Protocol buffer definitions
├── CHANGELOG.md                 # Version history
├── compatibility.md             # Root compatibility guide
└── README.md                    # This file

Quick Start

Validate an Event

# Validate against v1 schema
loxa schema validate --file event.json --schema-version v1

# Validate from stdin
echo '{"event_id":"...","event_type":"user.login",...}' | loxa schema validate

View Schema Versions

# List all available schema versions
loxa schema list

# Show differences between versions
loxa schema diff --from v1.0.0 --to v1.1.0

Schema Overview

Required Fields (v1)

All LOXA events must include:

• event_id (string, UUID): Unique event identifier
• event_type (string): Event type in dot notation (e.g., user.login)
• timestamp (string, ISO 8601): Event timestamp
• service (object): Service identity with name and version
• deployment (object): Deployment context with environment

Example Event

{
  "event_id": "01934a5e-8f2c-7b3d-9e4f-5a6b7c8d9e0f",
  "event_type": "user.login",
  "timestamp": "2024-01-15T10:30:00.123Z",
  "service": {
    "name": "auth-service",
    "version": "2.1.0"
  },
  "deployment": {
    "environment": "production",
    "region": "us-east-1"
  },
  "data": {
    "login_method": "password",
    "success": true
  }
}

See v1/examples/ for complete examples.

Compatibility Promise

• Backward Compatible: Minor versions (v1.x) are backward compatible
• Forward Compatible: Collectors accept events with unknown optional fields
• Breaking Changes: Require major version increment (v1 → v2)
• Migration Period: 90 days minimum overlap for major versions

See compatibility.md for details.

Key Locations

• v1/: Version 1 schema definitions and examples
• schema/: JSON Schema for canonical LOXA events (legacy)
• openapi/: Collector ingest API description
• examples/: Event and ingest payload examples
• docs/: Language-neutral contract and compatibility documentation
• proto/: Canonical protobuf source files

Documentation

• v1 Schema Documentation
• Compatibility Matrix
• Schema Evolution Policy
• Event State Machine
• Identity Model
• Privacy & Compliance

Versioning

LOXA schemas follow Semantic Versioning:

• MAJOR (v1 → v2): Breaking changes (field removal, type changes)
• MINOR (v1.0 → v1.1): Backward-compatible additions (new optional fields)
• PATCH (v1.0.0 → v1.0.1): Documentation updates

See CHANGELOG.md for version history.

Contributing

1. Review Schema Evolution Policy
2. Submit GitHub issue with proposed changes
3. Create PR with schema updates and tests
4. Update CHANGELOG.md and compatibility docs

Testing

Golden Test Files

Use golden test files for validation:

# Run validation tests
loxa schema validate --dir examples/golden/valid/

# Test invalid events (should fail)
loxa schema validate --dir examples/golden/invalid/ --expect-failure

Schema Validation

# Validate schema syntax
loxa schema validate-schema --file v1/event.schema.json

# Check backward compatibility
loxa schema check-compatibility --base v1.0.0 --target v1.1.0

License

See LICENSE file.

Contact

• GitHub Issues: https://github.com/Astraive/loxa-spec/issues
• Documentation: https://github.com/Astraive/loxa-spec/docs