JSON 스타일 가이드라인

lang/js

JSON 스타일 가이드라인

C/H 2018. 6. 16. 08:30

자바스크립트 언어 자료

JSON 스타일 가이드라인

JSON에서 가장 중요한 것은 상호운용성이다. 그러므로 JSON 데이터 피드를 수신자 측에서 바라는 형태로 제공하는 것이 중요하다. Google은 JSON 스타일 가이드(https://google.github.io/styleguide/jsoncstyleguide.xml)를 배포하여 모범 사례를 공유하고 유지보수성을 향상시키는 데 기여하고 있다.
Google의 JSON 스타일 가이드는 매우 광범위하지만, API 설계자 및 개발자에게 가장 중요한 것을 꼽자면 다음과 같다.

속성이름
날짜 속성값
열거형 값

속성 이름

속성 이름은(Google의 표현을 따르자면) 이름 값 쌍에서 콜론 왼쪽에 위치한다(속성 값은 콜론의 오른쪽). JSON의 속성 이름을 짓는 주요 스타일은 다음과 같은 두 가지 방법이 있다.

lowerCamelCase
snake_case

lowerCamelCase는 여러 단어를 붙여쓰되, 첫 단어를 제외한 각 단어의 첫 글자를 대문자로 한다. Java와 JavaScritp 커뮤니티 코딩 가이드에서 볼 수 있다.
snake_case는 모든 글자를 소문자로 하되 단어와 단어 사이를 언더스크오(_)로 연결한다. Ruby on Rails 커뮤니티에서 이를 많이 볼 수 있다.
Google 및 RESTful API 대부분에서는 속성 이름에 lowerCamelCase를 사용한다.

{
    "firstName": "John Smith"
}

날짜 속성 값

Google의 JSON 스타일 가이드sms RFC 3339를 준수하는 것을 선호한다.

{
    "dateRegisterd": "2018-06-08T23:46:11-05:00"
}

위 날자 표현은, UTC/GMT(coordinated Universal Time)와의 시간차가 -5시간, 즉 미국 동부표준시라는 것을 알 수 있다. RFC 3339는 ISO 8601의 요약본으로, 양자 간의 주된 차이는 ISO 8601(http://www.iso.org/iso/home/standards/iso8601.html)이 T(날짜와 시간 사이의)를 공백문자로 대체할 수 있다는 점이다. RFC 3339에서는 이것이 허용되지 않는다.

위도 및 경도 값

지리 API(예: Google Maps 등)나 지리 정보시스템(GIS)과 관련된 API는 위도 및 경도 데이터를 자주 다룬다. Google JSON 스타일 가이드에서는 일관성을 위해 위도 경도 데이터를 ISO 6709(http://en.wikipedia.org/wiki/ISO_6709) 표준을 준수하여 다루라고 권고하고 있다. Google Maps는 뉴욕 시 엠파이어스테이트 빌딩의 좌표를 북위 40.748747, 서경 73.985547도라 나타내고 있는데 이를 JSON으로 나타내면 아래와 같다.

{
    "empireStateBuilding": "40.748747-73.985547"    
}

위는 다음과 같은 원칙에 따라 +-DD.DDDD+-DDD.DDDD 포멧으로 위도 경도를 나타낸다.

위도를 먼저 표기한다.
북위가 양수이다.
동경이 양수이다.
위도 및 경도 값은 문자열로 나타낸다. 음수 기호 때문에 숫자로 취급할 수 없다.

들여쓰기

Google JSON 스타일 가이드는 들여쓰기에 대해서 특별히 언급하지 않지만, 여기에도 몇가지 원칙이 있다.

JSON은 직렬화를 위한 포멧이지 보여주기 위한 포멧이 아니다. 그러므로 API 제공 측과 사용 측 사이에서 들여쓰기는 의가 없다.
대부분의 JSON 포메터는 JSON을 보기 좋게 정리할 때 2글자에서 4글자 사이로 들여쓰기를 선택할 수 있게끔 한다.
JSON은 JavaScript(ECMA 262 표준의일부)로부터 왔다. 그러나 JavaScript커뮤니티와 조율이 된 부분은 아무것도 없다.
대부분의 개발자와 코딩 스타일 가이드 문서는 2글자 공백문자를 선호한다. 하지만 다른 스타일을 사용하고 싶다면 그렇게 해도 무방하다.
다만, 일관성을 지키는 것이 중요하다.