Part.4 · Contract·Document 작성

Contract & Document: 작업 선언과 지원 대상의 연결

첫 문서 실습: 파일 저장부터 Helper 인계까지

목표: 아래의 완전한 소스 Document를 quality-document.json으로 저장하고 문법을 확인합니다. 이 파일은 소스 선언만 담습니다. SDK/Helper의 전체 요청이나 GAPE 매니페스트가 아닙니다.

1. 조직이 허용한 새 작업 폴더를 만들고 텍스트 편집기를 엽니다. 아래 JSON 블록의 {부터 마지막 }까지만 복사합니다. 코드 울타리와 json 표시는 파일에 넣지 않습니다.
2. 파일 이름을 quality-document.json, 인코딩을 UTF-8로 저장합니다. Word/서식 문서 형식이 아닌 일반 텍스트를 사용하고 .json.txt가 붙지 않았는지 확인합니다. 저장한 파일을 다시 열어 operations.read_quality가 있는지 읽습니다.
3. macOS/Linux에 Python 3가 이미 준비돼 있다면 아래 명령을 사용합니다. Windows는 PowerShell의 내장 JSON 파서를 사용할 수 있으므로 이 실습 때문에 Python 설치가 필수는 아닙니다.
4. 문법 통과 후 properties의 resource/component/score와 각 required 목록을 대조합니다. 이 검토와 JSON 파싱은 제품의 의미 검증을 대신하지 않습니다.
5. 원본 사본을 보존한 뒤 공급자가 제공한 전체 요청의 draft.source에 문서 객체를 넣습니다. 파일 경로 문자열이나 JSON을 이중 인코딩한 문자열을 넣지 않습니다. 대상 참조·매핑·fixture는 제공된 요청에서 별도로 확인하고 Helper 첫 준비 실습으로 이동합니다.

document_path="/absolute/path/quality-document.json"
python3 -m json.tool "$document_path"

$documentPath = 'C:\absolute\path\quality-document.json'
Get-Content -LiteralPath $documentPath -Raw -Encoding UTF8 -ErrorAction Stop | ConvertFrom-Json -ErrorAction Stop | Format-List
Get-FileHash -LiteralPath $documentPath -Algorithm SHA256

기대 결과: JSON 파서는 객체를 표시하고 파싱 오류를 내지 않습니다. 문법 오류라면 줄/열과 쉼표·따옴표·중괄호를 확인합니다. 이 파서는 중복 키나 제품 미지원 스키마 전체를 판정하지 않습니다. 문법 확인 완료 / Helper 의미 검증 미실행으로 기록하고, 실제 Helper 결과가 나왔을 때 별도 추가합니다.

작은 수정 연습: 새 사본에서 입력 이름을 바꾸려면 properties, required, 요청의 명시적 매핑과 지원 대상 영향을 함께 검토합니다. 처음에는 제공된 원본으로 한 번 확인한 뒤 바꾸십시오. DOC-1/2 사례는 이름 불일치와 전체 요청 누락을 다룹니다.

수정 중인 산출물 구분

범위가 정해진 소스 Document 작성

1. 짧은 목표와 데이터 경계를 적습니다. 예: read_quality는 리소스 이름을 받아 구성요소 이름과 품질 점수를 문자열로 반환합니다. 리소스를 변경하지 않습니다.
2. 지원되는 CUSTOM_API 형식에서 document_kind는 CUSTOM_API, protocol_revision은 지원되는 값으로 하고 operations 아래에 read_quality를 둡니다. input_schema는 필수 resource 문자열을 가진 object, output_schema는 필수 component와 score 문자열을 가진 object로 선언합니다. 문장 속 필드 이름은 설명이며 완전한 JSON 파일이 아니므로 구두점과 중첩은 아래의 완전한 예시를 사용하십시오.
3. 속성 이름과 required 목록을 일치시킵니다. 제한된 예시는 지원되는 기본 자료형만 받습니다. 중첩 object·배열·추가 JSON Schema 키워드·중복 키·주석이 묵시적으로 허용되지는 않습니다. 자격 증명이나 실제 운영 응답을 schema의 기본값·설명에 넣지 않습니다.
4. 로컬 사본에서 앞의 OS별 파서 명령으로 JSON 문법을 확인합니다. 문법 PASS는 JSON 파싱만 증명합니다. 수정할 때 원본과 지문을 보존합니다.
5. 공급자가 게시한 정확한 기능·Contract·어댑터·작업·리비전 식별자를 확보합니다. 이 참조는 독립 소스 Document가 아니라 릴리스가 정한 요청 envelope에 넣습니다. 이후 Integration Helper 준비 절차를 따릅니다.

완전한 소스 Document 예시

아래 CUSTOM_API 예시는 읽기 전용 read_quality 작업을 선언합니다. 실제 API를 호출하거나 제품 Contract를 만들지 않습니다. JSON을 quality-document.json으로 저장하고 해당 릴리스가 제공한 완전한 요청의 draft.source에 넣은 뒤 호환되는 지원 대상 참조를 지정하십시오.

{
  "document_kind": "CUSTOM_API",
  "protocol_revision": "1",
  "operations": {
    "read_quality": {
      "input_schema": {
        "type": "object",
        "properties": {"resource": {"type": "string"}},
        "required": ["resource"]
      },
      "output_schema": {
        "type": "object",
        "properties": {
          "component": {"type": "string"},
          "score": {"type": "string"}
        },
        "required": ["component", "score"]
      }
    }
  }
}

python3 -m json.tool quality-document.json > /dev/null
sha256sum quality-document.json

첫 명령은 JSON 문법만 확인합니다. macOS는 shasum -a 256 quality-document.json, Windows PowerShell은 Get-FileHash -Algorithm SHA256 quality-document.json을 사용하십시오. 완전한 envelope·대상·매핑의 적합성은 Helper의 타입 판정으로 별도 확인해야 합니다.

예시: JSON은 유효하지만 대상 리비전이 다름

소스 Document가 파싱되고 발견 단계에서 read_quality가 받아들여졌지만 요청은 다른 릴리스의 어댑터 리비전을 참조합니다. 정규화 단계는 대상을 거부합니다. 릴리스 매니페스트와 공급자 참조를 대조하고, 승인된 호환 값이 실제로 있을 때만 새 요청의 대상 리비전을 바로잡습니다. 소스 작업 이름만 바꿔 우연히 맞추면 불일치를 숨기게 됩니다.

예시: 필드 이름만 바꾸고 required를 그대로 둠

편집자가 입력 속성 resource를 resource_name으로 바꾸고 required: ["resource"]는 그대로 둡니다. JSON 문법은 유효하지만 선언 의미가 일치하지 않습니다. 속성을 되돌리거나 required 목록을 고친 뒤 같은 로컬 파서와 Helper 검증을 다시 수행하십시오. 문법 검사 통과를 Contract 검증으로 해석하지 않습니다.

완료 증거

소스 Document의 리비전·지문, 게시된 대상 참조, 요청 신원, 타입이 정해진 Helper 결과와 남은 승인 담당자를 보관합니다. 실제 인증·등록·런타임 증거 전에는 “연결됨”, Work와 영수증 전에는 “실행됨”이라고 표시하지 않습니다.

단계별 실제 사용 용례

예를 들어 읽기 전용 품질 조회에 출력 필드 하나를 추가하려고 합니다. 사람용 목표, 소스 스키마, 대상 참조와 전체 요청 envelope를 각각 구분합니다. 출력 속성과 required 목록, 실제 합성 응답, 명시적 매핑을 함께 검토하고 지원되지 않는 스키마 확장은 그대로 별도 구현 요구로 남깁니다. 제품이 발행한 Contract를 고객 문서로 대체하지 않습니다.

증상별 확인과 복귀 확인

다음 담당자에게 넘길 최소 기록

인계 항목: 소스 Document 리비전·지문, 요청 envelope 리비전, 게시된 Contract·어댑터 참조, 매핑 규칙, 합성 입력·예상 출력, 문법·의미 검증 결과와 변경 이유. 실제 값이 없는 템플릿과 실행 가능한 전체 요청을 구분합니다.

도구별 문제 해결 사례 읽기

다음은 지원되는 입력·명령·권한 경계를 바탕으로 구성한 교육용 사례입니다. 제품의 실제 상태·사유와 함께 읽고, 자신의 실행 기록 없이 예시의 결과를 성공 이력으로 사용하지 않습니다. 온라인과 오프라인 환경 모두에 적용되는 확인 항목과 선택 의존성 경로에만 해당하는 항목을 구별합니다.

상세 예시 DOC-1: 속성 이름만 바꾸고 required는 그대로 둠

상황: 입력 속성 resource를 resource_name으로 바꿨지만 required에는 resource가 남아 있습니다. JSON 문법 검사는 통과해도 선언의 의미는 일치하지 않습니다.

관찰을 이렇게 나눠 읽습니다.

• 문법: JSON 파싱은 가능합니다.
• 선언: properties와 required가 다른 이름을 가리킵니다.
• 대상·매핑: 소스 변경의 영향을 따로 확인해야 합니다.

확인·조치 순서:

1. 전체 소스 Document와 원본 리비전·지문을 보존합니다.
2. 실제 의도한 입력 이름을 정하고 속성·required·명시적 매핑을 지원 범위 안에서 맞춥니다.
3. 로컬 JSON 문법과 Helper 의미 검증을 각각 수행하고 결과를 구분합니다.

다음 단계로 돌아갈 조건: 문법과 의미 검증이 모두 확인된 새 요청을 후속 준비에 사용합니다.

해결되지 않았을 때: 지원되지 않는 스키마 확장은 임의로 허용하지 않고 추가 구현 요구로 남깁니다.

상세 예시 DOC-2: 소스 Document 발췌를 전체 요청으로 실행함

상황: 사용자는 안내서의 짧은 CUSTOM_API 예시만 저장해 Helper 또는 SDK 입력으로 보냅니다. 소스 설명은 맞지만 요청·대상·매핑·합성 응답을 포함한 전체 envelope는 아닙니다.

관찰을 이렇게 나눠 읽습니다.

• 소스 Document: draft.source에 들어갈 자료입니다.
• 전체 요청: request_id·correlation_id·draft와 지원 참조가 필요합니다.
• 발췌: 필드를 설명하는 예시이며 바로 실행 가능한 전체 입력이 아닙니다.

확인·조치 순서:

1. 제공된 버전에 맞는 전체 요청 템플릿을 확보하고 원본을 보존합니다.
2. 소스·대상·매핑·합성 응답을 각각의 정해진 위치에 채웁니다. 비밀값·실제 고객 응답은 넣지 않습니다.
3. 문법 확인 뒤 제품의 analyze 또는 Helper 단계 판정으로 의미를 확인합니다.

다음 단계로 돌아갈 조건: 완전한 요청과 게시된 대상이 지원 범위 안에서 검증됐을 때 후보 준비로 진행합니다.

해결되지 않았을 때: 필수 대상 참조가 없으면 설명용 값을 실제 식별자로 추측해 사용하지 않습니다.

설치 후 도구 목록