CodingKey로 JSON 키 매핑하기

 
 

🍏 CodingKey란?

---

CodingKey는 Swift에서 Codable프로토콜을 사용할 때, JSON의 키와 Swift 프로퍼티명이 다를 경우 이를 매핑해주는 열거형이다.

 
 

🍎 Codable은 뭘까?

---

Codable은 Decodable과 Encodable을 함께 채택한 프로토콜이다.

• Decodable: 외부 데이터를 Swift 객체로 변환
• Encodable: Swift 객체를 외부 형식(JSON 등)으로 변환

참고로 CodingKey는 Codable 내부에 속한 건 아니지만, Encodable, Decodable을 구현할 때 함께 사용하는 보조 프로토콜이다.

 
 

🤔 왜 CodingKey가 필요할까?

---

예를 들어 아래와 같은 JSON 데이터가 있다고 하자.

{
  "book_title": "Harry Potter and the Goblet of Fire",
  "release_date": "2025-06-19",
  "page_count": 734
}

 
Swift에서는 보통 카멜케이스를 사용하기 때문에, 아래처럼 모델을 만들게 된다.

struct Book: Codable {
  let title: String
  let releaseDate: String
  let pageCount: Int
}

하지만 이 코드는 디코딩 에러가 발생한다.
 

왜냐하면 JSON 키는 스네이크 케이스(release_date), Swift 프로퍼티는 카멜케이스(releaseDate)로 서로 일치하지 않기 때문이다.

 
 

해결 방법: CodingKey 사용

---

이럴 때 CodingKey를 사용하면, JSON 키와 Swift 프로퍼티명을 매핑할 수 있다.

struct Book: Codable {
  let title: String
  let author: String
  let releaseDate: String
  let pageCount: Int

  enum CodingKeys: String, CodingKey {
    case author
    case title = "book_title"
    case releaseDate = "release_date"
    case pageCount = "page_count"
  }
}

• book_title → title
• release_date → releaseDate
• page_count → pageCount

이렇게 원하는 프로퍼티명으로 값을 매핑할 수 있다.
 
 

🧐 일부만 작성하면 안 될까?

---

아래 코드에서 author는 이름이 같아서 매핑할 필요가 없어 보인다.

enum CodingKeys: String, CodingKey {
  case author
  case title = "book_title"
  case releaseDate = "release_date"
  case pageCount = "page_count"
}

그럼 이런 생각을 할 수도 있다. “얘는 값도 변하지 않는데, 안적고 생략하면 되는거 아닌가?”
 
결론은.. 🙂‍↔️ 안된다. ㅎ..
 

이유는 CodingKeys를 선언하는 순간, Swift는 자동 매핑을 중단하고, 오직 CodingKeys에 정의된 키만 사용하게된다.

 

즉, author를 생략하면 해당 프로퍼티는 무시되어 디코딩되지 않는다.

 

그러니, 하나 이상의 프로퍼티가 매핑이 필요하다면, 매핑이 필요 없는 프로퍼티라도 CodingKeys에 반드시 작성해주어야 한다.

 
 

String과 CodingKey의 순서 주의!

---

enum에서 CodingKey를 쓸 때는 순서를 주의해야 한다. 예시를 보자.

enum CodingKeys: String, CodingKey { ... } // ✅ 올바른 선언

 
원래는 이런식으로 작성해야한다. 하지만, 이 순서를 아래처럼 반대로 해준다면?

enum CodingKeys: CodingKey, String { ... } // ❌ 에러 발생

 

Error..!

이렇게 에러가 발생한다. 해석하자면, “Raw 타입인 ‘String’은 enum의 선언부에서 첫 번째에 와야 한다."
 
왜 이런 에러가 발생할까? 하고 찾아봤는데, Swift에서 Raw값을 지정해주면 내부적으로 RawRepresentable 프로토콜이 자동으로 채택된다고 한다.
 
이 RawRepresentable은 컴파일러가 enum을 처리할 때 Raw 타입이 맨 앞에 있어야 한다는 전제를 가진다.
 

그렇기에 Swift에서 enum이 Raw타입(String)과 프로토콜(CodingKey)를 함께 채택할 때는, 반드시 Raw타입을 먼저 작성하고, 그 다음에 다른 프로토콜(CodingKey)를 적어야 한다.

 

💡 RawRepresentable은 열거형(enum)이 String이나 Int같은 원시값(RawValue)을 가질 수 있게 해주는 프로토콜이며, enum에 원시값을 지정하면 자동으로 채택되는 프로토콜이다.

 
 

💡 정리

• CodingKey는 JSON 키와 Swift 프로퍼티를 매핑해주는 열거형
• Codable은 Decodable + Encodable을 통합한 프로토콜
• CodingKeys를 정의하면 모든 프로퍼티를 명시적으로 작성해야 함
• enum이 Raw타입과 프로토콜을 함께 채택할 경우, Raw타입을 앞에 작성해야 함 (RawRepresentable 때문)