Bibliographic Reaction Object (BRO)

본 문서는 https://schema.slat.or.kr/bro/v1/schema.json에 정의된 Bibliographic Reaction Object(BRO)의 아키텍처, 제약 조건 및 데이터 처리 파이프라인에 대한 심층 기술 명세다. 이 스키마는 도서에 대한 파생 데이터(서평, 요약, 비평 등)를 수집, 검증, 영속화 및 반출하기 위한 규칙 세트를 규정한다.

1. 최상위 라우팅 아키텍처 (Top-Level Routing)

BRO 스키마는 단일 목적의 객체가 아니며, 진입점의 문맥에 따라 3개의 서로 다른 페이로드 구조 중 하나(oneOf)로 분기 처리된다. 시스템은 인입/반출 시점에 따라 정확한 형태의 DTO 및 엔티티 캐스팅을 수행해야 한다.

1. articleIngestionPayload (클라이언트 데이터 인입용)
   • 목적: 외부 클라이언트(웹, 앱, 크롤러 등)로부터 최초 데이터를 수집하는 Write 단계의 DTO.
   • 특징: 서버 측에서 발급해야 하는 시스템 식별자(@id)에 대한 검증이 면제된다. 페이로드의 순수 데이터 무결성만 검증한다.
2. articlePersistedEntity (서버 내부 및 조회용 영속성 엔티티)
   • 목적: 데이터베이스 영속화(Persisted) 및 API 쿼리 응답(Read) 시 사용되는 구조.
   • 특징: 엄격한 UUID 포맷의 @id가 필수적으로 강제된다. 클라이언트 반출 파이프라인에서 실제 내부 식별자가 노출되지 않도록, 반드시 가명화된(Pseudonymized) 식별자로의 치환 연산이 선행되어야 한다.
3. itemListDefinition (다중 배열 매트릭스)
   • 목적: 단일 도서가 아닌, 특정 기준에 의해 묶인 도서 관련 글의 목록(Collection)을 전송하거나 반환할 때 사용.

2. 공통 기반 속성: articleBaseProperties 분석

모든 Article 기반 객체(Ingestion, Persisted)가 상속받는 핵심 뼈대 데이터 구조다.

• @context 및 @type: 고정값(Const) 적용. @context는 https://schema.org, @type은 Article로 강제 바인딩된다.
• dateCreated (최초 생성 타임스탬프):
  • 타입/포맷: string (ISO 8601 / RFC 3339 규격의 date-time 포맷).
  • 불변성 규칙(Immutability): 시스템 아키텍처 상 데이터 갱신(Update)은 전면 금지된다. 수정 요구가 발생할 경우, 기존 객체를 논리적 삭제(Soft Delete) 또는 별도 아카이빙 테이블로 이관하고, 신규 타임스탬프를 부여받은 완전히 새로운 객체를 생성하여 덮어쓴다.
  • KOMARC 매핑: 코어 서지 시스템 연동 프로세스(ETL)에서 타임스탬프는 YYYYMMDD 포맷으로 다운캐스팅되어 KOMARC 552 ▾k 서브필드의 '개시일자' 노드에 직접 매핑된다.
• about (대상 도서 식별체):
  • @type: Book 고정.
  • isbn: 정규식 ^(?:97[89]-?)?(?:\d[ -]?){9}[\dxX]$을 통과하는 10자리 또는 13자리의 국제표준도서번호만 허용. 하이픈 유무를 모두 허용하는 유연한 정규식이나, 파이프라인 후단에서 정규화 처리가 권장됨.
• text (범용 문서 텍스트 & 마크다운 프론트매터 파싱 로직):
  • 제약: 길이 0 ~ 300,000자.
  • 데이터 캡슐화 강제: 본문 데이터는 반드시 최상단 YAML Frontmatter로 메타데이터를 캡슐화해야 한다.
  • 유연성과 정규화의 비대칭성: 데이터 인입 시에는 프론트매터 블록 내에 임의의 키(Arbitrary Keys)를 무제한으로 주입하는 것이 허용된다. 그러나 API 반환 및 영속화 객체 표출을 담당하는 후행 파이프라인은 정규식 ^---\n([\s\S]*?)\n---을 이용해 프론트매터를 강제 파싱해야 한다.
  • 역직렬화 재구성 규칙: 파싱된 데이터 중 1급 필드인 title(문자열)과 keywords(문자열 배열)만을 최상위 노드에 직렬화한다. 그 외에 인입된 모든 잔여 동적 데이터 키-값 쌍은 others: [{key: value}, ...] 형태의 단일 배열 객체로 강제 묶음(Bundling) 처리하여 마크다운 본문 상단에 재조립해 표출해야 한다.
  • KOMARC 매핑 프로토콜: 생성된 text 데이터 세트의 규격 출처 식별자(https://schema.slat.or.kr/bro/v1/schema.json)는 KOMARC 552 ▾h에 기록되어야 하며, text 페이로드의 실제 원문은 552 ▾u 서브필드의 외부 URI 식별자를 통해 해소(Resolve)되어야 한다.

3. 영속화 엔티티: articlePersistedEntity 확장 조건

기본 articleBaseProperties를 모두 포함하며(allOf), 서버 내부 처리 및 출력 단계에서 다음 속성들을 추가로 강제(required)한다.

• @id: * ^urn:uuid:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
  • 반드시 URN 네임스페이스가 포함된 UUID 규격을 준수해야 한다.
• datePublished: * 발행 및 영속화 확정 일자. date 포맷(YYYY-MM-DD)을 사용한다.
  • KOMARC 매핑: 코어 서지 데이터 552 ▾k 서브필드의 '종료일자' 혹은 '유효일자'로 직결된다.

4. 서브 컴포넌트: abstractDefinition (요약 데이터)

LLM 또는 인간 작업자가 도출한 본문의 고밀도 구조화 요약 데이터 객체다.

• 필수 속성: @type, @id, text, author, dateCreated. (추가 임의 속성 unevaluatedProperties는 false로 엄격히 차단됨)
• @id 불변성: 원본 데이터 식별자 및 생성 시간을 시드로 하는 결정론적 UUID 해시값이 강제된다. 이는 본 요약 객체가 불변함을 수학적으로 보장하기 위함이다. 갱신 시 updated 필드 사용은 스키마 단위에서 금지되어 있으며, 반드시 신규 UUID가 재발급되어야 시스템의 멱등성이 유지된다.
• text KOMARC 매핑: 이 필드의 텍스트는 서지 시스템 연동 시 KOMARC 552 ▾o의 '개체/속성 개요' 서브필드에 Raw Text 형태로 직접 인젝션된다.

5. 컬렉션 구조: itemListDefinition

단일 도서에 종속되지 않는 큐레이션 데이터나 다중 게시물 반환 시 사용하는 배열 컨테이너.

• 구조: @type은 ItemList. @id는 URN UUID 규격 적용.
• name: 컬렉션의 명칭. 길이 제약 2자 이상 200자 이하.
• itemListElement: 내부 아이템 배열. 이 배열 내부의 객체는 모두 articleIngestionPayload로 강제 캐스팅된다.
  • 특이사항: 순수하게 글 없이 도서 자체만을 리스트업(예: 즐겨찾기 목록, 읽을 책 목록)하는 경우에는 text 값을 빈 문자열("")로 주입한 Article 객체 형태로 페이로드를 생성하여 규격의 통일성을 강제한다.

6. 작성자 식별 구조: authorDefinitions 및 다형성(Polymorphic) 식별자 제약

이 스키마에서 가장 복잡한 검증 로직이 적용된 블록. 원본 도서의 저자(KOMARC 1XX/7XX 필드)와는 완벽히 분리된 파생 문서의 생성 주체를 정의한다. 주체의 성격(@type)에 따라 식별자(@id)의 검증 정규식이 동적으로 변이(Mutation)하는 allOf + if/then 논리 게이트가 설계되어 있다.

• 공통 필드: * @type (enum), @id (타입별 조건부 검증), name (최대 100자).
  • softwareVersion: 생성 주체가 LLM(SoftwareApplication)인 경우 모델의 하위 버전 표기.
  • 보안 지침: 서버 내부 트랜잭션 시에는 원본 UUID v7 식별자가 유지되어야 하나, API 응답으로 클라이언트에 반출될 때는 반드시 식별자 난독화 로직(가명 처리)이 작동해야 한다.

6.1. 타입별 @id 검증 매트릭스

객체의 @type 값에 따라 다음의 엄격한 정규식 필터가 적용된다. 패턴 불일치 시 스키마 유효성 검증은 즉시 하드 폴트(Hard Fault)를 발생시킨다.

1. @type: Person (개인/사용자)
   • 규격: 표준 URN UUID 포맷.
   • 정규식: ^urn:uuid:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
2. @type: GovernmentOrganization (정부/공공기관)
   • 규격: 대한민국 정부기관 코드 7자리.
   • 정규식: ^urn🇰🇷govcode:\d{7}$
3. @type: Corporation (영리 법인/기업)
   • 규격: 법인등록번호(CRN) 13자리 또는 사업자등록번호(BRN) 10자리.
   • 정규식: ^urn🇰🇷(crn:\d{13}|brn:\d{10})$
4. @type: Organization (비영리 단체 등 기타 조직)
   • 규격: 비영리단체 고유번호 10자리 또는 범용 URN UUID.
   • 정규식: ^urn:(kr:npo:\d{10}|uuid:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
5. @type: SoftwareApplication (AI 모델 / 소프트웨어 알고리즘)
   • 규격: 벤더 및 모델명을 뎁스 구조로 식별하는 단일 URN 구조. (예: urn:model:openai:gpt-4o)
   • 정규식: ^urn:model:[a-zA-Z0-9-]+:[a-zA-Z0-9\.-]+$

서지 표준 매핑 가이드 (Bibliographic Standard Mapping Guide)

Bibliographic Reaction Object (BRO)는 원본 도서에 대한 파생 데이터(리뷰, 요약, 비평 등)를 표현하기 위한 스키마입니다. 따라서 전통적인 서지 표준(MARC, Dublin Core 등)의 핵심 레코드 자체가 아니라, 핵심 서지 레코드에 부착되거나 연동되는 부가 정보(Note/Extension) 속성을 갖습니다.

본 섹션은 BRO 스키마의 각 필드가 주요 서지 표준 시스템과 어떻게 매핑되고 호환되는지 설명합니다.

1. KOMARC (한국문헌자동화목록형식) 매핑 (공식 규격)

BRO 객체는 기본적으로 KORMARC/KOMARC의 552 필드 (데이터 세트와 관련된 개체/속성 주기) 에 연동되도록 설계되었습니다. 시스템 연동 시 ETL 파이프라인에서 다음과 같은 매핑 프로토콜을 따릅니다.

2. MARC 21 매핑 호환성

글로벌 서지 표준인 MARC 21 환경에서 BRO 객체를 관리할 때의 권장 매핑 방식입니다.

3. Dublin Core (더블린 코어) 매핑

웹 기반 메타데이터 표준인 Dublin Core (DC) 기반으로 변환할 때의 매핑입니다.

매핑 시 주의사항 (Mapping Protocols)

1. 도메인 분리 원칙: BRO 스키마의 author 속성은 원본 도서의 저자가 아닙니다. 리뷰, 요약 등 본 "반응(Reaction)" 데이터를 작성한 주체를 나타냅니다. (예: 독자, AI 모델명, 평가 기관 등) 서지 시스템의 메인 저자 필드(MARC 1XX)와 혼용해서는 안 됩니다.
2. 불변성(Immutability)과 타임스탬프: BRO 객체의 dateCreated는 수정이 불가능합니다. 내용 변경 시 기존 객체를 논리적 삭제하고 새로운 UUID와 타임스탬프를 발급받아야 하며, 이는 서지 시스템 연동 시 데이터의 멱등성과 무결성을 보장하기 위함입니다.
3. Payload 외부화: text 페이로드 내부에는 임의의 Markdown과 YAML Frontmatter가 포함될 수 있어 크기가 매우 커질 수 있습니다. 핵심 서지 데이터베이스에 직접 삽입하는 것을 지양하고 URI로 링킹하는 것을 권장합니다.

@slat.or.kr/bro-schema

Slat.or.kr 플랫폼 및 북슬(Booksle) 애플리케이션을 위한 서지 반응 객체(Bibliographic Reaction Object, BRO) 스키마 정의, 유효성 검사 유틸리티 및 파서입니다.

이 패키지는 BRO JSON 객체의 유효성을 검사하고, 엄격한 마크다운 프런트매터(frontmatter)를 파싱 및 직렬화하며, BRO 페이로드를 KOMARC 형식으로 변환하는 통합 도구 세트를 제공합니다.

설치

선호하는 패키지 매니저를 사용하여 라이브러리를 설치할 수 있습니다:

pnpm

pnpm add @slat.or.kr/bro-schema

npm

Bash

npm install @slat.or.kr/bro-schema

yarn

Bash

yarn add @slat.or.kr/bro-schema

주요 기능

• 스키마 유효성 검사 (Schema Validation): @cfworker/json-schema를 사용하여 공식 BRO JSON 스키마를 기준으로 JSON 객체의 유효성을 검사합니다.
• TypeScript 타입 지원: BRO 스키마에 대한 완전한 타입의 인터페이스를 제공합니다 (예: BibliographicReactionObjectBRO, ArticleBaseProperties).
• 엄격한 프런트매터 유틸리티 (Strict Frontmatter Utilities): 엄격한 YAML 프런트매터 분리 및 동적 OthersBundle 블록이 포함된 마크다운 파일을 파싱하고 직렬화합니다.
• KOMARC 변환: BRO 메타데이터 페이로드를 KOMARC(한국문헌자동화목록) 레코드로 변환합니다.

사용법

1. 스키마 유효성 검사

표준을 준수하는지 확인하기 위해 BRO 스키마를 기준으로 페이로드의 유효성을 검사합니다.

TypeScript

import { validateBroSchema } from '@slat.or.kr/bro-schema';

const payload = {
  "@context": "[https://schema.org](https://schema.org)",
  "@type": "Article",
  "about": {
    "@type": "Book",
    "isbn": "9788937460753",
    "name": "위대한 개츠비"
  },
  "author": {
    "@type": "Person",
    "name": "F. 스콧 피츠제럴드"
  },
  "text": "아메리칸 드림에 관한 매혹적인 책입니다."
};

const result = validateBroSchema(payload);

if (result.valid) {
  console.log("유효한 BRO 스키마입니다!");
} else {
  console.error("유효성 검사 오류:", result.errors);
}

2. TypeScript 타입

생성된 TypeScript 인터페이스를 가져와(import) 애플리케이션에서 엄격한 타입 지정을 적용할 수 있습니다.

TypeScript

import type { BibliographicReactionObjectBRO, ArticleBaseProperties } from '@slat.or.kr/bro-schema';

const myArticle: ArticleBaseProperties = {
  "@context": "[https://schema.org](https://schema.org)",
  "@type": "Article",
  about: {
    "@type": "Book",
    isbn: "9781234567897"
  },
  author: {
    "@type": "Person",
    name: "홍길동"
  },
  text: "나의 리뷰 콘텐츠입니다."
};

3. 프런트매터 파싱 및 직렬화

엄격한 YAML 프런트매터(title, keywords)와 동적 번들(others)이 포함된 마크다운 파일을 파싱합니다.

import { parseFrontmatter, serializeFrontmatter } from "@slat.or.kr/bro-schema";

const markdownString = `---
title: "도서 리뷰"
keywords: ["소설", "고전"]
---

\`\`\`json:others
{"others": [{"rating": 5}, {"readDate": "2024-04-11"}]}
\`\`\`

여기 제 리뷰가 있습니다...`;

// 파싱
const { data, others, content } = parseFrontmatter(markdownString);

console.log(data.title); // "도서 리뷰"
console.log(data.keywords); // ["소설", "고전"]
console.log(others); // [{ rating: 5 }, { readDate: "2024-04-11" }]
console.log(content); // "여기 제 리뷰가 있습니다..."

// 직렬화
const reconstructedMarkdown = serializeFrontmatter(data, others, content);

4. KOMARC 변환

BRO 페이로드(또는 아티클의 ItemList)를 표준 KOMARC 필드로 변환합니다.

import { convertBroToKomarc } from "@slat.or.kr/bro-schema";

const komarcRecord = convertBroToKomarc({
  "@context": "https://schema.org",
  "@type": "Article",
  dateCreated: "2024-04-11T15:00:00Z",
  about: {
    "@type": "Book",
    isbn: "9788937460753",
  },
  author: {
    "@type": "Person",
    name: "김철수",
  },
  text: "초록 텍스트...",
});

console.log(JSON.stringify(komarcRecord, null, 2));
// 출력 결과에는 올바르게 매핑된 020 (ISBN), 100/700 (저자) 및 552 (로컬 메타데이터) 필드가 포함됩니다.

라이선스

Apache-2.0