JSON Schema is already the schema format inside OpenAPI, AsyncAPI, and MCP. Using it means OBI can reference those specs directly without translation. Any other choice would have made interop harder, not easier.
The programming language analogy is about structural compatibility between contracts, not about the wire format the contract is written in.
Well he didn't choose JSON, he chose JSON Schema and since the documentation is trying to hide the existence of JSON Schema and the potential limitations of it when used in combination with e.g. gRPC, when the schema is 99% of the project it's hard to trust the project.
That said, if it feels buried, I'll look at surfacing it more clearly.
You're right about the gRPC fidelity issues though. int64 precision, oneof vs oneOf semantics, enum value mapping, and well-known types all need careful handling when binding to Proto. The tradeoff is that JSON Schema is already the schema format inside OpenAPI, AsyncAPI, and MCP, so OBI can reference their schemas directly without translation. Proto would have given better fidelity for gRPC but required schema translation for every other binding. Picking JSON Schema prioritizes cross-binding reach over depth in any one protocol.
The fidelity limitations deserve clearer documentation. Adding that to the list. Thanks for pushing on this.
OBI needs its schema format to be universally parseable, deterministic to compare, and rich enough to describe the portable subset of any binding format's type system. JSON Schema meets those requirements without tying the spec to any one ecosystem. Proto-level fidelity would center gRPC. A custom IDL would fragment tooling. JSON Schema is the neutral ground.
The limitations are real, especially with proto. For example, our own proto interface creator implementation maps 32-bit integers to JSON Schema `integer` and 64-bit integers to `string` to avoid JSON precision loss beyond 2^53, following Proto3's canonical JSON mapping. Proto enums are int-valued with names; JSON Schema enums are typically strings. Proto's oneof differs semantically from JSON Schema's oneOf. Maps with non-string keys can't be expressed directly.
These affect cross-service structural comparison, not execution. Executors handle source types natively on the wire, so int64 stays int64 when you actually make a call. Transforms bridge shape differences between operation schemas and binding sources at runtime. The comparison layer works at a coarser grain in v0.1 because that's what makes it deterministic and universally implementable. Future profile versions can tighten comparison precision as the ecosystem converges on the tradeoffs worth making.
The programming language analogy is about structural compatibility between contracts, not about the wire format the contract is written in.