텔레그램 TL 스키마·레이어 읽는 법

스키마는 API 의 '설계도 목록'

텔레그램 API 의 모든 자료 모양과 메서드는 TL(Type Language)이라는 짧은 표기로 한 줄씩 적혀 있습니다. 이 목록이 스키마입니다. 공식 스키마 쪽(core.telegram.org/schema)은 사람이 읽는 설명서가 아니라 이런 줄 수백 개의 목록이라, 읽는 법만 알면 메서드 목록을 따로 번역할 필요가 없습니다. 지금 공식 스키마의 판(레이어)은 225 입니다(이 글을 쓴 날 기준).

한 줄 읽기

아래는 설명을 위해 지어낸 줄입니다(실제 스키마에 없는 이름).

sampleNote#1a2b3c4d id:long text:string = Note;

부분	뜻
sampleNote	생성자 이름 — 소문자로 시작한다
#1a2b3c4d	생성자 번호(32비트, 16진수) — 이진 데이터 맨 앞에 붙어 '이건 sampleNote 다'를 알린다
id:long text:string	칸 이름과 칸의 형식
= Note	이 생성자가 만드는 형식 — 대문자로 시작한다

한 형식에 생성자가 여럿일 수 있습니다. 예를 들어 '사진' 형식에 '사진 있음'과 '빈 사진' 생성자가 함께 있는 식이라, 받은 데이터는 생성자 번호를 보고 어느 쪽인지 가립니다.

선택 칸 — flags

sampleMessage#5e6f7a8b flags:# pinned:flags.0?true reply_to:flags.1?int text:string = Message;

• flags:# — 어떤 선택 칸이 들어 있는지 비트로 알려 주는 숫자 칸.
• reply_to:flags.1?int — flags 의 1번 비트가 켜져 있을 때만 이 칸이 있다.
• pinned:flags.0?true — 형식이 true 인 칸은 값 없이 비트 자체가 '예/아니요'다.

읽을 때는 flags 를 먼저 보고, 켜진 비트의 칸만 차례로 읽습니다. 빠뜨리면 그 뒤 칸이 전부 밀려 해석이 깨집니다.

목록의 두 구역과 Vector

구역·표기	뜻
---functions--- 위	자료 모양(형식·생성자)
---functions--- 아래	호출할 수 있는 메서드 — 줄 끝의 형식이 돌려받는 값
Vector<User>	User 여러 개의 목록

레이어와 바뀐 점 따라가기

• 스키마가 바뀔 때마다 레이어 번호가 하나씩 올라갑니다. 앱은 자기가 쓰는 레이어를 연결 때 밝힙니다(메서드 부르기).
• 무엇이 바뀌었는지는 공식 '레이어 변경 기록'(core.telegram.org/api/layers)에서 봅니다. 기계가 읽는 JSON 판 스키마도 있어, 코드 생성기에 넣어 씁니다.
• TDLib 은 자기 스키마(td_api.tl)가 따로 있습니다. 표기법은 같고, 이름과 구조는 TDLib 에 맞춰 더 쓰기 쉽게 정리돼 있습니다(TDLib 빌드).