# WIA-EDU-014 Game-Based Learning Standard v1.0

## Phase 1: Data Format & Game Design

**Status:** ✅ Complete
**Version:** 1.0.0
**Date:** 2025-12-25
**Philosophy:** 弘益人間 (Benefit All Humanity)

---

## 1. Overview

This specification defines the foundational data format requirements for WIA-compliant game-based learning systems. Phase 1 establishes JSON schemas for game metadata, player profiles, progress tracking, achievements, and assessment data.

## 2. Scope

Phase 1 covers:
- Game metadata and descriptive information
- Player profile and preference data
- Progress tracking and session data
- Achievement and badge systems
- Assessment and learning analytics data
- Content structure and challenges

## 3. Game Metadata Schema

### 3.1 Base Game Metadata

All educational games MUST include comprehensive metadata in JSON format:

```json
{
  "id": "game_unique_id",
  "standard": "WIA-EDU-014",
  "version": "1.0",
  "title": "Game Title",
  "type": "educational-game",
  "category": "puzzle|simulation|adventure|strategy|quiz",
  "subject": "mathematics|science|language|history|coding",
  "topics": ["topic1", "topic2"],
  "gradeLevel": {"min": 6, "max": 8},
  "difficulty": "beginner|intermediate|advanced",
  "targetAge": {"min": 11, "max": 14},
  "language": ["en", "es", "fr", "ko"],
  "platform": ["web", "ios", "android", "desktop"],
  "accessibility": {
    "wcagLevel": "AA",
    "features": ["screen-reader", "high-contrast", "subtitles", "keyboard-nav"]
  },
  "learningObjectives": [
    {
      "id": "obj1",
      "description": "Learning objective description",
      "standard": "CCSS.Math.7.EE.A.1"
    }
  ],
  "metadata": {
    "created": "2025-12-25T00:00:00Z",
    "updated": "2025-12-25T00:00:00Z",
    "author": "Developer Name",
    "publisher": "Publisher Name",
    "license": "MIT"
  }
}
```

### 3.2 Required Fields

- `id` (string): Unique identifier following pattern `game_[a-z0-9]+`
- `standard` (string): Must be "WIA-EDU-014"
- `version` (string): Semantic version (e.g., "1.0")
- `title` (string): Human-readable game title
- `type` (enum): Game classification
- `subject` (enum): Primary subject area
- `accessibility` (object): WCAG compliance information

## 4. Player Profile Schema

### 4.1 Player Profile Structure

```json
{
  "playerId": "player_unique_id",
  "username": "display_name",
  "demographics": {
    "age": 12,
    "grade": 7,
    "location": {"country": "US", "region": "CA"}
  },
  "preferences": {
    "difficulty": "adaptive|easy|medium|hard",
    "soundEnabled": true,
    "musicVolume": 0.7,
    "notificationsEnabled": true,
    "language": "en"
  },
  "accessibility": {
    "screenReader": false,
    "highContrast": false,
    "extendedTime": false,
    "alternativeInput": false,
    "fontSize": "medium|large|xlarge"
  },
  "learningProfile": {
    "style": "visual|auditory|kinesthetic|reading",
    "pace": "slow|moderate|fast",
    "strengths": ["skill1", "skill2"],
    "growthAreas": ["skill3", "skill4"]
  },
  "privacy": {
    "dataCollection": "consented|parent-consented|declined",
    "consentDate": "2025-12-25T00:00:00Z",
    "shareWithTeachers": true,
    "shareWithPeers": false
  }
}
```

## 5. Progress Tracking Schema

### 5.1 Session Progress

```json
{
  "sessionId": "session_unique_id",
  "playerId": "player_xyz789",
  "gameId": "game_abc123",
  "startTime": "2025-12-25T14:00:00Z",
  "endTime": "2025-12-25T14:45:00Z",
  "duration": "PT45M",
  "currentLevel": 15,
  "totalLevels": 50,
  "completionPercentage": 30,
  "performance": {
    "score": 450,
    "accuracy": 78,
    "problemsSolved": 15,
    "hintsUsed": 3,
    "attemptsAverage": 1.8
  },
  "skillProgress": [
    {
      "skillId": "linear-equations",
      "mastery": 90,
      "status": "mastered|developing|beginning",
      "lastPracticed": "2025-12-25T14:30:00Z"
    }
  ]
}
```

### 5.2 Cumulative Progress

```json
{
  "playerId": "player_xyz789",
  "gameId": "game_abc123",
  "totalPlayTime": "PT12H30M",
  "sessionsCompleted": 24,
  "lastPlayed": "2025-12-25T14:45:00Z",
  "achievements": ["badge1", "badge2"],
  "levelHistory": [
    {
      "level": 1,
      "completedAt": "2025-12-20T15:00:00Z",
      "attempts": 2,
      "score": 85
    }
  ]
}
```

## 6. Achievement System

### 6.1 Achievement Definition

```json
{
  "achievementId": "badge_unique_id",
  "type": "completion|mastery|performance|persistence|collaboration|innovation",
  "name": "Achievement Name",
  "description": "Achievement description",
  "iconUrl": "https://cdn.example.com/badges/badge.png",
  "criteria": {
    "skillsMastered": ["skill1", "skill2"],
    "minAccuracy": 85,
    "minProblems": 100,
    "minPlayTime": "PT10H"
  },
  "points": 100,
  "rarity": "common|uncommon|rare|legendary"
}
```

### 6.2 Achievement Award Record

```json
{
  "awardId": "award_unique_id",
  "achievementId": "badge_algebra_master",
  "playerId": "player_xyz789",
  "earnedDate": "2025-12-25T14:30:00Z",
  "evidence": {
    "score": 95,
    "challengesCompleted": 120,
    "accuracy": 92
  },
  "verifiable": true,
  "credentialUrl": "https://verify.wia.com/vc/abc123"
}
```

## 7. Assessment Data

### 7.1 Assessment Event

```json
{
  "assessmentId": "assess_unique_id",
  "type": "formative|summative|diagnostic|adaptive",
  "playerId": "player_xyz789",
  "challengeId": "ch_15_01",
  "timestamp": "2025-12-25T14:30:00Z",
  "response": "student answer or action",
  "correctAnswer": "expected answer",
  "isCorrect": true,
  "score": 10,
  "maxScore": 10,
  "timeSpent": 45,
  "hintsUsed": 1,
  "skillsAssessed": ["linear-equations", "algebraic-reasoning"]
}
```

## 8. Content Structure

### 8.1 Level Definition

```json
{
  "levelId": "level_15",
  "gameId": "game_abc123",
  "title": "Level Title",
  "difficulty": 6,
  "learningObjectives": ["obj1", "obj2"],
  "challenges": [
    {
      "challengeId": "ch_15_01",
      "type": "equation-solving|multiple-choice|drag-drop|simulation",
      "question": "Challenge prompt",
      "correctAnswer": "answer",
      "hints": ["hint1", "hint2"],
      "feedback": {
        "correct": "Positive feedback",
        "incorrect": "Corrective feedback"
      },
      "points": 10,
      "timeLimit": 120
    }
  ],
  "requiredScore": 80,
  "rewards": {
    "points": 100,
    "badge": "badge_id"
  }
}
```

## 9. Data Validation

All data structures MUST be validated against JSON Schema definitions. Implementations MUST:
- Reject invalid data with clear error messages
- Use ISO 8601 format for all dates and times
- Use ISO 8601 duration format (PT notation) for time periods
- Follow WIA naming conventions for all IDs (prefix_alphanumeric)
- Encrypt personally identifiable information at rest and in transit

## 10. Privacy Requirements

### 10.1 Data Minimization
Collect only data necessary for educational purposes. PII MUST be:
- Separated from learning analytics data
- Encrypted at rest
- Transmitted only over TLS 1.3
- Deleted upon request (right to erasure)

### 10.2 Consent Management
```json
{
  "playerId": "player_xyz789",
  "consents": [
    {
      "type": "data-collection",
      "granted": true,
      "grantedBy": "parent|student",
      "grantedAt": "2025-12-25T00:00:00Z",
      "scope": ["progress", "analytics"]
    }
  ]
}
```

## 11. Compliance

Implementations MUST comply with:
- FERPA (US educational records privacy)
- COPPA (US children's online privacy)
- GDPR (EU data protection)
- WCAG 2.1 Level AA (accessibility)

---

**Status:** This specification is complete and ready for implementation.

**Next Phase:** Phase 2 defines RESTful APIs for game management and player interaction.

弘益人間 · Benefit All Humanity
© 2025 WIA - MIT License