About
Tool No. 45 of Pikkola
A schema is the part of a payload that survives the payload. Writing one by hand is slow, and copying one from a coworker's repository is how two services end up disagreeing about the same field. This page reads a real payload and writes the shape down in five languages, then checks another payload against it.
What it does
- Reads any JSON value and describes its shape: objects, arrays, strings, integers, numbers, booleans and null, in any amount of nesting.
- Merges the rows of an array. A key that appears in every row stays required, a key that some rows leave out becomes optional, and a value that is null in one row and a string in another becomes a union of both.
- Writes the same shape five ways: JSON Schema in draft 2020-12 or draft 07, TypeScript as an interface or a type, a Zod schema, a Go struct and a Python TypedDict.
- Reads a JSON Schema and a test payload and reports every failing value by path, with the keyword that failed. The path is the kind a stack trace uses: $.items[1].quantity, not a line number.
- Four presets, so the tool is useful before you paste anything: a SaaS user, an e-commerce order, a webhook event and a config file.
- English, Korean and Japanese, a light and a dark theme, and a phone layout that does not scroll sideways.
How a value becomes a shape
Every value is walked once. A string becomes a string, a whole number becomes an integer, a number with a fraction becomes a number, an object becomes a set of properties, and an array becomes an array of whatever its items are. Nothing is guessed from a key name.
An array is where the interesting part happens. The items are merged pairwise, so an array of thirty rows produces one shape that all thirty satisfy. A property that all rows carry is required; a property that only some rows carry is optional, and the count of rows is kept so the writers know how many times a key went missing. When two items disagree about a type, the result is a union rather than a guess, and the JSON Schema output writes it as anyOf.
One object is the weakest evidence there is, and the tool does not pretend otherwise: with a single row, every key in it is required. Pasting an array of two or three real rows is the single most useful thing a person can do here.
Formats, read from values
A format is only claimed when the value shows it. A string that parses as an ISO 8601 timestamp gets format date-time, one shaped like an address gets email, one shaped like a UUID gets uuid, one that starts with a scheme and two slashes gets uri, and a dotted quad gets ipv4. A plain word gets no format at all, which is the honest answer.
The writers use the format where the language has something for it. Zod gets .email(), .uuid() and .datetime({ offset: true }); Go and Python get a plain string, because their standard library has no such type; TypeScript gets string, because the format is a runtime fact. The JSON Schema keeps the format keyword, which is where it belongs.
What the validator checks
The schema keywords understood here are type, required, properties, items (as a schema or as a tuple), additionalProperties, enum, const, minimum, maximum, exclusiveMinimum, exclusiveMaximum, multipleOf, minLength, maxLength, pattern, format, minItems, maxItems, anyOf, oneOf, allOf, not and a local $ref such as #/$defs/Row. Format is enforced as a check, not left as an annotation, because a person who wrote email in a schema wants to know when a value is not one.
Everything else is left alone rather than half-implemented. A remote $ref is not fetched, since the page cannot make a network request by design. unevaluatedProperties, dependentSchemas, if and then, contentEncoding and the 2019-09 vocabulary are not interpreted. A schema that uses them will still be read, but those keywords simply do not add or remove a failure.
One run lists every failure, not just the first. That is a deliberate difference from the way a validator stops at the first exception: the point of the tab is to see all of the problems in a payload at once, so they can be fixed in one pass.
The five writers
Nested objects become named types in TypeScript, Go and Python, and inline objects in Zod. A property that holds an array of objects becomes a singular type, so items becomes Item and addresses becomes Address. Property names that are not valid identifiers are quoted. Go field names follow the language's habit of capitalising initialisms, so id becomes ID and avatar_url becomes AvatarURL, while the JSON tag keeps the wire name exactly.
Go and Python mark an optional member with a pointer and NotRequired respectively, and both keep the wire name in the tag or the key. Zod chains .optional() and .nullable() so the schema fails in the same places the JSON Schema would.
What it deliberately does not do
- It does not decide that a field is an enum, or that a number has a range, from one example. Both are guesses that would break the first payload that tried a new value.
- It does not fetch a schema from a URL, resolve a remote reference, or look at anything beyond the text in the two boxes.
- It does not read JSON5, JSON Lines or a JSON document with comments. It reads JSON, and says so when the text is not.
- It does not store a schema on a server. Your text, your tab and your options live in this browser, and nowhere else.
- No account, no upload, no analytics, no cookies, no fonts or scripts from another server.
Why it is free
Pikkola builds small tools that do one job and keeps them free, with no account and no advertising. A static page that does its work in the browser costs almost nothing to serve, so there is no reason to charge for it.
Contact
A shape that is written wrongly in Korean or Japanese, a keyword that should be supported, a payload that breaks the page: hello@pikkola.com. Send the smallest payload that shows the problem, and what you expected to see.
소개
피콜라의 45번째 도구
스키마는 페이로드가 사라진 뒤에도 남는 부분입니다. 손으로 적으면 느리고, 동료의 저장소에서 복사하면 두 서비스가 같은 필드를 다르게 믿게 됩니다. 이 페이지는 실제 페이로드를 읽어 다섯 언어로 모양을 적고, 다른 페이로드가 그 모양에 맞는지 검사합니다.
하는 일
- 어떤 JSON 값이든 읽어 모양을 설명합니다. 객체, 배열, 문자열, 정수, 숫자, 참·거짓, null을 깊이에 상관없이 다룹니다.
- 배열의 행을 합칩니다. 모든 행에 있는 키는 필수로 남고, 일부 행에만 있는 키는 선택이 되며, 어떤 행에서 null이고 다른 행에서 문자열이면 둘을 합친 타입이 됩니다.
- 같은 모양을 다섯 가지로 적습니다. JSON 스키마(2020-12 초안 또는 07 초안), 타입스크립트 인터페이스나 타입, Zod 스키마, Go 구조체, 파이썬 TypedDict입니다.
- JSON 스키마와 시험용 페이로드를 읽어 실패한 값마다 경로와 키워드를 적습니다. 경로는 스택 트레이스가 쓰는 모양입니다. 줄 번호가 아니라 $.items[1].quantity입니다.
- 외워 둘 만한 예시 네 가지. SaaS 사용자, 이커머스 주문, 웹훅 이벤트, 설정 파일입니다. 붙여 넣기 전에도 도구를 써 볼 수 있습니다.
- 영어, 한국어, 일본어와 밝은 테마, 어두운 테마, 옆으로 넘어가지 않는 휴대폰 화면까지.
값이 모양이 되는 과정
모든 값은 한 번씩 지나갑니다. 문자열은 문자열, 소수점이 없는 수는 정수, 소수점이 있는 수는 숫자, 객체는 속성의 묶음, 배열은 항목들이 이룬 모양의 배열이 됩니다. 키 이름으로 무엇인가를 짐작하지는 않습니다.
흥미로운 일은 배열에서 일어납니다. 항목을 둘씩 합쳐서, 서른 행의 배열은 서른 행이 모두 만족하는 모양 하나가 됩니다. 모든 행에 있는 속성은 필수이고, 일부 행에만 있는 속성은 선택입니다. 행 수를 함께 들고 있어서 각 출력이 그 키가 몇 번 빠졌는지 압니다. 두 항목의 타입이 다르면 짐작하지 않고 합집합으로 적고, JSON 스키마 출력은 이를 anyOf로 씁니다.
객체 하나는 가장 약한 증거이고, 도구는 그 사실을 숨기지 않습니다. 행이 하나면 그 안의 모든 키가 필수가 됩니다. 실제 행 두세 개를 배열로 붙여 넣는 것이 여기서 사람이 할 수 있는 가장 쓸모 있는 일입니다.
값에서 읽는 형식
형식은 값이 보여 줄 때만 주장합니다. ISO 8601 시각으로 읽히는 문자열은 date-time, 주소 모양이면 email, UUID 모양이면 uuid, 스킴과 슬래시 두 개로 시작하면 uri, 점으로 나뉜 네 숫자면 ipv4가 됩니다. 그냥 단어면 형식이 없습니다. 그게 정직한 답입니다.
출력은 그 언어에 해당하는 것이 있을 때 형식을 씁니다. Zod는 .email(), .uuid(), .datetime({ offset: true })를 쓰고, Go와 파이썬은 문자열을 씁니다. 표준 라이브러리에 그런 타입이 없기 때문입니다. 타입스크립트도 문자열입니다. 형식은 실행 시점의 사실이기 때문입니다. JSON 스키마에는 format 키워드가 그대로 남습니다. 그 자리가 제자리입니다.
검증기가 보는 것
여기서 이해하는 스키마 키워드는 type, required, properties, items(스키마 또는 튜플), additionalProperties, enum, const, minimum, maximum, exclusiveMinimum, exclusiveMaximum, multipleOf, minLength, maxLength, pattern, format, minItems, maxItems, anyOf, oneOf, allOf, not, 그리고 #/$defs/Row 같은 문서 안의 $ref입니다. format은 주석으로 남기지 않고 검사로 적용합니다. 스키마에 email이라고 적은 사람은 그 값이 이메일이 아닐 때 알고 싶어 하기 때문입니다.
나머지는 절반만 구현하지 않고 건드리지 않습니다. 원격 $ref는 받아 오지 않습니다. 이 페이지는 설계상 네트워크 요청을 할 수 없습니다. unevaluatedProperties, dependentSchemas, if와 then, contentEncoding, 2019-09 어휘는 해석하지 않습니다. 그런 키워드를 쓴 스키마도 읽기는 하지만, 그 키워드가 실패를 더하거나 빼지는 않습니다.
한 번 돌리면 첫 오류에서 멈추지 않고 실패를 모두 적습니다. 검증기가 첫 예외에서 멈추는 방식과 일부러 다릅니다. 이 탭의 목적은 페이로드의 문제를 한 번에 다 보고 한 번에 고치는 것이기 때문입니다.
다섯 가지 출력
중첩된 객체는 타입스크립트, Go, 파이썬에서 이름 붙은 타입이 되고 Zod에서는 안쪽에 그대로 들어갑니다. 객체의 배열을 담은 속성은 단수형 타입이 됩니다. items는 Item, addresses는 Address입니다. 식별자로 쓸 수 없는 속성 이름은 따옴표로 감쌉니다. Go 필드 이름은 그 언어의 관례대로 약어를 대문자로 씁니다. id는 ID, avatar_url은 AvatarURL이 되고, JSON 태그에는 원래 이름이 그대로 남습니다.
Go는 포인터로, 파이썬은 NotRequired로 선택 항목을 표시하고, 둘 다 태그나 키에 원래 이름을 유지합니다. Zod는 .optional()과 .nullable()을 붙여서 JSON 스키마가 실패하는 자리에서 함께 실패합니다.
일부러 하지 않는 것
- 예시 하나를 보고 어떤 필드가 enum이라거나 숫자에 범위가 있다고 정하지 않습니다. 둘 다 짐작이고, 새 값을 처음 보내는 페이로드에서 곧바로 깨집니다.
- URL에서 스키마를 받아 오거나, 원격 참조를 풀거나, 두 상자 안의 글자 밖을 보지 않습니다.
- JSON5, JSON Lines, 주석이 붙은 JSON 문서는 읽지 않습니다. JSON을 읽고, 아닐 때는 그렇다고 말합니다.
- 스키마를 서버에 저장하지 않습니다. 입력한 글과 탭, 설정은 이 브라우저에만 남습니다.
- 계정도, 업로드도, 분석도, 쿠키도 없고, 다른 서버의 폰트나 스크립트도 쓰지 않습니다.
왜 무료인가
피콜라는 일 하나를 맡은 작은 도구를 만들고 무료로 둡니다. 계정도 광고도 없습니다. 브라우저에서 계산하는 정적 페이지는 띄우는 비용이 거의 들지 않으니 값을 받을 이유도 없습니다.
연락
한국어나 일본어 문장이 어색하거나, 있어야 할 키워드가 빠졌거나, 어떤 페이로드가 페이지를 깨뜨리면 hello@pikkola.com으로 알려 주세요. 문제를 보여 주는 가장 작은 페이로드와 기대한 결과를 함께 적어 주시면 좋습니다.
概要
Pikkola の 45番目のツール
スキーマは、ペイロードが消えたあとも残る部分です。手で書くと遅く、同僚のリポジトリから写すと、二つのサービスが同じフィールドを別々に信じるようになります。このページは実際のペイロードを読んで五つの言語で形を書き、別のペイロードがその形に合うかを検査します。
できること
- どんな JSON の値でも読み、形を説明します。オブジェクト、配列、文字列、整数、数値、真偽、null を、どれだけ深くても扱います。
- 配列の行をまとめます。すべての行にあるキーは必須のまま残り、一部の行だけにあるキーは任意になり、ある行で null、別の行で文字列なら二つを合わせた型になります。
- 同じ形を五通りに書きます。JSON Schema(2020-12 または 07)、TypeScript のインターフェースか型、Zod スキーマ、Go の構造体、Python の TypedDict です。
- JSON Schema と試験用ペイロードを読み、落ちた値ごとに経路とキーワードを示します。経路はスタックトレースと同じ形で、行番号ではなく $.items[1].quantity です。
- 覚えておきたい例が四つ。SaaS のユーザー、EC の注文、Webhook イベント、設定ファイルです。何も貼る前から試せます。
- 英語、韓国語、日本語、明るいテーマと暗いテーマ、横に流れない携帯の画面。
値が形になるまで
どの値も一度ずつ通ります。文字列は文字列、小数点のない数は整数、小数点のある数は数値、オブジェクトはプロパティの集まり、配列は中身が作る形の配列になります。キーの名前から何かを推測することはありません。
面白いのは配列です。項目を二つずつ合わせるので、三十行の配列は三十行すべてが満たす一つの形になります。すべての行にあるプロパティは必須、一部の行だけにあるプロパティは任意です。行の数も持っているので、各出力はそのキーが何回欠けたかを知っています。二つの項目で型が違えば推測せず合併型として書き、JSON Schema では anyOf になります。
オブジェクト一つは最も弱い証拠で、道具はそれを隠しません。行が一つなら、その中のキーはすべて必須になります。実際の行を二つ三つ、配列で貼るのが、ここで人ができるいちばん役に立つことです。
値から読む形式
形式は、値が示したときだけ名乗ります。ISO 8601 の時刻として読める文字列は date-time、住所の形なら email、UUID の形なら uuid、スキームとスラッシュ二つで始まれば uri、点で区切られた四つの数なら ipv4 です。ただの単語なら形式はありません。それが正直な答えです。
出力は、その言語に対応するものがあるときに形式を使います。Zod は .email()、.uuid()、.datetime({ offset: true })、Go と Python は文字列です。標準ライブラリにその型がないからです。TypeScript も文字列です。形式は実行時の事実だからです。JSON Schema には format キーワードがそのまま残ります。そこが本来の場所です。
検証器が見るもの
ここで理解するキーワードは type、required、properties、items(スキーマまたはタプル)、additionalProperties、enum、const、minimum、maximum、exclusiveMinimum、exclusiveMaximum、multipleOf、minLength、maxLength、pattern、format、minItems、maxItems、anyOf、oneOf、allOf、not、そして #/$defs/Row のような文書内の $ref です。format は注記ではなく検査として適用します。スキーマに email と書いた人は、その値がそうでないときに知りたいからです。
それ以外は半分だけ実装せず、触りません。外部の $ref は取りに行きません。このページは設計上ネットワーク要求ができません。unevaluatedProperties、dependentSchemas、if と then、contentEncoding、2019-09 の語彙は解釈しません。それらを使ったスキーマも読みますが、そのキーワードが失敗を増やしたり減らしたりはしません。
一度動かすと最初の誤りで止まらず、失敗をすべて書きます。検証器が最初の例外で止まるのとはわざと違います。このタブの目的は、ペイロードの問題を一度に全部見て、一度に直すことだからです。
五つの出力
入れ子のオブジェクトは TypeScript、Go、Python では名前の付いた型になり、Zod では内側にそのまま入ります。オブジェクトの配列を持つプロパティは単数の型になります。items は Item、addresses は Address です。識別子に使えないプロパティ名は引用符で囲みます。Go のフィールド名はその言語の習慣どおり略語を大文字にします。id は ID、avatar_url は AvatarURL になり、JSON タグには元の名前がそのまま残ります。
Go はポインタで、Python は NotRequired で任意の項目を示し、どちらもタグやキーに元の名前を保ちます。Zod は .optional() と .nullable() を付け、JSON Schema が落ちる場所で同じように落ちます。
わざとしないこと
- 例を一つ見て、あるフィールドが enum だとか、数値に範囲があると決めることはしません。どちらも推測で、新しい値を初めて送るペイロードですぐ壊れます。
- URL からスキーマを取りに行かず、外部の参照を解かず、二つの箱の中の文字より外を見ません。
- JSON5、JSON Lines、コメント付きの JSON は読みません。JSON を読み、そうでないときはそう言います。
- スキーマをサーバーに保存しません。入力した文字とタブ、設定はこのブラウザにだけ残ります。
- アカウントも、アップロードも、解析も、クッキーもなく、別のサーバーのフォントやスクリプトも使いません。
なぜ無料か
Pikkola は一つの仕事を負う小さな道具を作り、無料で置きます。アカウントも広告もありません。ブラウザで計算する静的なページは配る費用がほとんどかからないので、代金を取る理由もありません。
連絡
韓国語や日本語の文が硬い、対応すべきキーワードが抜けている、あるペイロードでページが壊れる。そんなときは hello@pikkola.com まで。問題を示すいちばん小さいペイロードと、期待した結果を添えてください。