Custom Entity Types

Extensible

Extend ACE's ontology with your own entity types, validated by JSON Schema

What Are Custom Entity Types?

Go beyond the 10 built-in types

While ACE provides 10 built-in entity types (issues, decisions, memories, etc.), custom entity types let you define domain-specific entities with their own schema. Create types like "customer_feedback", "api_endpoint", "test_case", or anything your project needs.

Define Schema

JSON Schema validation for data integrity

Create Entities

CRUD operations with automatic validation

Graph Integration

Link to any other entity via relationships

Create a Custom Type

Define a type with JSON Schema validation

curl -X POST http://localhost:7777/api/v1/my-namespace/entity-types \
  -H "Authorization: Bearer $ACE_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "api_endpoint",
    "description": "REST API endpoint documentation",
    "schema": {
      "type": "object",
      "required": ["method", "path", "description"],
      "properties": {
        "method": {
          "type": "string",
          "enum": ["GET", "POST", "PUT", "PATCH", "DELETE"]
        },
        "path": { "type": "string" },
        "description": { "type": "string" },
        "request_body": { "type": "object" },
        "response_schema": { "type": "object" },
        "auth_required": { "type": "boolean", "default": true },
        "rate_limit": { "type": "integer" }
      }
    }
  }'

JSON Schema Validation

Data is validated against your schema on every write

Every entity created with a custom type is validated against the JSON Schema you defined. Invalid data is rejected with a clear error message.

Valid Entity

{
  "method": "GET",
  "path": "/api/v1/users",
  "description": "List users"
}

Created successfully

Invalid Entity

{
  "method": "INVALID",
  "path": "/api/v1/users"
}

Rejected: missing "description", invalid enum for "method"

CRUD Operations

# Create an entity of custom type
curl -X POST http://localhost:7777/api/v1/my-namespace/entities/api_endpoint \
  -H "Authorization: Bearer $ACE_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "POST",
    "path": "/api/v1/users",
    "description": "Create a new user",
    "auth_required": true,
    "rate_limit": 100
  }'

# List all entities of this type
curl "http://localhost:7777/api/v1/my-namespace/entities/api_endpoint" \
  -H "Authorization: Bearer $ACE_JWT_TOKEN"

# Get a specific entity
curl "http://localhost:7777/api/v1/my-namespace/entities/api_endpoint/1" \
  -H "Authorization: Bearer $ACE_JWT_TOKEN"

# Delete
curl -X DELETE "http://localhost:7777/api/v1/my-namespace/entities/api_endpoint/1" \
  -H "Authorization: Bearer $ACE_JWT_TOKEN"

# List all custom types in namespace
curl "http://localhost:7777/api/v1/my-namespace/entity-types" \
  -H "Authorization: Bearer $ACE_JWT_TOKEN"

Knowledge Graph Integration

Custom entities participate in the knowledge graph

Custom entities can be linked to any other entity (built-in or custom) using relationships. This means your custom types are fully integrated into the knowledge graph.

# Link custom entity to an architecture component
curl -X POST http://localhost:7777/api/v1/my-namespace/relationships \
  -H "Authorization: Bearer $ACE_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source_type": "api_endpoint",
    "source_id": 1,
    "target_type": "architecture",
    "target_id": 5,
    "relationship_type": "documented_in"
  }'

Use Cases

API Documentation

Track API endpoints with method, path, request/response schemas alongside your architecture decisions.

Test Cases

Define test case entities with steps, expected results, and link them to issues they validate.

Customer Feedback

Track user feedback with sentiment, source, and feature area, linked to relevant issues.

Domain-Specific Entities

Model anything unique to your domain - infrastructure components, compliance requirements, design tokens.