Skip to content

1.0 Semantic Contract

Jump to bottom
유용태 edited this page Jun 18, 2026 · 2 revisions

1.0 Semantic Contract

json-document 1.x 호환성은 export 이름만 유지한다는 뜻이 아니다. 제품은 call shape, result branch, error code, atomicity, selection/history 복구, clipboard 기본값에 의존한다. 이 페이지는 1.0에서 고정된 공개 계약을 API 사용자 관점에서 정리한다.

고정 대상

  1. Public import는 @interactive-os/json-document와 @interactive-os/json-document/react다.
  2. 모든 result family는 ok discriminant를 유지한다.
  3. 실패 result의 stable branch key는 code다.
  4. reason은 진단 문구이며 정확한 문자열로 분기하지 않는다.
  5. Schema failure의 violations[].path는 JSON Pointer다.
  6. strict 기본값은 false다.
  7. 실패한 mutation은 value, selection, clipboard, history, subscriber event를 부분 변경 상태로 남기지 않는다.
  8. commit(..., { selectionAfter })는 patch와 final selection을 같은 history entry에 기록한다.
  9. undo()와 redo()는 top-level command로 JSONCapabilityResult를 반환한다.
  10. 여러 source clipboard payload를 array insertion target에 paste하면 기본적으로 item별 sibling insert가 된다.
  11. 함수와 method의 overload, option field, placement target call shape는 public API 일부다.

Signature Contract

1.0에서 고정되는 것은 이름만이 아니다. 다음 호출 형태는 사용자 코드가 컴파일 시점에 의존하는 공개 계약이다.

createJSONDocument(Schema, input);
createJSONDocument(Schema, output, { trustedInitial: true });

doc.insert(value);
doc.insert(target, value, options);

doc.move(source, target);
doc.move(target);

doc.paste(target, options);
doc.canPaste(target, options);

React entrypoint도 같은 trusted/untrusted 초기값 overload를 유지한다.

useJSONDocument(Schema, input);
useJSONDocument(Schema, output, { trustedInitial: true });

Placement target은 다음 모양을 공개 API로 유지한다.

type JSONDocumentInsertTarget =
  | Pointer
  | { into: Pointer }
  | { before: Pointer }
  | { after: Pointer };

type JSONDocumentMoveTarget = JSONDocumentInsertTarget;

type JSONDocumentPasteTarget =
  | JSONDocumentInsertTarget
  | { replace: Pointer };

{ at: Pointer }는 paste target이 아니다. 삽입 위치를 직접 지정하려면 pointer 문자열을 그대로 넘긴다.

Result Code

앱은 실패를 reason 문구가 아니라 code로 분류한다.

const result = doc.canReplace("/title", 1);

if (!result.ok) {
  switch (result.code) {
    case "schema_violation":
      result.violations;
      break;
    case "invalid_pointer":
    case "path_not_found":
      result.pointer;
      break;
  }
}

reason은 logging, debug panel, 개발자 진단에 적합하다. Localization이나 제품 분기 조건은 code, pointer, violations 같은 구조를 사용한다.

Strict Policy

기본 document는 실행 실패를 throw하지 않고 result로 반환한다.

const doc = createJSONDocument(Schema, initial);
const result = doc.patch({ op: "replace", path: "/title", value: 1 });

strict: true를 명시하면 patch, commit, load, reset 같은 execution method가 JSONDocumentError를 throw할 수 있다. can*, schema query, clipboard write 같은 non-execution API는 strict mode에서도 result surface를 유지한다.

Atomicity

Mutation은 전부 성공하거나 전부 실패한다.

const before = doc.value;
const beforeSelection = doc.selection?.snapshot();

const result = doc.commit(operations, {
  selectionAfter: "/items/2",
});

if (!result.ok) {
  // value와 selection은 실패 전 상태로 남아 있다.
  doc.value;
  doc.selection?.snapshot();
}

실패한 mutation은 subscriber에게 성공한 patch stream event처럼 보이면 안 된다. History stack도 실패한 변경을 undo 가능한 entry로 기록하면 안 된다.

Selection And History

selectionAfter를 제공하면 core auto tracking보다 explicit final selection이 우선한다.

doc.commit([
  { op: "replace", path: "/items/0/title", value: "Ready" },
], {
  label: "rename",
  selectionAfter: "/items/0",
});

이 selection은 patch 적용 이후 document state 기준으로 복원된다. Undo/redo는 value와 selection을 같은 history entry에서 복원한다.

명시 selection이 없으면 core는 applied JSON Patch를 기준으로 기존 selection을 tracking/recover한다. 구조 편집 extension처럼 다음 focus를 정확히 아는 코드라면 selectionAfter를 제공하는 편이 좋다.

Clipboard Spread

Clipboard는 browser clipboard가 아니라 document instance 안의 headless buffer다.

doc.copy(["/items/0", "/items/1"]);
doc.paste("/items/-");

여러 source를 copy/cut한 clipboard payload는 array insertion target에서 기본적으로 펼쳐진다. 외부 payload를 직접 넣는 경우에는 doc.insert(target, payload, { spread: true })를 사용해 같은 sibling insert 의미를 명시한다.

검증 위치

이 계약은 다음 repo 산출물로 보호된다.

  • packages/json-document/public-contract.json: public export name lock
  • docs/standard/result-contract.md: result/error code 의미론
  • docs/standard/selection-contract.md: selection 의미론
  • docs/standard/schema-introspection-contract.md: schema query 의미론
  • packages/json-document/tests/public/standard-conformance.test.ts: 표준 적합성 흐름
  • packages/json-document/tests/public/semantic-contract.test.ts: breaking-risk fixture
  • packages/json-document/tests/public/signature-contract.test-d.ts: public call shape fixture
  • scripts/evaluate-standardization.mjs: release gate에서 위 산출물 존재와 핵심 패턴 확인

Clone this wiki locally