Most software systems don’t fail because of bugs.
They fail because of invisible dependency.
Contracts are consumed implicitly.
Compatibility is assumed globally.
Versioning becomes a coordination tax.
And evolution slowly turns into fear.
Raygon is an attempt to fix that not with another framework or tool, but by changing the model we use to think about contracts.
The Core Problem
In most systems today, a contract answers the question:
“What does this thing contain?”
Schemas, APIs, DTOs, and IDLs all focus on structure.
But structure alone hides the most important information:
- Who depends on what?
- Why does that dependency exist?
- What actually breaks when something changes?
Because dependency is implicit, change becomes risky.
Because compatibility is treated as global, evolution requires coordination.
Because history is erased, migrations become guesswork.
Raygon starts from a different question.
A Different Question
Raygon asks:
“Who depends on what, and why?”
That single shift changes everything.
In Raygon:
- Contracts are semantic spaces, not payload definitions.
- Fields represent meaning, not structure.
- Consumption is never implicit.
- Compatibility is local, not global.
- Evolution is recorded, not erased.
Projection-Based Consumption
The central idea in Raygon is simple and strict:
Contracts are never consumed directly.
Every consumer must declare a projection an explicit subset of fields it depends on.
This means:
- Adding a field never increases coupling.
- Removing a field only affects consumers that declared it.
- Different consumers can safely depend on different parts of the same contract.
- There is no hidden dependency.
Coupling becomes observable instead of accidental.
Evolution Without Fear
Raygon treats evolution as a first-class concern.
- Fields have lineage.
- Renames preserve identity via aliases.
- Deprecation signals intent without forcing migration.
- Versions record that change happened — not whether it is “breaking”.
Breaking changes are no longer global events.
They are local, explainable, and attributable.
Legacy consumers can coexist with modern ones without coordination or panic.
What Raygon Is (and Is Not)
Raygon is:
- a semantic contract model
- projection-based by design
- language-agnostic
- tooling-independent
- model-first
Raygon is not:
- a programming language
- a runtime framework
- a schema format
- a code generator
- a validation system
Raygon defines truth, not execution.
A Minimal Demonstration
To prove that Raygon is not just theory, a minimal demonstration was built:
- one .raygon contract
- multiple consumers with explicit projections
- a legacy consumer using a deprecated field
- a tiny analyzer issuing warnings, not failures
No frameworks.
No magic.
Just interpretation of the model.
The result is exactly what the model predicts:
safe coexistence, explicit dependency, and local compatibility.
Why This Matters
Raygon is not about making contracts easier to write.
It is about making dependency impossible to hide.
When systems can explain:
- who depends on what,
- why that dependency exists,
- and how evolution impacts it,
they can grow without losing coherence.
That is the real goal.
Closing Thought
Raygon is intentionally constrained.
It trades convenience for clarity.
Implicit behavior for explicit intent.
Short-term ease for long-term coherence.
If your system is large, long-lived, or evolving under pressure,
those trade-offs start to matter.
Raygon is one attempt to make them explicit.
Framework in TypeScript: https://github.com/MatheusPereiraSilva/raygon
Contract Docs and simple example: https://github.com/MatheusPereiraSilva/raygon-contract