Edit on Github
The open standard for reusable microservices

The Twelve-Factor Microservice

❤️Inspired by The Twelve-Factor App
Beta This guide is under active development. We welcome your input and contributions on GitHub
  1. Domain Specific

    Specialized to the domain and encapsulating the full API of the domain.

  2. Containerized

    For portability and re-usability (ex. Docker, rkt or FaaS).

  3. Language-Agnostic

    Written in any programming language.

  4. Vendor-Neutral

    Not be tied to one platform.
    Platforms designed to interface with OMG Compliant services can interact with all services.

  5. Any Interface

    Free to choose any communication interface.

  6. Documentation

    Automatically generated and actionable through the microservice.yml.

  7. Declarative

    List all actions the service can perform, including the arguments and the output.

  8. Stateless

    Services must be stateless.

  9. CloudEvents

    Use a common specification for describing event data.

  10. Meta

    Include health, metrics, resources, and logs.

  11. Isolated

    Not depend on any other service (aka container coupling).

  12. Config

    All service configuration must be documented.

Why OMG?

Microservices, by design, are intended to be highly reusable, operational-specific and language-agnostic. This guide defines the standard that defines how to interface with microservices to provide a blueprint for consistency and reusability. By following this documentation, developers will be able to create a platform that is well-documented and portable while not compromising flexibility.

The old way of communicating software architecture and design through whiteboards and diagrams is immediately out of date and often becomes difficult to read and understand. By mapping your microservice architecture using pre-defined yaml by OMG, developers are given a way to describe architecture and operational requirements as human-readable structured data.

Having these models in plain text files gives developers a framework to effectively communicate architecture, service to service communication, and operational complexities to many different audiences.


Focus is stressed on services being highly reusable between applications and platforms.


Define how to interface with the service, lifecycle management, scaling, among other requirements.


Services inherit documentation through a well defined configuration of commands, arguments and output.