What is field-name-mapper?

The Field Name Mapper is a specialized Claude skill designed to bridge data structure gaps between Web APIs and mobile platforms (Android/iOS). It streamlines the process of resolving field name inconsistencies, handling naming convention conflicts like snake_case vs camelCase, and ensuring seamless data synchronization through automated request aliasing and response transformation patterns.

When should I use field-name-mapper?

field-name-mapper is useful in the following scenarios: • Resolving mismatches where mobile clients send field names different from what the backend API expects (e.g., Android sending 'name' while API expects 'certName'). • Transforming backend database responses (like Prisma objects) into mobile-ready formats by renaming keys to match frontend data models. • Standardizing data types across platforms, such as converting backend Date objects into ISO-compliant strings for mobile consumption. • Implementing 'alias' support in API controllers to allow a single endpoint to accept multiple naming variations from different client versions. • Debugging integration issues by comparing server-side request logs with mobile-side data class definitions to identify missing or renamed fields.

name	field-name-mapper
description	Map field names between Web API and Android/iOS when they differ. Fix issues where Android sends 'name' but API expects 'certName', or API returns 'project_name' but Android expects 'projectName'. Handle both request and response field mapping.
allowed-tools	Read, Grep, Edit

Field Name Mapper

Purpose

Fix field name mismatches between platforms when:

Android sends field with different name than API expects
API returns field with different name than mobile expects
snake_case vs camelCase conversion issues

Common Patterns

Android Request Field Differs from API

Problem: Android sends name, API expects certName

Android Model:

data class CreateCertificationRequest(
    val name: String,  // Android convention
    val certificateNumber: String?
)

API Expects:

const { certName, certNumber } = body  // Different names!

Fix in API - Accept both:

const {
    certName,
    name,  // Android alias
    certNumber,
    certificateNumber  // Android alias
} = body

// Use whichever was provided
const finalCertName = certName || name
const finalCertNumber = certNumber || certificateNumber

API Response Field Differs from Mobile Model

Problem: API returns certName, Android expects name

API Returns:

return { certName: 'Test Cert', certNumber: '123' }

Android Expects:

data class Certification(
    val name: String,  // Expects 'name', not 'certName'
    val certificateNumber: String?
)

Fix in API - Transform response:

return {
    name: cert.certName,  // Map to Android field name
    certificateNumber: cert.certNumber
}

Field Mapping Reference

Common Mappings (Prisma → Mobile)

Prisma/Web	Android	iOS
`certName`	`name`	`name`
`certNumber`	`certificateNumber`	`certificateNumber`
`_count.items`	`itemCount`	`itemCount`
`created_at`	`createdAt`	`createdAt`
`user_id`	`userId`	`userId`

Date Field Patterns

Prisma returns Date objects, serialize to ISO string:

// Prisma returns: Date object
// Android expects: "2024-01-15" or "2024-01-15T10:30:00Z"

return {
    date: record.date.toISOString().split('T')[0],  // Date only
    createdAt: record.createdAt.toISOString()  // Full datetime
}

Accepting Multiple Field Names

Pattern for accepting both web and mobile field names:

const body = await request.json()
const {
    // Web naming
    certName,
    certNumber,

    // Mobile naming (aliases)
    name,
    certificateNumber,

    // Date fields - accept both
    date,
    scheduledDate,  // Android might send this

    // Title vs Name
    title,
    listName  // Web might use this
} = body

// Resolve to final values
const finalName = certName || name
const finalNumber = certNumber || certificateNumber
const finalDate = date || scheduledDate
const finalTitle = title || listName

Transform Function Pattern

Create transform functions for consistent mobile responses:

function transformCertification(cert: PrismaCert): MobileCert {
    return {
        id: cert.id,
        name: cert.certName,  // Prisma → Mobile mapping
        certificateNumber: cert.certNumber,
        issuingAuthority: cert.issuingAuthority,
        issueDate: cert.issueDate?.toISOString().split('T')[0] ?? null,
        expiryDate: cert.expiryDate?.toISOString().split('T')[0] ?? null,
        status: cert.status,
        createdAt: cert.createdAt.toISOString()
    }
}

// Use in API response
return NextResponse.json(transformCertification(cert))

Debugging Field Mismatches

Check What Android Sends

Look at server logs for request body:

console.log('Request body:', JSON.stringify(body, null, 2))

Check What API Returns

Compare API response to Android model:

# Make API call directly
curl -X GET http://localhost:3000/api/certifications \
    -H "Authorization: Bearer $TOKEN" | jq

Check Android Model Requirements

# Find Android model
grep -A 30 "data class Certification" apps/android/**/model/*.kt

Look for:

Fields without default values (required)
@SerialName annotations (expect snake_case)
Field names differ from Prisma

Quick Fix Checklist

When fixing a field mismatch:

Identify the exact field name mismatch
Check if API needs to accept alias in request
Check if API needs to rename in response
Update API to handle both names
Add transform function if multiple fields differ
Test with actual mobile request

field-name-mapper

When & Why to Use This Skill

Use Cases