온톨로지 스키마에 UI를 얹었더니, YAML에서 안보이는게 보입니다

YAML 편집이 한계에 부딪혔다

온톨로지 거버넌스를 운영하면서 스키마는 계속 ontology.yaml 파일 하나로 관리하고 있었거든요. 노드 타입, 관계 타입, 속성, 추출 규칙까지 전부 이 파일 안에 들어 있었습니다.

처음에는 괜찮았어요. 노드 타입이 10개 안팎일 때는 YAML을 열어서 "이 노드에 속성이 뭐가 있지?" 확인하고, 필요하면 직접 수정하면 됐거든요. 에디터에서 검색하면 금방 찾을 수 있었습니다.

그런데 노드 타입이 20개를 넘고, 관계 타입도 30개 가까이 되니까 상황이 달라지더라고요.

YAML에서 "관계"가 안 보인다

가장 큰 문제는 관계 파악이었습니다. YAML에서 노드 타입은 섹션별로 나뉘어 있어서 찾기 쉬운데, "이 노드가 어떤 노드와 어떤 관계로 연결되어 있는지"는 파일을 위아래로 스크롤하면서 머릿속으로 조합해야 했거든요.

예를 들어 "Server" 노드가 어떤 관계를 갖고 있는지 보려면, relationships 섹션에서 from이나 to에 Server가 들어간 항목을 하나하나 찾아야 합니다. 관계가 5개면 괜찮은데, 15개가 되면 눈으로 따라가는 게 불가능해요.

두 번째 문제는 오타였습니다. 속성 이름을 수정할 때 YAML 들여쓰기가 한 칸 어긋나면 파싱 에러가 나는데, 에러 메시지만 보면 어디가 틀렸는지 찾기가 어렵거든요. 노드 타입 이름을 오타 내면 관계 연결이 조용히 끊어지는 것도 문제였어요.

세 번째는 전체 구조가 안 보인다는 거였어요. 노드가 20개, 관계가 30개면 "전체적으로 어떤 그림인지"를 YAML 텍스트만으로는 파악할 수가 없습니다. 새로운 타입을 추가할 때 기존 구조와 어떻게 연결되는지를 판단하려면, 결국 별도로 그림을 그려야 했거든요.

다이어그램으로 보면 바로 보인다

해결 방법은 단순했습니다. YAML에 있는 정보를 그래프 다이어그램으로 시각화하면 되는 거였어요.

vis-network라는 라이브러리를 썼는데, 노드 타입을 컬러 박스로, 관계 타입을 화살표 + 라벨로 표시하면 전체 온톨로지 구조가 한눈에 들어옵니다. 계층형 좌→우 레이아웃을 적용하니까, "어떤 노드가 어떤 노드와 연결되어 있는지"가 YAML을 스크롤할 필요 없이 바로 보이더라고요.

각 노드 박스에는 주요 속성 4개를 표시하고, 나머지는 "+N" 으로 접어뒀어요. 속성이 15개인 노드를 전부 보여주면 박스가 너무 커져서 다이어그램이 읽기 어려워지거든요. 필요하면 클릭해서 상세 패널에서 전부 확인할 수 있습니다.

좌측 상단에는 노드 타입 범례를 세로로 나열해서, 특정 타입을 클릭하면 해당 노드가 하이라이트되게 만들었어요. 노드가 20개 넘으면 다이어그램에서 원하는 노드를 찾는 것 자체가 일이거든요.

보는 것만으로는 부족하고, 편집도 해야 한다

다이어그램을 만들고 나니 다음 문제가 보였습니다. "이 노드의 description을 수정하려면 결국 YAML로 가야 하잖아?"

그래서 우측 상세 패널에 편집 기능을 넣었어요. 노드나 관계를 클릭하면 보기 모드로 상세 정보가 나오고, 연필 아이콘을 누르면 편집 모드로 전환됩니다. description 수정, 속성 추가/삭제를 UI에서 바로 할 수 있어요.

저장하면 내부적으로 ontology.yaml이 자동 동기화되고, config_version 테이블에 새 버전이 기록됩니다. YAML을 직접 건드리지 않으니까 들여쓰기 오타 문제도 사라졌고, 누가 언제 뭘 바꿨는지 이력도 남거든요.

두 가지 뷰를 탭으로 나눴다

화면은 다이어그램 탭과 YAML 상세 탭, 두 개로 구성했어요.

다이어그램 탭은 구조를 파악하고 편집하는 용도이고, YAML 상세 탭은 ontology.yaml의 실제 내용을 섹션별로 접기/펼치기로 확인하는 용도입니다. nodes, relationships, vector, fulltext, extraction 섹션을 각각 펼쳐볼 수 있어요.

왜 YAML 탭을 따로 뒀냐면, 다이어그램에서 수정한 결과가 실제 YAML에 어떻게 반영됐는지 확인하고 싶을 때가 있거든요. 특히 extraction 규칙(merge_key, normalize 설정)은 아직 다이어그램에서 편집이 안 되기 때문에, 이 부분은 YAML 탭에서 직접 확인해야 합니다.

아직 못 만든 것들

현재 UI에서 되는 건 "보기 + 속성 편집"까지예요. 노드 타입이나 관계 타입을 새로 추가하거나 삭제하는 건 아직 구현 안 했습니다.

남은 과제를 정리하면 이렇거든요.

타입 추가/삭제는 거버넌스 프로세스와 연동해야 해서, 승격·롤백 로직이 들어가면 같이 진행하면 좋을거 같습니다.

YAML은 남아 있되, 직접 건드릴 일이 줄었다

온톨로지 스키마의 원본은 여전히 ontology.yaml입니다. UI가 이 파일을 대체하는 게 아니라, YAML 위에 시각화 + 편집 레이어를 얹은 구조예요.

다이어그램으로 전체 구조를 파악하고, 클릭해서 상세를 확인하고, 필요하면 바로 수정하고, 저장하면 YAML이 동기화되는 흐름입니다. YAML을 에디터로 직접 여는 빈도가 확실히 줄었고, 새로운 타입을 추가할 때 기존 구조와의 관계를 다이어그램에서 먼저 확인할 수 있게 된 게 가장 큰 변화였습니다.

온톨로지 스키마가 복잡해질수록 텍스트만으로 관리하는 건 한계가 있어요. 노드 타입이 10개를 넘어가면 시각화부터 해보는 걸 추천합니다.