Service Dependencies

Use dependencies to declare the relationships between this service and other services or datastores. Each entry becomes an edge in the service graph, owned by the current service.

Dependencies are metadata only. Nothing is fetched from or introspected on the target service, and a target that has not been onboarded yet is kept as an unresolved edge rather than failing the sync.

Config shape

dependencies:
  - name: payments-charges
    service: Payments Provider
    direction: downstream
    type: http
    criticality: hard
    description: Charges customer cards through the payments provider.
    apiGroupName: payments-api
    apiEndpointNames:
      - createCharge
      - refundCharge

  - name: orders-store
    service: Orders DB
    direction: downstream
    type: database
    criticality: soft
    databaseName: orders

  - name: mobile-order-feed
    service: Mobile App
    direction: upstream
    criticality: soft
    description: The mobile app reads the order feed from this service.

A service block is required. A config without a service cannot sync dependencies.

Direction

direction is required on every dependency and records where the current service sits relative to the target. It is stored exactly as declared and is never inferred, normalized, or swapped.

Value	Meaning	Read it as
downstream	The current service is downstream of the target.	"I call them."
upstream	The current service is upstream of the target.	"They call me."

Most declared dependencies are downstream. Use upstream to record an inbound consumer this service knows about.

A mutual relationship — A calls B and B calls A — is two separate entries with two distinct name values and opposite directions. They can be split across the two services' configs, or declared entirely from one side.

Field reference

Field	Type	Required	Description
name	string	yes	Stable upsert key for the edge. Must be unique across all dependencies.
service	string	yes	Target service name. Must not equal service.name.
direction	string	yes	upstream or downstream.
criticality	string	yes	hard or soft.
type	string	no	http, graphql, grpc, or database. Omit when unknown.
description	string	no	Short summary of what the dependency is used for.
apiGroupName	string	no	API group on the target service.
apiEndpointNames	list	no	Endpoints on the target service. Each non-empty and unique within the dependency.
databaseName	string	no	Datastore name, typically paired with type: database.

Use hard when the current service cannot function correctly while the dependency is down, and soft when it degrades gracefully.

apiGroupName, apiEndpointNames, and databaseName describe the target service's artifacts, not this service's own apis and databases. They are free-form references and are not existence-checked against local files.

Validation errors

dependencies[0].direction is required
dependencies[0].direction must be one of: upstream, downstream
dependencies[1].criticality must be one of: hard, soft
dependencies[2].type must be one of: http, graphql, grpc, database
dependencies[3].name must be unique
dependencies[4].service must not reference the current service
service is required to sync dependencies; configs without a service may only sync maps and frames

The full words are the only accepted direction values — up and down are rejected.

Related

• APIs
• Databases
• Troubleshooting