Node & Edge Types

Overview

The schema layer turns declarative type definitions into:

1. Validated REST endpoints (via schema-to-api service)
2. Zod schemas used for request body validation
3. D1 metadata records that describe the graph’s shape

Node types

A node type defines the shape of a node in the graph:

// Example node type definition
const personType = {
  name: "Person",
  properties: {
    name: { type: "string", required: true },
    age: { type: "number", required: false },
    email: { type: "string", required: false },
  },
};

Register it via the API:

POST /graphs/{graphId}/schema/node-types
{
  "name": "Person",
  "properties": {
    "name": { "type": "string", "required": true },
    "age":  { "type": "number", "required": false }
  }
}

Once registered, the following endpoints are automatically available:

Method	Path	Action
POST	/graphs/{id}/nodes/Person	Create a Person node
GET	/graphs/{id}/nodes/Person/{nodeId}	Get a Person node
PATCH	/graphs/{id}/nodes/Person/{nodeId}	Update a Person node
DELETE	/graphs/{id}/nodes/Person/{nodeId}	Delete a Person node
GET	/graphs/{id}/nodes/Person	List Person nodes

Tip

You never write handler code for these endpoints. The schema-to-API service dynamically registers Hono routes when you define a type.

Edge types

An edge type defines a directed relationship between two node types:

POST /graphs/{graphId}/schema/edge-types
{
  "name": "KNOWS",
  "sourceType": "Person",
  "targetType": "Person",
  "properties": {
    "since": { "type": "string", "required": false }
  }
}

Auto-generated edge endpoints:

Method	Path
POST	/graphs/{id}/edges/KNOWS
GET	/graphs/{id}/edges/KNOWS/{edgeId}
DELETE	/graphs/{id}/edges/KNOWS/{edgeId}
GET	/graphs/{id}/edges/KNOWS

Supported property types

Type	JSON representation
string	"hello"
number	42, 3.14
boolean	true, false
string[]	["a", "b"]

Validation

All create and update requests are validated against the type’s Zod schema.
A request with an extra or missing required property returns:

{
  "error": "Validation failed",
  "details": [{ "path": ["name"], "message": "Required" }]
}