SCORM Package Validation and Requirements Guide

Overview

This guide explains the validation requirements for SCORM packages uploaded to the SCORM API, common validation errors, and how to ensure your packages are compatible.

Package Requirements

File Format

• Format: ZIP archive (.zip)
• Maximum Size: 10 GB (configurable)
• Structure: Must contain imsmanifest.xml at root level

Required Files

1. imsmanifest.xml (Required)

   • Must be at the root of the ZIP file
   • Must be valid XML
   • Must conform to SCORM manifest specification

2. Launch File (Required)

   • Referenced in manifest
   • Must exist in package
   • Must be accessible

Supported SCORM Versions

• SCORM 1.2: Full support
• SCORM 2004: Full support (all editions)

Package Structure

Valid SCORM Package Structure

package.zip
├── imsmanifest.xml          (Required - at root)
├── index.html               (Launch file - example)
├── assets/
│   ├── css/
│   │   └── styles.css
│   ├── js/
│   │   └── scorm-api.js
│   └── images/
│       └── logo.png
└── content/
    └── pages/
        └── page1.html

Common Invalid Structures

❌ Missing Manifest:

package.zip
├── index.html
└── assets/

Error: MISSING_MANIFEST

❌ Manifest in Subdirectory:

package.zip
├── content/
│   └── imsmanifest.xml  (Wrong location)
└── index.html

Error: MISSING_MANIFEST (manifest must be at root)

❌ Corrupted ZIP:

package.zip (corrupted or invalid ZIP format)

Error: INVALID_FILE_TYPE or PARSE_FAILED

Manifest Requirements

SCORM 1.2 Manifest Structure

<?xml version="1.0" encoding="UTF-8"?>
<manifest identifier="MANIFEST-001" version="1.0"
  xmlns="http://www.imsproject.org/xsd/imscp_rootv1p1p2"
  xmlns:adlcp="http://www.adlnet.org/xsd/adlcp_rootv1p2"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.imsproject.org/xsd/imscp_rootv1p1p2 imscp_rootv1p1p2.xsd
                      http://www.imsglobal.org/xsd/imsmd_rootv1p2p1 imsmd_rootv1p2p1.xsd
                      http://www.adlnet.org/xsd/adlcp_rootv1p2 adlcp_rootv1p2.xsd">
  
  <metadata>
    <schema>ADL SCORM</schema>
    <schemaversion>1.2</schemaversion>
    <lom xmlns="http://www.imsglobal.org/xsd/imsmd_rootv1p2p1">
      <general>
        <identifier>
          <catalog>URI</catalog>
          <entry>http://example.com/package-001</entry>
        </identifier>
        <title>
          <langstring xml:lang="en-US">Course Title</langstring>
        </title>
      </general>
    </lom>
  </metadata>
  
  <organizations default="TOC1">
    <organization identifier="TOC1">
      <title>Course Title</title>
      <item identifier="ITEM1" identifierref="RES1">
        <title>Lesson 1</title>
      </item>
    </organization>
  </organizations>
  
  <resources>
    <resource identifier="RES1" type="webcontent" adlcp:scormtype="sco" href="index.html">
      <file href="index.html"/>
    </resource>
  </resources>
</manifest>

SCORM 2004 Manifest Structure

<?xml version="1.0" encoding="UTF-8"?>
<manifest identifier="MANIFEST-001" version="1.0"
  xmlns="http://www.imsglobal.org/xsd/imscp_v1p1"
  xmlns:adlcp="http://www.adlnet.org/xsd/adlcp_v1p3"
  xmlns:adlseq="http://www.adlnet.org/xsd/adlseq_v1p3"
  xmlns:adlnav="http://www.adlnet.org/xsd/adlnav_v1p3"
  xmlns:imsss="http://www.imsglobal.org/xsd/imsss"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="...">
  
  <metadata>
    <schema>ADL SCORM</schema>
    <schemaversion>CAM 1.3</schemaversion>
    <!-- Additional metadata -->
  </metadata>
  
  <organizations default="TOC1">
    <organization identifier="TOC1">
      <title>Course Title</title>
      <item identifier="ITEM1" identifierref="RES1">
        <title>Lesson 1</title>
      </item>
    </organization>
  </organizations>
  
  <resources>
    <resource identifier="RES1" type="webcontent" adlcp:scormtype="sco" href="index.html">
      <file href="index.html"/>
    </resource>
  </resources>
</manifest>

Validation Process

Upload Validation

When a package is uploaded, the API performs these checks:

1. File Type Validation

   • ✅ File is a ZIP archive
   • ✅ File extension is .zip
   • ❌ Error: INVALID_FILE_TYPE if not ZIP

2. File Size Validation

   • ✅ File size ≤ 10 GB (configurable)
   • ❌ Error: FILE_TOO_LARGE if exceeds limit

3. ZIP Extraction

   • ✅ ZIP file can be extracted
   • ✅ No corrupted entries
   • ❌ Error: PARSE_FAILED if extraction fails

4. Manifest Location

   • ✅ imsmanifest.xml exists at root
   • ✅ Case-insensitive match (imsmanifest.xml, IMSManifest.xml, etc.)
   • ❌ Error: MISSING_MANIFEST if not found

5. XML Parsing

   • ✅ Manifest is valid XML
   • ✅ Well-formed XML structure
   • ❌ Error: INVALID_XML if parsing fails

6. SCORM Version Detection

   • ✅ Version detected (1.2 or 2004)
   • ✅ Valid SCORM namespace/schema
   • ❌ Error: UNKNOWN_VERSION if version cannot be determined

7. Launch URL Extraction

   • ✅ Launch URL found in manifest
   • ✅ Launch file exists in package
   • ❌ Error: MISSING_LAUNCH_URL if not found

8. Metadata Extraction

   • ✅ Title extracted (or default "Untitled SCORM Package")
   • ✅ Description extracted (optional)
   • ✅ SCO count calculated

Validation Response

Success Response (201):

{
  "id": "package-uuid",
  "tenant_id": "tenant-uuid",
  "title": "Course Title",
  "version": "1.2",
  "launch_url": "index.html",
  "manifest_url": "https://storage.../imsmanifest.xml",
  "storage_path": "tenant/package/...",
  "file_size_bytes": 10485760,
  "created_at": "2025-01-12T10:00:00Z"
}

Error Response (400):

{
  "error": "Missing imsmanifest.xml file",
  "code": "MISSING_MANIFEST",
  "details": {
    "file": "package.zip",
    "expected_location": "root"
  }
}

Common Validation Errors

MISSING_MANIFEST

Cause: imsmanifest.xml not found at root of ZIP file.

Solutions:

• Ensure imsmanifest.xml is at the root level (not in a subdirectory)
• Check file name is exactly imsmanifest.xml (case-insensitive)
• Verify ZIP structure before uploading

Check Package Structure:

# List ZIP contents
unzip -l package.zip | grep -i manifest

# Should show:
# imsmanifest.xml

INVALID_XML

Cause: Manifest XML is malformed or invalid.

Solutions:

• Validate XML syntax before packaging
• Check for unclosed tags
• Verify XML encoding (UTF-8 recommended)
• Use XML validator tool

Validate XML:

# Check XML syntax
xmllint --noout imsmanifest.xml

# Or use online validator

UNKNOWN_VERSION

Cause: SCORM version cannot be determined from manifest.

Solutions:

• Ensure manifest includes SCORM schema declaration
• Check schemaversion element matches SCORM version
• Verify namespace declarations are correct
• Use SCORM-compliant authoring tool

Check Schema Version:

<metadata>
  <schema>ADL SCORM</schema>
  <schemaversion>1.2</schemaversion>  <!-- For SCORM 1.2 -->
  <!-- OR -->
  <schemaversion>CAM 1.3</schemaversion>  <!-- For SCORM 2004 -->
</metadata>

MISSING_LAUNCH_URL

Cause: Launch URL not found in manifest or file doesn't exist.

Solutions:

• Ensure href attribute in resource points to valid file
• Verify launch file exists in package
• Check file paths are relative (not absolute)
• Ensure no special characters in file paths

Check Launch URL:

<resource identifier="RES1" href="index.html">
  <file href="index.html"/>
</resource>

INVALID_FILE_TYPE

Cause: Uploaded file is not a ZIP archive.

Solutions:

• Ensure file is a valid ZIP archive
• Check file extension is .zip
• Re-zip the package if corrupted
• Verify ZIP file can be opened locally

FILE_TOO_LARGE

Cause: Package exceeds maximum size limit (default 10 GB).

Solutions:

• Reduce package size (compress assets, remove unused files)
• Use multipart upload for large files
• Request quota increase if justified
• Split large packages into multiple smaller packages

PARSE_FAILED

Cause: Package processing failed (extraction, parsing, or validation).

Solutions:

• Verify ZIP file is not corrupted
• Check package structure is valid
• Ensure all referenced files exist
• Test package with SCORM validator tool

Pre-Upload Validation

Validate Package Locally

Before uploading, validate your package:

1. Check ZIP Structure:

# List contents
unzip -l package.zip

# Extract and verify
unzip -t package.zip  # Test ZIP integrity
unzip package.zip -d test/
ls test/ | grep -i manifest  # Should show imsmanifest.xml

2. Validate Manifest XML:

# Extract manifest
unzip -p package.zip imsmanifest.xml > manifest.xml

# Validate XML
xmllint --noout manifest.xml

# Check SCORM version
grep -i "schemaversion" manifest.xml

3. Verify Launch File:

# Extract manifest
unzip -p package.zip imsmanifest.xml > manifest.xml

# Find launch URL
grep -i "href" manifest.xml

# Verify file exists
unzip -l package.zip | grep "index.html"  # Or your launch file

Use SCORM Validator Tools

Recommended Tools:

• SCORM Cloud: Upload and validate packages
• ADL Test Suite: Official SCORM validation tool
• Reload Editor: SCORM authoring tool with validation

Package Best Practices

1. File Organization

• Root Level: Keep imsmanifest.xml at root
• Relative Paths: Use relative paths for all resources
• No Absolute Paths: Avoid absolute file paths
• Consistent Naming: Use lowercase, no spaces in filenames

2. Manifest Quality

• Complete Metadata: Include title, description
• Valid Schema: Use correct SCORM schema version
• Proper Namespaces: Include all required namespaces
• Valid XML: Ensure well-formed XML

3. Resource References

• Valid Hrefs: All href attributes must point to existing files
• Relative Paths: Use relative paths from package root
• Case Sensitivity: Be consistent with case (some systems are case-sensitive)

4. File Size Optimization

• Compress Assets: Optimize images, videos, audio
• Remove Unused Files: Don't include unnecessary files
• Minify Code: Minify JavaScript and CSS
• External Resources: Consider hosting large assets externally

5. Testing Before Upload

• Local Testing: Test package locally first
• SCORM Validator: Use validator tools
• Multiple Browsers: Test in different browsers
• SCORM API: Verify SCORM API communication works

Validation-Only Mode

You can validate a package without processing it:

curl -X POST https://api.scorm.com/api/v1/packages/process \
  -H "X-API-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "tenant-uuid",
    "uploaded_by": "user-id",
    "storage_path": "tenant/uploads/temp.zip",
    "original_filename": "package.zip",
    "validate_only": true
  }'

Response:

{
  "valid": true,
  "version": "1.2",
  "title": "Course Title",
  "launch_url": "index.html",
  "sco_count": 1,
  "metadata": {
    "description": "Course description",
    "duration": "PT1H30M"
  }
}

Troubleshooting Validation Errors

Issue: Package Validates But Won't Launch

Causes:

• Launch file missing SCORM API implementation
• Incorrect launch URL path
• CORS issues with assets
• JavaScript errors in content

Solutions:

• Verify SCORM API Bridge is included
• Check launch URL is correct
• Test launch file in browser
• Review browser console for errors

Issue: Manifest Validates But Metadata Missing

Causes:

• Metadata section incomplete
• Missing title element
• Invalid metadata structure

Solutions:

• Ensure <metadata> section is complete
• Include <title> in manifest
• Use proper LOM (Learning Object Metadata) structure

Issue: Package Works Locally But Fails Validation

Causes:

• Absolute paths in manifest
• External resource dependencies
• Platform-specific file paths

Solutions:

• Use relative paths only
• Include all dependencies in package
• Test on target platform

SCORM Compliance Checklist

Before uploading, verify:

• Package is a valid ZIP archive
• imsmanifest.xml exists at root
• Manifest XML is well-formed
• SCORM version is correctly specified
• Launch URL is valid and file exists
• All resource files referenced in manifest exist
• File paths are relative (not absolute)
• Package size is within limits
• No special characters in file paths
• SCORM API implementation is included (for player)

Package Validation API

Validate Endpoint

POST /api/v1/packages/process
Content-Type: application/json
X-API-Key: your-key

{
  "tenant_id": "tenant-uuid",
  "uploaded_by": "user-id",
  "storage_path": "tenant/uploads/package.zip",
  "original_filename": "package.zip",
  "validate_only": true
}

Validation Response

Valid Package:

{
  "valid": true,
  "version": "1.2",
  "title": "Course Title",
  "launch_url": "index.html",
  "sco_count": 1,
  "metadata": {
    "description": "Course description"
  }
}

Invalid Package:

{
  "valid": false,
  "error": "Missing imsmanifest.xml file",
  "code": "MISSING_MANIFEST",
  "details": {
    "expected_location": "root"
  }
}

Last Updated: 2025-01-12
Version: 1.0

For package upload instructions, see Upload Your First Package.