C.W.K.
Stream
Lesson 04 of 05 · published

Protocol vs Library vs Convention

~20 min · protocol, library, convention, spec

Level 0Curious Reader
0 XP0/48 lessons0/14 achievements
0/100 XP to next level100 XP to go0% complete

Three nouns get flung around interchangeably in this space, and untangling them sharpens every later lesson.

A library is code you import into your process. openai-python is a library; so is anthropic. Libraries can be wrong; libraries can be replaced; libraries are a convenience layer over something else. Two libraries by different authors that target the same protocol can interoperate. Two libraries by different authors that target each other have made up a private dialect.

A convention is an agreement written in human prose. "Use camelCase for fields" is a convention. "Always return JSON, not plain text" is a convention. Conventions live in style guides, README files, and group chats. They are useful but unenforceable; they describe what people tend to do.

A protocol is a contract written precisely enough that two independently built programs — by people who never spoke — can interact correctly. Protocols define wire formats, message shapes, error codes, lifecycle, and what each side is allowed to assume. JSON-RPC 2.0, HTTP/1.1, and the Model Context Protocol are all protocols. They have specifications you can point at and say "your implementation violates section 4.2." That arguability is what makes them useful.

The trap is picking the wrong noun for the artifact you are about to build. If two teams will need to interoperate without coordinating, you need a protocol. If your library will only ever talk to itself, a convention is fine. The cost of a protocol is up-front rigor; the cost of skipping it is a future N×M problem we will study explicitly later in this quest.

Code

A library is convenience over a protocol·python
# This Python call:
client.responses.create(model="gpt-4.1", input=[...])
# ...is a library wrapping an HTTP+JSON protocol the OpenAI API speaks.
# A different language can talk to the same API by following the protocol,
# without ever touching this library.
A protocol is the *spec*, not the SDK·json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}
// JSON-RPC 2.0 is a *protocol*. Every MCP client and server, in every
// language, sends and receives messages of exactly this shape. The SDKs
// are libraries on top.

External links

Exercise

Open the MCP specification for the current revision and the OpenAPI specification side by side. Find one section in each that defines an error or status response. Notice the level of precision: types, codes, fields, MUST/SHOULD/MAY language. That precision is the line between a protocol and a convention.

Progress

Progress is local-only — sign in to sync across devices.
Spotted a bug or have feedback on this page?Report an Issue

Comments 0

🔔 Reply notifications (sign in)
Sign inPlease sign in to comment.

No comments yet — be the first.