Koesion initiative · Open specification
Microservice.MD
The open specification for designing, documenting, and validating microservices. A structured, AI-ready design document for microservice systems.
Microservice.MD is created, owned, and maintained by Koesion — born from the patterns we apply in consulting engagements, and open for every team to use.
What MICROSERVICE.md is
MICROSERVICE.md is an open specification for microservice design documentation. Every service in a system carries one structured document that captures what the service is, where its boundaries are, and how it behaves — in a format both humans and AI tools can consume.
It builds on microservice canvas concepts and is evolving into a broader design and conception toolset for microservice systems: from first design sketch through validation, governance, and change.
Because the format is structured and consistent, it becomes a foundation for better design conversations, clearer communication between teams, practical architecture governance, and effective AI-assisted development.
What a MICROSERVICE.md document captures
One document per service, covering the decisions that matter:
- Service purpose and responsibilities
- Boundaries and bounded context
- Ownership and team accountability
- APIs — REST, gRPC, GraphQL
- Events published and consumed
- Dependencies, upstream and downstream
- Data ownership and storage
- Observability: metrics, logs, traces, SLOs
- Security posture and access control
- Deployment strategy and runtime environment
- AI-ready context for assisted engineering
A public GitHub repository — github.com/koesion/microservice-md — will soon host the specification and its tooling.
Want the design knowledge behind the specification? Microservice.Guru is Koesion’s learning platform for microservice architecture.
Discover Microservice.Guru