Source of Truth

Source of Truth #

The different specification formats can be used as a source or a sink or both of them, but never use sources as source of the specs.

graph LR µSpec --> Spec Spec --> Proto Proto --> µSpec Spec --> µSpec

Some transitions will loose information

  • Spec --> *

some transitions are destructive

  • Proto -> µSpec
  • Spec -> Proto

and some are updating the sinks

  • µSpec -> Spec
  • Spec -> µSpec

You should choose one source of truth and stick to it when possible. It is always possible to change.

Sources AND Sink #

  • Spec
  • µSpec
  • Proto

Sinks only #

  • Es6Module (by design)
  • Docs
  • U33E
  • Gateway
  • OpenApi

Spec as source #

graph TD Spec --> Proto Spec --> µSpec Spec --> Es6Module Spec --> Docs Spec --> U33E Spec --> ... Proto --> Gateway Proto --> OpenApi

Pros

  • only one kind of spec to work with
  • run your flow at any time with same results (idempotency)
  • guaranteed interoperability from backend to client

Cons

  • design phase is harder
  • µSpec only for discussions and not for “design”
Recommended when you only have to maintain an existing project.

µSpec as source #

graph TD Spec --> Proto µSpec -->Spec Spec --> Es6Module Spec --> Docs Spec --> U33E Spec --> ... Proto --> Gateway Proto --> OpenApi

Pros

  • fastest variant to design new stuff
  • simplest notation
  • covers >90% of the cases
  • idempotent
  • guaranteed interoperability from backend to client

Cons

  • working in specs for some edge cases required

Recommended when you have a fresh project or a lot of changes.

Easiest method when you know protobuf/grpc.

Proto as source #

graph TD Proto --> µSpec µSpec -->Spec Spec --> Es6Module Spec --> Docs Spec --> U33E Spec --> ... Proto --> Gateway Proto --> OpenApi

Pros

  • good solution when everything is already defined in proto
  • covers >80% of the cases
  • idempotent

Cons

  • destructive step Proto –> µSpec
  • working in specs for some cases required
  • writing REST service definitions by “hand”
  • interoperability from backend to client is not guaranteed because some steps are not under control of spectools anymore.
Recommended when you have a huge portfolio of protos and want to bring them to the web (without any changes).

Advanced Setup #

This is a extended µSpec as source variant.

graph TD SomeProto --> µSpec µSpec --> Spec Spec --> Proto Spec --> Es6Module Spec --> Docs Spec --> U33E Spec --> ... Proto --> Gateway Proto --> OpenApi

Pros

  • implement external changes very fast
  • designing new stuff still fast
  • guaranteed interoperability from backend to client

Cons

  • hard setup for the SomeProto part
  • bigger skill set needed
  • partially destructive step
Recommended when you have to import protos to your system. Use “µSpec as source” first and switch to this variant when you have to.

Multiple Sources of Truth #

The you know what you do mode.

When you have to migrate a project from different spec formats, you have to use this setup. This is not recomended and should still be an exception and not the default.

graph TD SomeProto --> µSpec OtherFormats --> Spec µSpec --> Spec Spec --> Proto Spec --> µSpec Spec --> Es6Module Spec --> Docs Spec --> U33E Spec --> ... Proto --> Gateway Proto --> OpenApi Proto --> µSpec

Pros

  • Do what ever you ever want.

Cons

  • Dangerous
  • More then one flow required
  • Not idempotent
  • very hard setup

NOT Recommended!

Do this only when you have to do, try to switch to another setup as fast as you can.