Data Schemas

This document describes all data models and schemas used by the ESFA Backend API. These schemas define the structure of request and response payloads.

Overview

The ESFA Backend API uses JSON for all data exchange. All schemas are defined according to OpenAPI 3.0 specification and follow consistent patterns for data validation and serialization.

Common Patterns

ID Fields: All identifiers are strings (typically UUIDs for matches, simple strings for players)
Timestamps: ISO 8601 format in UTC (e.g., 2025-09-05T13:31:23.174Z)
URLs: Full HTTP/HTTPS URLs for external resources
Error Handling: Consistent error envelope structure across all endpoints

Core Schemas

Player

Represents a player participating in a game match.

{
  "id": "p1",
  "name": "Alice",
  "status": "Active",
  "imgAvatarUrl": "https://api.dicebear.com/9.x/adventurer/svg?seed=Alice"
}

Fields

Field	Type	Required	Description
`id`	string	✓	Unique identifier for the player
`name`	string	✓	Display name of the player
`status`	string	✓	Current status of the player in the match
`imgAvatarUrl`	string		URL to the player's avatar image

Player Status Values

Value	Description
`Active`	Player is actively participating in the match
`Pending`	Player has joined but is not yet active
`Inactive`	Player is temporarily inactive
`Disconnected`	Player has lost connection

Validation Rules

id: Must be non-empty string, typically alphanumeric
name: Must be non-empty string, max length varies by implementation
status: Must be one of the defined status values
imgAvatarUrl: Must be valid URL if provided

GameMatch

Represents a complete game match with its players.

{
  "matchId": "a3c6e5f2-1a2b-4c5d-8e9f-0123456789ab",
  "gameCode": "TTT",
  "players": [
    {
      "id": "p1",
      "name": "Alice",
      "status": "Active",
      "imgAvatarUrl": "https://api.dicebear.com/9.x/adventurer/svg?seed=Alice"
    },
    {
      "id": "p2",
      "name": "Bob",
      "status": "Pending",
      "imgAvatarUrl": "https://api.dicebear.com/9.x/adventurer/svg?seed=Bob"
    }
  ]
}

Fields

Field	Type	Required	Description
`matchId`	string	✓	Unique identifier for the match
`gameCode`	string	✓	Code identifying the game type
`players`	array	✓	Array of Player objects

Game Code Values

Code	Game Type
`TTT`	Tic-Tac-Toe
(others)	Additional games as configured

Validation Rules

matchId: Must be valid UUID format
gameCode: Must be supported game code
players: Must be non-empty array of valid Player objects

Request Schemas

GameMatchFinishRequest

Used to submit final results when completing a match.

{
  "results": [
    {
      "playerId": "p1",
      "place": 1,
      "score": 1200
    },
    {
      "playerId": "p2",
      "place": 2,
      "score": 900
    }
  ]
}

Fields

Field	Type	Required	Description
`results`	array	✓	Array of player result objects

Player Result Object

Field	Type	Required	Description
`playerId`	string	✓	Unique identifier for the player
`place`	integer	✓	Final ranking/position (1st, 2nd, etc.)
`score`	number	✓	Final score achieved by the player

Validation Rules

results: Must be non-empty array
playerId: Must correspond to a player in the match
place: Must be positive integer starting from 1
place: All values must be unique (no ties)
place: Must be consecutive sequence (1, 2, 3, ..., n)
score: Must be numeric (integer or decimal)

Example Validation

Valid Results Example:

{
  "results": [
    {"playerId": "p1", "place": 1, "score": 1200},
    {"playerId": "p2", "place": 2, "score": 900},
    {"playerId": "p3", "place": 3, "score": 700}
  ]
}

Invalid Examples:

Missing place sequence:

{
  "results": [
    {"playerId": "p1", "place": 1, "score": 1200},
    {"playerId": "p2", "place": 3, "score": 900}
  ]
}

Duplicate places:

{
  "results": [
    {"playerId": "p1", "place": 1, "score": 1200},
    {"playerId": "p2", "place": 1, "score": 900}
  ]
}

MachineTokenRequest

Used to request authentication tokens from the Authentication Service.

{
  "apiKey": "your-api-key",
  "secretKey": "your-secret-key"
}

Fields

Field	Type	Required	Description
`apiKey`	string	✓	API key provided by administrator
`secretKey`	string	✓	Secret key provided by administrator

Validation Rules

apiKey: Must be non-empty string
secretKey: Must be non-empty string
Both fields are case-sensitive

Response Schemas

OAuthMachineTokenResponse

Response from the Authentication Service containing a Bearer token.

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires": "2025-09-05T13:31:23.174Z"
  }
}

Fields

Field	Type	Required	Description
`data`	object	✓	Token data container
`data.token`	string	✓	JWT Bearer token
`data.expires`	string	✓	Token expiration timestamp (ISO 8601 UTC)

Usage

// Extract token for API calls
const tokenResponse = await getToken();
const bearerToken = tokenResponse.data.token;
const expiresAt = new Date(tokenResponse.data.expires);

// Use in API calls
const headers = {
  'Authorization': `Bearer ${bearerToken}`
};

ErrorEnvelope

Standardized error response format used across all endpoints.

{
  "errors": [
    {
      "i18N": "MATCH_NOT_FOUND",
      "error": "Match not found",
      "type": "NotFound"
    }
  ]
}

Fields

Field	Type	Required	Description
`errors`	array	✓	Array of error objects

Error Object

Field	Type	Required	Description
`i18N`	string	✓	Internationalization key for error
`error`	string	✓	Human-readable error message
`type`	string	✓	Error type classification

Error Types

Type	HTTP Status	Description
`BadRequest`	400	Invalid request data
`Unauthorized`	401	Authentication required
`Forbidden`	403	Access denied
`NotFound`	404	Resource not found
`Conflict`	409	Resource state conflict
`Gone`	410	Resource expired/deleted
`ServerError`	500	Internal server error

Common Error Codes

i18N Key	Description	Typical Cause
`UNAUTHORIZED`	Invalid/missing token	Authentication failure
`MATCH_NOT_FOUND`	Match doesn't exist	Invalid matchId
`MATCH_EXPIRED`	Match has expired	Match TTL exceeded
`MATCH_ALREADY_FINISHED`	Match completed	Duplicate finish attempt
`INVALID_RESULTS`	Invalid match results	Data validation failure
`INVALID_REQUEST`	Malformed request	JSON/schema validation
`INVALID_CREDENTIALS`	Wrong API keys	Authentication Service error
`SERVER_ERROR`	Internal error	System/network issues

Schema Extensions

Custom Validation

Some schemas may include additional validation rules beyond the basic type requirements:

Match Results Validation

interface ResultsValidation {
  // All players must have unique places
  uniquePlaces: boolean;
  
  // Places must be consecutive starting from 1
  consecutivePlaces: boolean;
  
  // All playerIds must exist in the match
  validPlayerIds: boolean;
  
  // Scores must be numeric
  numericScores: boolean;
}

Player Status Transitions

// Valid status transitions for players
const validTransitions = {
  'Pending': ['Active', 'Inactive', 'Disconnected'],
  'Active': ['Inactive', 'Disconnected'], 
  'Inactive': ['Active', 'Disconnected'],
  'Disconnected': ['Active', 'Inactive']
};

Field Constraints

String Fields

Maximum lengths: Vary by field and implementation
Character sets: UTF-8 encoding supported
Empty values: Generally not allowed for required fields

Numeric Fields

Precision: Scores support decimal values
Range: Places must be positive integers
Special values: NaN and Infinity not allowed

URL Fields

Protocols: HTTP and HTTPS supported
Validation: Must be valid URL format
Accessibility: Should be publicly accessible

Integration Examples

TypeScript Interfaces

interface Player {
  id: string;
  name: string;
  status: 'Active' | 'Pending' | 'Inactive' | 'Disconnected';
  imgAvatarUrl?: string;
}

interface GameMatch {
  matchId: string;
  gameCode: string;
  players: Player[];
}

interface GameMatchFinishRequest {
  results: Array<{
    playerId: string;
    place: number;
    score: number;
  }>;
}

interface MachineTokenRequest {
  apiKey: string;
  secretKey: string;
}

interface OAuthMachineTokenResponse {
  data: {
    token: string;
    expires: string;
  };
}

interface ErrorEnvelope {
  errors: Array<{
    i18N: string;
    error: string;
    type: string;
  }>;
}

JSON Schema Validation

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "GameMatchFinishRequest",
  "type": "object",
  "required": ["results"],
  "properties": {
    "results": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "required": ["playerId", "place", "score"],
        "properties": {
          "playerId": {
            "type": "string",
            "minLength": 1
          },
          "place": {
            "type": "integer",
            "minimum": 1
          },
          "score": {
            "type": "number"
          }
        }
      }
    }
  }
}

Python Data Classes

from dataclasses import dataclass
from typing import List, Optional
from datetime import datetime

@dataclass
class Player:
    id: str
    name: str
    status: str
    img_avatar_url: Optional[str] = None

@dataclass
class GameMatch:
    match_id: str
    game_code: str
    players: List[Player]

@dataclass
class PlayerResult:
    player_id: str
    place: int
    score: float

@dataclass
class GameMatchFinishRequest:
    results: List[PlayerResult]

@dataclass
class TokenData:
    token: str
    expires: datetime

@dataclass
class OAuthMachineTokenResponse:
    data: TokenData

Get Match: Using GameMatch schema
Finish Match: Using GameMatchFinishRequest schema
Authentication: Using token-related schemas
Error Handling: Using ErrorEnvelope schema

05 September 2025

Data Schemas

Overview

Common Patterns

Core Schemas

Player

Fields

Player Status Values

Validation Rules

GameMatch

Fields

Game Code Values

Validation Rules

Request Schemas

GameMatchFinishRequest

Fields

Player Result Object

Validation Rules

Example Validation

MachineTokenRequest

Fields

Validation Rules

Response Schemas

OAuthMachineTokenResponse

Fields

Usage

ErrorEnvelope

Fields

Error Object

Error Types

Common Error Codes

Schema Extensions

Custom Validation

Match Results Validation

Player Status Transitions

Field Constraints

String Fields

Numeric Fields

URL Fields

Integration Examples

TypeScript Interfaces

JSON Schema Validation

Python Data Classes

Related Documentation