Schema Development Workflow

# 1. Create JSON Schema
cat > database/schemas/domain/v1/new_entity.schema.json << 'EOF'
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://altsportsdata.ai/schemas/new_entity.v1.schema.json",
  "title": "NewEntity",
  "type": "object",
  "properties": {
    "id": {"type": "string"},
    "name": {"type": "string", "minLength": 2}
  },
  "required": ["id", "name"]
}
EOF
 
# 2. Generate Pydantic models
./scripts/regenerate_adapters.sh
 
# 3. Add to Neo4j schema
cat >> database/sql/neo4j_comprehensive_schema.cypher << 'EOF'
 
// New Entity
CREATE CONSTRAINT new_entity_id_unique IF NOT EXISTS
  FOR (n:NewEntity) REQUIRE n.id IS UNIQUE;
 
CREATE INDEX new_entity_name_idx IF NOT EXISTS
  FOR (n:NewEntity) ON (n.name);
EOF
 
# 4. Document mapping
# Edit database/docs/SCHEMA_MAPPING.md and add entity
 
# 5. Validate sync
python database/scripts/validate_schema_sync.py

# 1. Update JSON Schema
# Edit database/schemas/domain/v1/entity_name.schema.json
 
# 2. Regenerate adapters
./scripts/regenerate_adapters.sh
 
# 3. Update Neo4j schema
# Edit database/sql/neo4j_comprehensive_schema.cypher
 
# 4. Apply Neo4j changes (if using Neo4j)
# cypher-shell < database/sql/neo4j_comprehensive_schema.cypher
 
# 5. Validate sync
python database/scripts/validate_schema_sync.py

# JSON Schema
# Add to "properties" section
 
# Neo4j Cypher
# Add to node template properties
 
# Validate
python database/scripts/validate_schema_sync.py

# JSON Schema (optional - may use foreign key pattern)
# Add foreign key field OR array of IDs
 
# Neo4j Cypher (required)
CREATE (entity1)-[:RELATIONSHIP_TYPE {property: 'value'}]->(entity2)
 
# Document in SCHEMA_MAPPING.md under "Relationship Mapping Patterns"

# Full validation
python database/scripts/validate_schema_sync.py
 
# Verbose output
python database/scripts/validate_schema_sync.py --verbose
 
# Custom base path
python database/scripts/validate_schema_sync.py --base-path /path/to/database

# Regenerate all adapters (Python, TypeScript, Drizzle)
./scripts/regenerate_adapters.sh
 
# Generate specific target
python database/setup/generate_adapters.py --version v1 --target python
python database/setup/generate_adapters.py --version v1 --target typescript
python database/setup/generate_adapters.py --version v1 --target drizzle

# Apply Neo4j schema (requires Neo4j running)
cat database/sql/neo4j_comprehensive_schema.cypher | cypher-shell
 
# Query Neo4j
cypher-shell "MATCH (n) RETURN labels(n), count(n)"
cypher-shell "CALL db.constraints()"
cypher-shell "CALL db.indexes()"

{
  "league_id": "string",
  "full_name": "string",
  "website_url": "string"
}

{
  id: "string",        // league_id → id (shortened)
  fullName: "string",  // full_name → fullName (camelCase)
  websiteUrl: "string" // website_url → websiteUrl (camelCase)
}

JSON: team.league_id = "LEAGUE_001"
Neo4j: "(team)-[:COMPETES_IN]->(league {id: "LEAGUE_001"})"

JSON: league.team_ids = ["TEAM_001", "TEAM_002"]
Neo4j: "(league)<-[:COMPETES_IN]-(team1), (league)<-[:COMPETES_IN]-(team2)"

JSON: "player.contract = {start: "2025-01", end: "2026-12"}"
Neo4j: "(player)-[:HAS_CONTRACT {start: date(), end: date()}]->(contract)"

✅ ALL CHECKS PASSED
Summary: 10 JSON entities, 10 Neo4j entities

❌ VALIDATION FAILED (3 errors)

🔴 ERRORS:
  • Entity "Team" missing in Neo4j
  • League: JSON property 'website_url' → Neo4j property 'websiteUrl' NOT FOUND

🟡 WARNINGS:
  • Neo4j has "Sportsbook" entity not in JSON Schema

💡 SUGGESTIONS:
  • Add 'websiteUrl' to Neo4j League node
  • Document mapping in SCHEMA_MAPPING.md

ls database/schemas/domain/v1/
ls database/sql/neo4j_comprehensive_schema.cypher

name: Validate Schemas
on: [push, pull_request]
 
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with:
          python-version: '3.11'
 
      - name: Validate schema sync
        run: python database/scripts/validate_schema_sync.py
 
      - name: Generate adapters (test)
        run: ./scripts/regenerate_adapters.sh