apache/ossie 딥다이브
— 회사마다 다른 "매출"의 정의를, 50개 벤더가 합의한 하나의 YAML로

1프로젝트 한 줄 요약

Apache Ossie는 "시맨틱 모델(semantic model)을 어떤 YAML 형식으로 적을 것인가"를 정하는 규격 하나와, 그 규격을 기계가 검증할 수 있게 만든 JSON Schema, 그리고 기존 도구들의 형식을 이 규격으로 오가게 해주는 변환기 7종이 전부인 저장소다. 코드베이스라기보다 규격서(specification)에 가깝다.

저장소는 크게 네 덩어리로 나뉜다.

2왜 지금 주목받는가

이유 1 — "AI 에이전트가 틀린 숫자를 말한다"는 절박함

README가 직접 지목하는 문제는 세 가지다: 도구마다 다르게 정의된 같은 KPI, 정의를 수동으로 맞추느라 낭비되는 시간, 그리고 "일관성 없는 비즈니스 로직에 기반해 신뢰할 수 없는 결과를 내놓는 AI 에이전트"다. 세 번째가 2026년의 결정타다.

이유 2 — 경쟁사 50곳이 한 테이블에 앉았다는 사건성

docs/index.md에 적힌 참여 조직에는 Alation, Anomalo, Atlan, AtScale, BlackRock, Cloudera, Databricks, dbt Labs, Snowflake, GoodData, Informatica, Mistral AI, Oracle, Qlik, Salesforce, Starburst가 함께 들어 있다. 데이터 웨어하우스 시장에서 서로를 잡아먹으려는 회사들이 같은 규격을 만든다는 것 자체가 뉴스거리다.

이유 3 — 이관 직후의 폭발적 활동량

이 저장소는 원래 open-semantic-interchange/OSI 조직에 있다가 Apache로 옮겨왔다. 커밋 로그에 그 흔적이 그대로 남아 있다.

9738b1e  Welcome Apache Ossie (incubating)
267638d  docs: flag repository as legacy, point to apache/ossie
710da10  feat(cli): scaffold ossie CLI            # (#151)
309acbf  [OSI][Omni] Add Omni semantic model converter  # (#175)
07be017  chore: add EditorConfig tab indentation for Go files  # (#225)

수치로 보면 총 212커밋 중 최근 30일(2026-06-18~07-18)에만 52커밋이 몰려 있고, 마지막 push는 이 글을 쓰기 하루 전이다. 열린 이슈 55개도 대부분 "새 변환기 추가"류다 — #227 Lightdash 변환기, #224 Databricks Unity Catalog 변환기, #222 sqlglot 기반 OSI SQL 딜렉트, #228 uv 전환.

경쟁·유사 규격과의 관계

3기술 스택 전체 지도

언어 구성 (실측 LOC)

백엔드 — Python 계층

검증기 validation/validate.py

의존성 선언 방식이 재미있다. requirements.txt도 pyproject.toml도 없이, 파일 맨 위 주석에 의존성을 적는 PEP 723 인라인 메타데이터를 쓴다.

# /// script
# requires-python = ">=3.11"
# dependencies = [
#   "jsonschema>=4.26.0",
#   "pyyaml>=6.0.3",
#   "sqlglot>=30.12.0",
# ]
# ///

참조 구현 패키지 python/ (PyPI명 apache-ossie)

의존성은 pydantic과 pyyaml 둘뿐. 스펙을 파이썬 객체로 읽고 쓰는 얇은 층이다.

dbt 변환기 converters/dbt/

dependencies = [
  "apache-ossie>=0.2.0.dev0",
  "metricflow>=0.209.0",   # dbt Labs 패키지를 그대로 의존!
  "sqlglot>=20.0",
  "jinja2>=3.0",
  "PyYAML>=6.0",
]
# 빌드 백엔드: hatchling · 패키지 매니저: uv (uv.lock 존재)

프론트엔드 / CLI 계층 — Go

// cli/go.mod
go 1.26.2
require github.com/spf13/cobra v1.10.2   // + mousetrap, pflag
// 배포: GoReleaser (cli/.goreleaser.yaml)

Cobra의 플래그 설계는 이미 꽤 정교하다 — --from/--to 상호배타(MarkFlagsMutuallyExclusive), --input 필수, --plugin으로 변환기 경로 직접 지정, --timeout, --max-input-size. 이 설계는 "변환기를 플러그인으로 설치하고 CLI가 오케스트레이션한다"는 미래 그림을 드러낸다. 다만 실행 로직은 비어 있다.

Java 계층

converters/polaris/pom.xml, converters/salesforce/pom.xml 둘 다 Maven이고 ASF 부모 POM(org.apache:apache:39)을 상속한다. Salesforce 변환기는 HandlerFactory + PipelineStep의 파이프라인 패턴으로 구성돼 있다.

인프라 · CI · 거버넌스 설정

4아키텍처 심화 분석

설계 패턴 1 — 허브 앤 스포크 (hub-and-spoke)

Ossie가 존재하는 이유를 한 장의 그림으로 요약하면 이렇다. converters/README.md에 실린 다이어그램을 옮긴다.

수학이 단순하다. 도구가 N개일 때 서로 직접 변환기를 만들면 N × (N-1)개가 필요하다. 도구 8개면 56개다. 가운데 중립 허브를 두면 각 도구가 "허브로 내보내기 1개 + 허브에서 읽기 1개"만 만들면 되므로 2 × N = 16개로 줄어든다.

설계 패턴 2 — 5계층 데이터 모델

스펙의 핵심 개념은 다섯 개다. 위에서 아래로 내려가며 읽으면 된다.

딜렉트(dialect) — 하나의 개념, 여러 개의 SQL

Ossie는 "표현식을 하나의 언어로 통일"하지 않는다. 대신 같은 개념에 대해 여러 딜렉트의 표현식을 나란히 적게 한다.

dialects:
  - "ANSI_SQL"
  - "SNOWFLAKE"
  - "DATABRICKS"
  - "BIGQUERY"
  - "MDX"        # 다차원 큐브 질의어
  - "TABLEAU"
  - "MAQL"       # GoodData 전용

실제 YAML — 이렇게 생겼다

semantic_model:
  - name: retail_analytics
    ai_context: "소매 주문·상품 분석용 모델"
    datasets:
      - name: orders
        source: PROD.PUBLIC.FCT_ORDERS
        primary_key: [order_id]
        fields:
          - name: order_date
            expression:
              dialects:
                - dialect: ANSI_SQL
                  expression: order_date
            dimension:
              is_time: true
            ai_context:
              synonyms: ["purchase date", "transaction date"]

    relationships:
      - name: order_lines_to_products
        from: orders            # many 쪽
        to: products             # one 쪽
        from_columns: [product_id, variant_id]   # 복합 FK 지원
        to_columns:   [id, variant_id]

    metrics:
      - name: total_revenue
        expression:
          dialects:
            - dialect: ANSI_SQL
              expression: SUM(orders.amount)
        ai_context:
          synonyms: ["total sales", "revenue"]

    custom_extensions:
      - vendor_name: SNOWFLAKE
        data: '{"warehouse": "ANALYTICS_WH", "database": "PROD"}'

설계 패턴 3 — ai_context를 1급 시민으로

모델·데이터셋·필드·관계·메트릭 모든 계층에 ai_context가 들어간다. 그리고 JSON Schema에서 oneOf로 문자열과 객체를 둘 다 허용한다.

# 간단하게 쓰고 싶으면 문자열 하나
ai_context: "매출 분석에 사용하세요"

# 자세히 쓰고 싶으면 객체
ai_context:
  instructions: "Use this for sales analysis"
  synonyms: ["orders", "purchases", "sales"]
  examples: ["Show total sales last month"]

설계 패턴 4 — 온톨로지 층 (두 번째 스택)

여기서 Ossie의 야심이 드러난다. Dataset/Field는 결국 물리 테이블에 묶인 논리 층인데, 그 위에 물리 스키마와 완전히 무관한 순수 개념 층을 하나 더 두려 한다(ontology/).

name: EnterpriseOntology
ontology:
  - concept:
      name: SocialSecurityNr
      type: ValueType        # 의미가 붙은 데이터 타입
      extends: [Integer]
  - concept:
      name: Employee
      type: EntityType       # 실세계 개념
      extends: [Person]

이 층은 별도 JSON Schema(ontology/ontology.json)를 갖고, ontology_mappings로 물리 시맨틱 모델과 연결된다. 즉 Ossie는 "물리에 붙은 시맨틱 레이어"와 "물리와 무관한 온톨로지" 두 스택을 모두 가지려 한다.

검증기 파이프라인 — 실제로 도는 유일한 코드

# validation/validate.py — 딜렉트 매핑
DIALECT_MAP = {
    "ANSI_SQL": None,      "SNOWFLAKE": "snowflake",
    "DATABRICKS": "databricks", "BIGQUERY": "bigquery",
    "MDX": None, "TABLEAU": None, "MAQL": None,
}
# sqlglot이 파싱 못하는 딜렉트는 SQL 검증 자체를 건너뛴다
SKIP_SQL_VALIDATION = {"MDX", "TABLEAU", "MAQL"}

참조 모델 — 불변(frozen) pydantic

# python/src/ossie/models.py
class OSIRelationship(BaseModel):
    model_config = ConfigDict(frozen=True, populate_by_name=True)
    name: str
    from_dataset: str = Field(..., alias="from")  # from은 파이썬 예약어!
    to: str
    from_columns: list[str]
    to_columns: list[str]

class OSIDocument(BaseModel):
    version: str = "0.2.0.dev0"
    semantic_model: list[OSISemanticModel]

    def to_osi_yaml(self, **kwargs):
        data = self.model_dump(by_alias=True, exclude_none=True,
                               mode="json", **kwargs)
        return yaml.dump(data, default_flow_style=False,
                         sort_keys=False, allow_unicode=True)

포인트 셋: frozen=True로 모델을 불변화(스펙 문서는 값 객체다), alias="from"으로 파이썬 예약어 회피, exclude_none=True로 빈 필드를 출력에서 제거해 왕복 변환(round-trip) 시 YAML이 지저분해지지 않게 한다. 그리고 OSIAIContext = Union[str, OSIAIContextObject]로 스키마의 oneOf를 파이썬 타입으로 그대로 미러링한다.

5디렉토리 구조 해부

어디부터 읽어야 하나 — 읽는 순서 추천

6학습 포인트

1) JSON Schema로 "검증 가능한 규격" 만들기

osi-schema.json은 JSON Schema 학습 교재로 쓸 만하다. 실제로 쓰인 기법들:

2) 이중 표현 전략 — 사람용과 기계용을 나란히

같은 스펙을 세 벌로 유지한다. spec.md(산문 설명) / spec.yaml(주석 많은 예시) / osi-schema.json(기계 검증). 중복처럼 보이지만 각각 독자가 다르다 — 의사결정자, 구현자, 도구.

3) pydantic으로 불변 도메인 모델 만들기

배울 것: frozen=True(값 객체), alias로 예약어 회피, Union 타입으로 스키마 oneOf 미러링, model_dump(by_alias=True, exclude_none=True, mode="json")으로 깔끔한 왕복 직렬화.

4) sqlglot으로 다중 SQL 딜렉트 다루기

sqlglot은 20종 이상의 SQL 방언을 파싱·변환하는 파이썬 라이브러리다. Ossie는 검증에만 쓰지만, 이 라이브러리 자체가 "SQL을 문자열이 아니라 AST로 다루는" 세계로 들어가는 관문이다. 이슈 #222는 여기서 더 나아가 sqlglot에 OSI 전용 딜렉트를 등록해 표현식을 자동 트랜스파일하자는 제안이다.

5) 손실을 숨기지 않는 변환기 설계

dbt 변환기의 msi_to_osi.py는 dbt의 PydanticSemanticManifest를 순회하며 Entity/Dimension/Measure를 Ossie Field로, dbt Metric을 OSIMetric으로 옮긴다. 이때 옮길 수 없는 것을 조용히 버리지 않고 명시적으로 기록한다.

ConverterIssueType.CUMULATIVE_SEMANTICS_LOSS
ConverterIssueType.CONVERSION_METRIC_DROPPED

6) Apache 거버넌스 실물 관찰

CONTRIBUTING.md가 유난히 상세해서, 오픈소스 거버넌스를 글이 아니라 실물로 볼 수 있다.

7) PEP 723 · uv · hatchling — 2026년 파이썬 패키징 관행

validate.py의 인라인 메타데이터, 변환기들의 uv.lock, 빌드 백엔드 hatchling. setup.py 시대를 건너뛰고 현재 관행을 바로 배울 수 있는 샘플이다. (열린 이슈 #228이 "저장소 전체를 uv로 전환"이다.)

8) Cobra(Go) CLI 스캐폴딩

기능은 비었지만 골격은 배울 만하다. MarkFlagsMutuallyExclusive(상호배타 플래그), MarkFlagsOneRequired, PersistentPreRunE. 특히 Cobra가 PersistentPreRunE를 부모→자식으로 자동 상속하지 않는다는 함정을 코드 주석으로 직접 경고해 둔 부분이 실전 지식이다.

7시스템 · 실행 요구사항

다행히 요구사항이 거의 없다. GPU도 클라우드 계정도 필요 없고, YAML 파일을 읽고 검증하는 것이 전부다.

8직접 해볼 수 있는 실습 과제

git clone --depth 1 https://github.com/apache/ossie.git
cd ossie
python validation/validate.py examples/tpcds_semantic_model.yaml

from ossie.models import OSIDocument
import yaml

doc = OSIDocument(**yaml.safe_load(open("examples/tpcds_semantic_model.yaml")))
for model in doc.semantic_model:
    for m in (model.metrics or []):
        print(m.name, "|", m.expression.dialects[0].expression)

9관련 기술 심화 학습 로드맵

10핵심 키워드 사전

11참고 링크