About

A spec is a document with rules about itself

Last updated 22 November 2026

Most formats ask you to be careful. OpenAPI writes down what it expects and then waits to be checked against it, which is an unusual thing for a file to do.

Three readers, no library

The first reader is YAML. It walks the text line by line, keeping the indentation that gives the document its shape, and understands the parts a real spec uses: block and flow collections, plain and quoted scalars, block scalars with their chomping, comments, anchors and aliases, and the merge key. It is not a general YAML 1.2 implementation, and it says so when it meets something it does not know.

The second reader is JSON, through the browser's own parser. When that refuses the text, a small reader written here walks the same text again, because the browser's message names the problem but not the place, and a place is what you need.

The third and last reader is the checker. It does not parse anything. It walks the tree the first two readers built and compares it with the rules the specification sets for paths, operations, parameters, responses and references.

What the checker reads

A path that does not start with a slash, an operation with no responses, a response key that is not a status, a parameter with no name or no place, a path parameter that is not required, a template brace with no parameter behind it, a parameter declared for a place the path does not have, an operationId used twice, a security scheme that is not declared, a tag that is used but never described, and a local reference that resolves to nothing. Each finding names the operation it belongs to and the pointer into the document.

Two checks depend on the version. A 3.1 document that still writes nullable, and a 3.0 document that writes a list of types, are both reported, because each one is the other version's habit.

Where the trees come from

Every reference inside the document is resolved before a schema is drawn, so an Order that appears in five responses is read once and shown in five places. A reference that points at itself stops after one turn and is marked as a cycle rather than followed forever. A reference to another file or another host is not resolved at all: that would be a network request, and this page makes none.

The three writers

The cURL snippet fills the path from the parameter's example, or from the first value its schema suggests, and adds the query pairs and the declared headers. The fetch snippet is the same call in a form you can paste into a module. The TypeScript writer walks the request and response schemas, writes an interface for every named schema they touch, and then a function that returns the response type rather than any. None of the three is a client generator: they are a way to see what the document says, in the shape you will actually type.

Where it stops

Who made it

Pikkola Lab builds small tools that keep the work in the browser. This is tool No. 64. Write to hello@pikkola.com with a document that reads badly, and say which line the reader lost.

Back to the studio

소개

스펙은 자기 규칙을 적어 둔 문서입니다

최종 수정 2026년 11월 22일

대부분의 형식은 조심하라고 말합니다. OpenAPI는 자기가 무엇을 기대하는지 적어 두고, 그 규칙으로 자기를 검사받기를 기다립니다. 파일이 하기로는 드문 일입니다.

라이브러리 없이 세 번

첫 번째 리더는 YAML입니다. 줄을 하나씩 넘기며 문서의 모양을 만드는 들여쓰기를 지키고, 실제 스펙이 쓰는 것들을 알아봅니다. 블록과 흐름 컬렉션, 평문과 인용 문자열, 블록 스칼라와 그 끝 처리, 주석, 앵커와 별칭, 병합 키까지입니다. YAML 1.2 전체 구현은 아니고, 모르는 것을 만나면 모른다고 말합니다.

두 번째 리더는 JSON이고, 브라우저의 파서를 씁니다. 브라우저가 거절하면 여기서 쓴 작은 리더가 같은 글을 다시 걸어갑니다. 브라우저의 메시지는 무엇이 문제인지는 알려 주지만 어디인지는 알려 주지 않고, 필요한 것은 그 자리이기 때문입니다.

세 번째이자 마지막 리더는 검사기입니다. 아무것도 파싱하지 않습니다. 앞의 두 리더가 만든 트리를 걸으며, 규격이 경로와 오퍼레이션, 파라미터, 응답, 참조에 정해 둔 규칙과 견줍니다.

검사기가 읽는 것

슬래시로 시작하지 않는 경로, 응답이 없는 오퍼레이션, 상태가 아닌 응답 키, 이름이나 위치가 없는 파라미터, 필수가 아닌 경로 파라미터, 뒤에 파라미터가 없는 템플릿 중괄호, 경로에 없는 자리를 선언한 파라미터, 두 번 쓰인 operationId, 선언되지 않은 보안 스킴, 쓰이기만 하고 설명이 없는 태그, 아무것도 가리키지 않는 내부 참조를 찾습니다. 발견한 것마다 어느 오퍼레이션인지와 문서 안의 위치를 함께 적습니다.

두 가지는 판에 따라 다릅니다. 3.1 문서에 아직 nullable이 남아 있거나, 3.0 문서에 타입 목록이 적혀 있으면 둘 다 알려 줍니다. 서로의 판에서 온 버릇이기 때문입니다.

트리는 어디서 오나

스키마를 그리기 전에 문서 안의 참조를 모두 풉니다. 다섯 응답에 나오는 Order는 한 번 읽고 다섯 자리에 보여 줍니다. 스스로를 가리키는 참조는 한 바퀴 돌고 멈추며, 끝없이 따라가지 않고 순환이라고 표시합니다. 다른 파일이나 다른 호스트를 가리키는 참조는 아예 풀지 않습니다. 네트워크 요청이 되고, 이 페이지는 요청을 하지 않습니다.

쓰는 쪽 셋

cURL 조각은 파라미터의 예시나 스키마가 제안하는 첫 값으로 경로를 채우고, 쿼리와 선언된 헤더를 붙입니다. fetch 조각은 같은 호출을 모듈에 붙일 수 있는 모양으로 씁니다. TypeScript 쪽은 요청과 응답 스키마를 걸으며, 닿는 이름 있는 스키마마다 인터페이스를 쓰고, any가 아니라 응답 타입을 돌려주는 함수를 씁니다. 셋 다 클라이언트 생성기는 아닙니다. 문서가 말하는 것을 실제로 칠 모양으로 보여 주는 방법입니다.

멈추는 곳

만든 곳

피콜라 랩은 작업을 브라우저 안에 두는 작은 도구를 만듭니다. 이것은 64호기입니다. 읽히지 않는 문서가 있으면 hello@pikkola.com으로 보내 주세요. 리더가 어느 줄에서 길을 잃었는지 알려 주시면 됩니다.

스튜디오로 돌아가기

概要

仕様は、自分の規則を書いた文書です

最終更新 2026年11月22日

ほとんどの形式は気をつけてと言います。OpenAPI は自分が何を期待するかを書き、その規則で自分を検査されるのを待ちます。ファイルとしては珍しいことです。

ライブラリなしで三度

最初の読み手は YAML です。行を一つずつたどり、文書の形を作る字下げを守り、実際の仕様が使うものを理解します。ブロックとフローのコレクション、素の文字列と引用した文字列、終わりの扱いを含むブロックスカラー、コメント、アンカーと別名、マージキーまでです。YAML 1.2 の完全な実装ではなく、知らないものに出会えば知らないと言います。

二番目の読み手は JSON で、ブラウザのパーサーを使います。ブラウザが断ったら、ここで書いた小さな読み手が同じ文字をもう一度たどります。ブラウザの知らせは何が問題かを伝えますが、どこかは伝えないからです。必要なのはその場所です。

三番目で最後の読み手は検査です。何も解析しません。前の二つが作った木をたどり、仕様が経路、オペレーション、パラメータ、応答、参照に定めた規則と照らします。

検査が読むもの

スラッシュで始まらない経路、応答のないオペレーション、状態でない応答キー、名前か場所のないパラメータ、必須でない経路パラメータ、後ろにパラメータのない雛形の波括弧、経路にない場所を宣言したパラメータ、二度使われた operationId、宣言されていないセキュリティ方式、使われるだけで説明のないタグ、何も指さない内部参照を探します。見つけたものには、どのオペレーションかと文書内の位置を添えます。

二つは版によって変わります。3.1 の文書にまだ nullable が残っていたり、3.0 の文書に型の一覧が書かれていたりすれば、どちらも知らせます。互いの版から来た癖だからです。

木はどこから来るか

スキーマを描く前に、文書内の参照をすべて解きます。五つの応答に出てくる Order は一度だけ読み、五か所に示します。自分を指す参照は一周して止まり、果てしなくたどらずに循環だと示します。別のファイルや別のホストを指す参照は解きません。ネットワーク要求になり、このページは要求をしないからです。

書く側の三つ

cURL の断片は、パラメータの例かスキーマが示す最初の値で経路を埋め、クエリと宣言されたヘッダーを付けます。fetch の断片は同じ呼び出しをモジュールに貼れる形で書きます。TypeScript は要求と応答のスキーマをたどり、触れる名前のあるスキーマごとにインターフェースを書き、any ではなく応答の型を返す関数を書きます。どれもクライアント生成器ではありません。文書が言っていることを、実際に打つ形で見せる方法です。

止まる場所

作ったところ

Pikkola Lab は仕事をブラウザの中に置く小さな道具を作ります。これは 64 号機です。読めない文書があれば hello@pikkola.com まで。読み手がどの行で道に迷ったかを教えてください。

スタジオに戻る