VIA JSON 구조
키보드 JSON 파일은 어떤 정보를 담고 있으며 VIA는 어떻게 이를 해석할까?
- VIA JSON은 키보드 펌웨어가 아니라 키보드 레이아웃을 설명하는 메타데이터입니다.
- JSON에는 키 위치, 레이어, 레이아웃, 메뉴 정보 등이 저장됩니다.
- VIA는 JSON을 읽어 화면에 키보드를 그리고 사용자가 키를 변경할 수 있도록 합니다.
- 잘못된 JSON을 사용하면 키 배열이 어긋나거나 일부 기능이 정상적으로 표시되지 않을 수 있습니다.
- JSON 자체는 키보드 동작을 변경하는 것이 아니라 VIA가 장치를 이해하도록 도와주는 역할을 합니다.
VIA를 처음 사용하는 사람이라면 가장 먼저 접하는 파일이 바로 JSON입니다. 대부분은 제조사 홈페이지에서 JSON 파일을 다운로드한 뒤 VIA에 불러오기만 하면 된다고 알고 있지만, 정작 JSON 파일 안에 무엇이 들어 있는지, 왜 필요한지는 잘 알려져 있지 않습니다.
많은 사용자가 JSON을 펌웨어(Firmware)와 같은 것으로 오해하기도 합니다. 하지만 실제로는 역할이 전혀 다릅니다. 펌웨어는 키보드 내부에서 동작하는 프로그램이고, JSON은 VIA가 그 키보드를 이해하기 위한 ‘설명서’에 가깝습니다.
이번 글에서는 VIA JSON이 어떤 구조로 이루어져 있는지, 각 항목이 어떤 의미를 가지는지, VIA가 JSON을 이용해 키보드 화면을 만드는 과정까지 차근차근 살펴보겠습니다.
1. VIA JSON이란 무엇인가?
VIA JSON은 키보드 레이아웃을 설명하는 데이터 파일입니다. 확장자는 ‘.json’이며 JavaScript Object Notation이라는 데이터 표현 방식을 사용합니다. JSON 자체는 프로그래밍 언어가 아니라 사람이 읽기도 쉽고 프로그램도 쉽게 해석할 수 있도록 만든 데이터 형식입니다.
VIA는 키보드를 연결했을 때 내부 펌웨어의 Vendor ID와 Product ID를 확인한 뒤, JSON에 기록된 정보를 이용하여 화면에 키보드의 모양을 그립니다. 즉 VIA가 화면에 보여주는 키 배열은 JSON에 정의된 내용을 그대로 시각화한 결과라고 볼 수 있습니다.
중요한 점은 JSON 파일이 키보드를 제어하지 않는다는 것입니다. 실제 키 입력을 처리하는 것은 QMK 기반 펌웨어이며, JSON은 VIA 인터페이스를 구성하는 역할만 담당합니다.
JSON은 ‘키보드의 프로그램’이 아니라 ‘키보드의 설계도’입니다. VIA는 이 설계도를 읽어 사용자에게 키 배열과 설정 화면을 보여줍니다.
QMK는 키 입력을 처리하는 펌웨어를 담당하고 VIA는 설정 인터페이스를 담당합니다. 두 시스템이 서로 분리되어 있기 때문에 펌웨어를 수정하지 않고도 VIA에서 키맵을 변경할 수 있는 구조가 만들어집니다.
2. JSON 파일에는 어떤 정보가 들어 있을까?
JSON 파일은 단순히 키 위치만 저장하는 것이 아닙니다. VIA가 필요한 거의 모든 화면 정보가 이 파일 안에 포함됩니다.
이처럼 JSON은 단순히 키 하나의 위치만 설명하는 것이 아니라 키보드 전체 인터페이스를 구성하는 정보를 체계적으로 저장하고 있습니다.
3. layouts 항목의 역할
가장 중요한 항목은 layouts입니다. VIA에서 보이는 키보드 모양 대부분은 layouts 정보를 기반으로 생성됩니다.
각 키는 X좌표와 Y좌표, 너비, 높이 등의 값을 가지고 있으며 VIA는 이를 이용해 브라우저 화면 위에 키를 배치합니다.
예를 들어 Enter 키는 일반 키보다 세로 길이가 길고 Space Bar는 가로 길이가 매우 긴데, 이러한 차이 역시 layouts 안에 정의되어 있습니다.
JSON이 키 위치를 설명하기 때문에 다른 모델의 JSON을 적용하면 키 위치가 어긋나거나 일부 키가 겹쳐 보이는 현상이 발생할 수 있습니다.
4. Matrix 정보는 왜 필요할까?
겉으로 보기에는 키보드 배열만 있으면 될 것 같지만 실제 키보드는 Matrix 구조로 동작합니다.
각 키는 Row와 Column의 교차점으로 연결되어 있으며 펌웨어는 이 Matrix를 계속 스캔하면서 눌린 키를 찾습니다.
JSON 안의 Matrix 정보는 화면의 키와 실제 펌웨어 안의 위치를 연결하는 역할을 합니다. 따라서 사용자가 VIA에서 특정 키를 클릭하면 VIA는 Matrix 번호를 통해 해당 위치를 정확하게 찾아 변경 요청을 보낼 수 있습니다.
Matrix 번호는 실제 PCB 회로와 연결됩니다. 따라서 화면에서는 오른쪽 Shift를 선택했더라도 내부적으로는 특정 Row와 Column 번호를 대상으로 데이터를 전송하게 됩니다.
이번 Part에서는 VIA JSON이 무엇인지, JSON이 담고 있는 핵심 정보와 layouts, Matrix 구조가 어떤 역할을 하는지 살펴보았습니다. 다음 Part에서는 VIA가 JSON을 실제로 읽는 순서와 menus 구조, 레이어 정보, JSON 오류가 발생하는 이유, FAQ 및 함께 보면 좋은 글까지 이어서 정리하겠습니다.
6. VIA는 JSON 파일을 어떤 순서로 읽을까?
VIA에서 JSON 파일을 불러오면 파일에 적힌 내용을 단순히 화면에 그대로 출력하는 것이 아닙니다. 먼저 JSON 문법이 올바른지 확인하고, 장치를 구분하는 정보와 키보드 배열 정보를 차례로 해석한 뒤 실제 연결된 키보드와 통신할 준비를 합니다.
전체 흐름을 간단히 정리하면 JSON 문법 확인 → 장치 정보 확인 → 화면 레이아웃 생성 → 키보드 연결 승인 → 펌웨어와 통신 순서로 이해할 수 있습니다. JSON은 키보드의 펌웨어 자체가 아니라 VIA가 키보드를 이해하기 위해 사용하는 정의 파일에 가깝습니다.
- 불러온 파일이 정상적인 JSON 형식인지 검사합니다.
- 키보드 이름, Vendor ID, Product ID 등의 장치 정보를 확인합니다.
- layouts에 정의된 키 위치를 바탕으로 화면 배열을 만듭니다.
- 사용자가 장치 접근을 허용하면 실제 키보드와 연결합니다.
- VIA 프로토콜을 통해 현재 키맵과 레이어 정보를 읽습니다.
- 사용자가 변경한 키 설정을 키보드의 동적 키맵 영역에 기록합니다.
여기서 중요한 부분은 JSON 파일을 불러오는 것과 실제 키보드를 연결하는 것은 별개의 과정이라는 점입니다. JSON을 정상적으로 불러오면 화면에 키보드 모양이 나타날 수 있지만, 실제 장치 연결이 완료되지 않았다면 키 변경 내용은 키보드에 저장되지 않습니다.
반대로 키보드가 USB 장치로 정상 연결되어 있어도 VIA가 해당 키보드의 배열 정보를 알지 못하면 화면에 키 배열을 제대로 표시할 수 없습니다. 이 때문에 사이드로드 방식의 VIA 키보드는 JSON 불러오기와 장치 승인을 모두 완료해야 합니다.
VIA 화면에 키보드 배열은 보이는데 키를 눌러도 반응하지 않는다면 JSON보다 장치 승인 상태를 먼저 확인해보는 것이 좋습니다. 반대로 장치는 연결되는데 배열이 비어 있거나 이상하다면 JSON의 장치 정보와 layouts 구성을 확인해야 합니다.
JSON은 키 입력을 직접 처리하지 않습니다. 실제 키 스캔, 디바운스, 레이어 전환과 USB HID 전송은 키보드 펌웨어가 담당합니다. JSON은 VIA가 그 펌웨어의 설정 가능한 구조를 사용자에게 보여주기 위한 인터페이스 정의에 가깝습니다.
7. menus는 무엇을 정의할까?
VIA JSON에서 menus는 키 배열 외에 사용자가 조절할 수 있는 추가 설정 화면을 정의할 때 사용됩니다. 대표적으로 조명 효과, 밝기, 애니메이션 속도, 특정 펌웨어 기능과 같은 항목을 VIA 화면에 표시할 수 있습니다.
다만 menus에 원하는 설정 이름을 임의로 적는다고 해서 기능이 새로 생기는 것은 아닙니다. 해당 기능을 실제로 처리하는 코드가 키보드 펌웨어에 구현되어 있어야 하며, JSON에 정의된 명령과 펌웨어 내부의 설정 처리 방식도 서로 일치해야 합니다.
- RGB 조명 효과 선택
- 조명 밝기와 속도 조절
- LED 색상 또는 채도 조절
- 키보드별 사용자 지정 기능
- 펌웨어가 지원하는 토글 및 슬라이더 설정
menus는 일반적인 키맵 변경보다 구조가 복잡합니다. 화면에 표시될 컨트롤 종류뿐 아니라 사용자가 값을 바꿨을 때 어떤 명령을 보내야 하는지도 연결되어야 하기 때문입니다. 펌웨어에 없는 기능을 JSON 메뉴에만 추가하면 버튼이나 슬라이더는 나타나더라도 정상적으로 작동하지 않을 수 있습니다.
다른 키보드의 JSON에서 RGB 메뉴 부분만 복사해 붙이는 방식은 권장되지 않습니다. 같은 RGB 기능처럼 보여도 펌웨어가 사용하는 채널, 명령 번호, 지원 범위가 다를 수 있습니다.
8. VIA JSON과 레이어의 관계
레이어는 하나의 물리 키에 여러 기능을 배치할 수 있게 해주는 구조입니다. 기본 레이어에서는 일반 문자 키로 작동하지만, Fn 키를 누른 상태에서는 밝기 조절이나 미디어 제어 키로 작동하도록 구성할 수 있습니다.
VIA 화면에서 Layer 0, Layer 1, Layer 2처럼 여러 페이지가 표시되지만, 실제 레이어 수와 키맵 저장 공간은 펌웨어가 결정합니다. JSON은 사용자가 레이어별 배열을 확인하기 쉽도록 키보드 모양을 표현하며, 실제 키코드 데이터는 VIA 프로토콜을 통해 펌웨어에서 읽어옵니다.
예를 들어 JSON에 레이어처럼 보이는 배열을 여러 개 추가하더라도 펌웨어가 그만큼의 동적 레이어를 지원하지 않으면 실제 사용 가능한 레이어 수는 늘어나지 않습니다. 레이어를 추가하려면 QMK 펌웨어 설정과 메모리 크기까지 함께 고려해야 합니다.
또한 VIA에서 자주 사용하는 MO(1), TG(1), TO(1) 같은 키코드는 레이어를 사용하는 방식이 서로 다릅니다. MO는 누르는 동안만 지정 레이어를 활성화하고, TG는 레이어를 켜거나 끄며, TO는 지정한 레이어로 전환합니다.
- 이동한 레이어에서 기본 레이어로 돌아올 키가 있는지 확인합니다.
- Fn 키를 변경하기 전 현재 위치를 기록해두는 것이 안전합니다.
- 레이어 전환 키를 여러 개 배치하면 복구가 쉬워집니다.
- 펌웨어가 지원하는 레이어 수를 초과해 설정할 수는 없습니다.
VIA에서 키를 바꾸면 펌웨어 소스 코드가 다시 컴파일되는 것이 아닙니다. 이미 펌웨어 안에 마련된 동적 키맵 저장 영역의 값만 변경됩니다. 그래서 설정이 빠르게 적용되지만, 펌웨어가 처음부터 지원하지 않는 기능까지 VIA만으로 추가할 수는 없습니다.
9. VIA JSON에서 자주 발생하는 오류
VIA JSON 오류는 크게 문법 오류, 장치 식별 오류, 레이아웃 오류, 펌웨어 호환 오류로 나눌 수 있습니다. 화면에 파일을 불러오지 못했다는 메시지가 나타난다면 먼저 JSON 문법을 확인해야 하고, 파일은 열리지만 키보드를 찾지 못한다면 Vendor ID와 Product ID를 확인해야 합니다.
쉼표와 괄호 오류
JSON은 항목과 항목 사이에 쉼표가 필요하지만 마지막 항목 뒤에는 불필요한 쉼표를 허용하지 않는 경우가 많습니다. 또한 중괄호와 대괄호가 하나라도 빠지면 전체 파일을 읽지 못할 수 있습니다. 사람이 보기에는 작은 오타처럼 보여도 VIA 입장에서는 파일 구조가 완전히 깨진 것으로 판단할 수 있습니다.
Vendor ID와 Product ID 불일치
VID와 PID는 USB 장치를 구분하는 핵심 값입니다. JSON에 기록된 값과 실제 키보드가 보고하는 값이 다르면 VIA는 화면 정의와 연결된 장치를 같은 제품으로 판단하지 못할 수 있습니다. 같은 제품명이라도 유선·무선 리시버 또는 펌웨어 버전에 따라 식별 정보가 달라질 가능성이 있습니다.
키 배열 순서 불일치
화면에 그려지는 키의 순서와 펌웨어가 기대하는 키맵 순서가 다르면 사용자가 클릭한 키와 실제 변경되는 키가 달라질 수 있습니다. 이 오류는 배열이 비슷한 다른 모델의 JSON을 복사해 수정할 때 특히 자주 발생합니다.
지원하지 않는 VIA 정의 버전
VIA 정의 파일은 사용되는 스키마와 기능에 따라 구조가 달라질 수 있습니다. 오래된 정의 파일을 최신 VIA 환경에서 사용하거나, 반대로 최신 형식의 JSON을 오래된 프로그램에서 열면 일부 필드가 인식되지 않을 수 있습니다. 제조사에서 제공하는 최신 파일을 우선 사용하는 이유가 여기에 있습니다.
JSON을 수정하기 전에는 원본 파일을 별도로 복사해두는 것이 좋습니다. 오류가 발생했을 때 수정 지점을 찾는 것보다 정상 작동하던 원본으로 돌아간 뒤 한 항목씩 변경하는 편이 훨씬 빠릅니다.
10. VIA JSON, QMK 키맵, VIAL 구조 차이
VIA JSON과 QMK 키맵은 모두 키보드 배열과 관련되어 있지만 역할은 다릅니다. QMK 키맵은 펌웨어를 빌드할 때 포함되는 실제 키 동작 코드이고, VIA JSON은 이미 빌드된 펌웨어를 VIA 화면에서 설정하기 위한 정의 파일입니다.
VIAL은 QMK 기반 펌웨어와 그래픽 설정 도구를 결합한다는 점에서는 VIA와 비슷하지만, 장치 정의와 보안 절차, 지원 기능 구성에서 차이가 있습니다. VIAL은 키보드 펌웨어 안에 더 많은 정의 정보를 포함하고 다양한 고급 기능을 제공하는 방식으로 설계됩니다.
단순히 키 위치를 바꾸고 매크로를 설정하려는 사용자라면 VIA만으로 충분한 경우가 많습니다. 반면 펌웨어의 동작 자체를 바꾸거나 새로운 기능을 구현하려면 QMK 소스 수정과 컴파일이 필요합니다. VIAL은 다양한 고급 설정을 GUI에서 다루고 싶을 때 선택할 수 있지만, 키보드가 VIAL 펌웨어를 지원해야 합니다.
11. VIA JSON을 직접 수정해도 될까?
기본적인 JSON 문법과 VIA 구조를 이해하고 있다면 직접 수정할 수 있습니다. 예를 들어 키보드 이름을 정리하거나, 실제 제품과 다른 화면상의 키 위치를 바로잡거나, 펌웨어에서 이미 지원하는 옵션을 화면에 표시하도록 수정할 수 있습니다.
그러나 JSON 수정만으로 매트릭스 회로를 바꾸거나, NKRO를 추가하거나, 스캔 속도를 높이거나, 새로운 키보드 기능을 구현할 수는 없습니다. 이런 동작은 펌웨어와 하드웨어 영역에서 결정됩니다.
- 가능: 화면 키 위치 수정, 키보드 이름 변경, 레이아웃 옵션 정리
- 조건부 가능: 펌웨어가 이미 지원하는 조명·설정 메뉴 표시
- 불가능: 물리 매트릭스 변경, 새로운 USB 기능 추가, 스캔 로직 변경
- 펌웨어 작업 필요: 레이어 수 확장, 사용자 키코드 구현, 기능 자체 추가
수정할 때는 한 번에 여러 항목을 바꾸지 않는 것이 좋습니다. 원본을 복사한 뒤 키보드 이름, layouts, 메뉴처럼 영역을 나누어 하나씩 수정하고, 변경할 때마다 VIA에서 정상적으로 불러와지는지 확인해야 오류 원인을 쉽게 찾을 수 있습니다.
VIA JSON을 키보드 드라이버라고 부르는 경우가 있지만, 운영체제 수준의 장치 드라이버와는 성격이 다릅니다. JSON은 키보드의 USB 통신을 가능하게 하는 파일이 아니라 VIA 내부에서 장치를 설명하고 설정 화면을 구성하는 데이터입니다.
12. 자주 묻는 질문
아닙니다. JSON은 VIA 화면에서 키보드 구조를 설명하는 파일입니다. 펌웨어를 교체하거나 업데이트하려면 별도의 펌웨어 파일과 플래싱 과정이 필요합니다.
일반적으로 JSON을 잘못 불러온 것만으로 하드웨어가 바로 손상되지는 않습니다. 다만 배열이 잘못 표시되거나 엉뚱한 키가 변경될 수 있으므로 자신의 모델과 펌웨어에 맞는 파일을 사용해야 합니다.
아닙니다. JSON은 화면 표현만 정의합니다. 실제 키 수와 위치는 PCB 매트릭스, 펌웨어 키맵, 물리 스위치 배치에 의해 결정됩니다.
정상적인 VIA 지원 펌웨어라면 변경한 동적 키맵이 키보드의 비휘발성 저장 영역에 기록되므로 USB 케이블을 분리해도 유지됩니다. 공장 초기화나 펌웨어 교체 시에는 설정이 초기화될 수 있습니다.
데이터 전송을 지원하지 않는 케이블, 잘못된 연결 모드, 브라우저 권한 거부, VID·PID 불일치, VIA 기능이 없는 펌웨어 등이 원인일 수 있습니다. 유선 연결과 Chrome 또는 Edge 환경부터 확인하는 것이 좋습니다.
일반적인 VIA JSON만으로는 바꿀 수 없습니다. NKRO 처리, 스캔 주기, USB Polling Rate 같은 항목은 주로 키보드 펌웨어와 USB 장치 설정에서 결정됩니다.
📚 함께 보면 좋은 글
VIA JSON의 역할을 이해했다면 키보드 입력 처리 과정과 VIA·VIAL의 구조도 함께 살펴보는 것이 좋습니다. 각 개념이 어느 영역에서 작동하는지 비교하면 JSON으로 가능한 설정과 펌웨어 수정이 필요한 작업을 더 명확하게 구분할 수 있습니다.
13. 공식 자료
VIA JSON을 직접 작성하거나 수정하려면 예제 파일만 복사하기보다 VIA와 QMK의 공식 문서를 함께 확인하는 것이 안전합니다. 특히 정의 파일 버전, 동적 키맵, 장치 식별 정보는 사용하는 펌웨어와 VIA 환경에 따라 달라질 수 있습니다.
14. Sources
VIA JSON은 키보드의 기능을 만드는 펌웨어가 아니라, VIA가 장치와 배열을 이해하고 설정 화면을 구성하도록 돕는 구조 설명서입니다.
답글 남기기