# Domain Graph Protocol (DGP)

> Agent-first protocol for exposing business domains as unified, queryable graphs.

DGP models business entities and relationships directly, so agents can query and mutate domain concepts (for example `Customer`, `Order`, `Payment`) instead of orchestrating many tool-specific APIs.

## Current Version

- Core spec: `0.9.0`
- Core status: Production-Ready
- Last updated: January 2026
- Reference implementation tests: 1048 passing

## Core Spec

- [Specification (Markdown)](/spec.md)
- [Specification (HTML)](/spec/)

## Core Request/Response Shapes

### Query

```json
{
  "query": {
    "entity": "Customer",
    "where": {"lifetime_value": {"gte": 1000}},
    "include": {
      "orders": {"limit": 5}
    },
    "options": {
      "consistency": "bounded_staleness",
      "max_staleness_ms": 30000
    },
    "limit": 10
  }
}
```

### Mutation

```json
{
  "mutation": {
    "operation": "confirm_order",
    "entity": "Order",
    "id": "order_123",
    "input": {"payment_method_id": "pm_xyz"},
    "options": {"idempotency_key": "idem_abc123"}
  }
}
```

### Query Response

```json
{
  "data": [],
  "metadata": {
    "query_id": "q_abc123",
    "execution": {"duration_ms": 145, "sources_queried": ["postgres", "stripe"]},
    "cost": {"total_tokens": 67},
    "freshness": {"staleness_ms": 2300},
    "provenance": {"sources": [], "transformations": []}
  },
  "pagination": {"total": 1234, "has_more": true}
}
```

## Companion Specs

Production-ready companion specs:
- [Consistency Model](https://github.com/pyramidal-io/DGP.dev/blob/main/docs/dgp-consistency-model-spec.md)
- [Schema Evolution](https://github.com/pyramidal-io/DGP.dev/blob/main/docs/dgp-schema-evolution-spec.md)
- [External Services](https://github.com/pyramidal-io/DGP.dev/blob/main/docs/dgp-external-services-spec.md)

Draft companion specs:
- [Query Safety & Resource Limits](https://github.com/pyramidal-io/DGP.dev/blob/main/docs/dgp-query-safety-resource-limits-spec.md)
- [Data Privacy & Access Control](https://github.com/pyramidal-io/DGP.dev/blob/main/docs/dgp-data-privacy-access-control-spec.md)
- [Distributed Transactions (Saga Pattern)](https://github.com/pyramidal-io/DGP.dev/blob/main/docs/dgp-distributed-transactions-saga-pattern-spec.md)
- [Conflict Resolution Across Sources](https://github.com/pyramidal-io/DGP.dev/blob/main/docs/dgp-conflict-resolution-across-sources-spec.md)
- [Batch Queries & Error Taxonomy](https://github.com/pyramidal-io/DGP.dev/blob/main/docs/dgp-batch-queries-error-taxonomy-spec.md)
- [CSN and Agent Context Management](https://github.com/pyramidal-io/DGP.dev/blob/main/docs/dgp-csn-agent-context-management-spec.md)
- [Proactive Intelligence Layer](https://github.com/pyramidal-io/DGP.dev/blob/main/docs/dgp-proactive-intelligence-layer-spec.md)
- [NATS Transport](https://github.com/pyramidal-io/DGP.dev/blob/main/docs/dgp-nats-transport-spec.md)

## Schemas and Examples

- [Query Schema](/schema/query.schema.json)
- [Response Schema](/schema/response.schema.json)
- [Components Schema](/schema/components.schema.json)
- [Example Queries](/examples/queries.json)
- [Example Responses](/examples/responses.json)
- [E-Commerce CSN](/examples/ecommerce.csn)

## Transport

- HTTP endpoints: `/schema`, `/query`, `/mutation`, `/health`
- Optional NATS transport for request/reply and subscriptions
- NATS spec: [/nats/](/nats/)

## Notes for Agents

- Prefer semantic traversal via `include` over multiple endpoint-style calls.
- Use consistency options (`strong`, `eventual`, `bounded_staleness`) explicitly when freshness matters.
- Use mutation `idempotency_key` for safe retries.
- Check `metadata.provenance` and `metadata.cost` to optimize follow-up queries.