You've probably heard it: "Fish don't exist."

Not in the sense that there are no aquatic creatures. But in the sense that "fish" is a fuzzy, human-invented category with no clean boundaries. Lungfish are fish? Are whales fish?

The answer: Fish exist because we decided they do. We drew a line around a collection of creatures and said "that's a fish." The category is useful, but it's not discovered in nature—it's constructed by us.

Your computer feels real. Files, folders, applications—you can see them on your desktop.

But they don't actually exist.

What actually exists: magnetic patterns on disk, electricity flowing through circuits.

What doesn't exist: the "file" abstraction.

When you double-click "my_project.txt", the OS executes complex instructions to read bytes and present them as a "file." The "file" is a definition. A useful fiction. If the OS changed its definition, the whole concept changes.

Now extend this to your software.

You believe your system has an OrderService, an order_created event, a payment-timeout error. But these don't actually exist.

What actually exists: functions executing, data transforming, bytes transmitting.

What doesn't exist: the categories you've imposed.

When you say "OrderService," you're drawing a circle around clustered functions. That's a definition, not a discovery. Tomorrow you could reorganize it completely.

If nothing fundamentally exists except the definitions we create, then the definitions themselves become the most important part of the system.

Most teams scatter definitions everywhere:

• Component: class in code, deployment in K8s, box in diagram, paragraph in wiki
• Error: exception in code, ticket in Jira, Slack thread, tribal knowledge
• Event: Kafka schema, consumer code, API docs, that one email

Four definitions of the same thing. All drifting. All inconsistent.

Stop pretending definitions are just "documentation." They're not describing the system—they are the system.

;; First, define what errors need
(s/def :error/code string?)
(s/def :error/severity #{:low :medium :high :critical})
(s/def :error/retry? boolean?)

;; Define the error TYPE and the required props 
(contract.type/def #{:semantic-namespace/error}
  [:error/code :error/severity :error/retry?])

;; Now define a specific error with expected props-types/values
(contract/def #{:semantic-namespace/error 
                :domain.payment/timeout}
  {:error/code "PAY_TIMEOUT"
   :error/severity :high
   :error/retry? true})

Notice what just happened: The identity #{:semantic-namespace/error :domain.payment/timeout} reads like English:

"An error, in the payment domain, specifically a timeout"

The compound identity is the description. You don't need separate documentation—you can read it.

Traditional identities are flat strings. No semantics. No relationships.

:payment-timeout-error  ;; What domain? What type? What properties?

Compound identities are sets of semantic aspects. Readable as plain English.

#{:semantic-namespace/error      ;; "an error"
  :domain.payment/timeout        ;; "payment domain, timeout type"  
  :severity/high}                ;; "high severity"

;; Reads: "A high-severity error in the payment domain, specifically a timeout"

Now the system can answer questions:

;; "What can go wrong with payments?"
(find-docs #{:domain.payment})

;; "What are all high-severity issues?"  
(find-docs #{:severity/high})

;; "Show me all errors"
(contract.type/instances #{:semantic-namespace/error})

The definitions are queryable. The identities are readable. The system is self-describing.

You might think: "Okay, but how many contract types do I really need?"

More than you think. And that's the point.

Most teams think: System exists → document it → hope docs stay current

The truth: Define everything explicitly → system implements the definitions → query the definitions to understand the system

The definitions come first. Everything else flows from them.

;; Single source of truth
@registry  
;; Every metric, error, event, permission, component

;; Fully queryable
(contract.type/instances #{:semantic-namespace/error})
;; All errors, across all domains

;; Human readable  
#{:semantic-namespace/metric :domain.order/latency}
;; "A metric for order domain latency" - reads like English

;; Generative
(generate-api-from-definitions)
(generate-docs-from-definitions)  
(generate-tests-from-definitions)

Your system isn't mysterious anymore. It's not hidden in code, configs, or people's heads.

It's explicit. It's unified. It's readable. It's just definitions.

All the way down.

• https://github.com/semantic-namespace/contract.example a mock medium project definitions to query about
• https://github.com/semantic-namespace/compound-identity the compound-identity registry and utilities to navigate/query that registry
• https://github.com/semantic-namespace/contract the semantic contract and type design and utils
• https://github.com/semantic-namespace/contract.di a PoC about defining dependency injection on systems via component contract definitions. Include utils to plan, query and start the system

https://news.ycombinator.com/item?id=45776620