Entity Definitions

Entity Definitions allow you to define custom entity types in your Devgraph ontology. They specify the structure, validation rules, and metadata for entities you create.

What is an Entity Definition?

An Entity Definition is a schema that describes:

• The structure of an entity type
• Required and optional fields
• Validation rules for field values
• Metadata like descriptions and display names

Think of it as a template or blueprint for creating entities of a specific type.

Structure

Entity Definitions follow this structure:

apiVersion: meta.devgraph.ai/v1
kind: EntityDefinition
metadata:
  name: my-service
spec:
  group: mycompany.com           # Your domain
  name: v1                        # API version
  kind: Service                   # Entity type name
  listKind: ServiceList          # Plural form for lists
  singular: service              # Singular form
  plural: services               # Plural form
  description: "Custom service entity"
  served: true                   # Whether to serve this definition
  storage: true                  # Whether to store entities of this type
  spec:                          # Schema definition
    type: object
    properties:
      url:
        type: string
        description: "Service URL"
      port:
        type: integer
        description: "Service port"
      protocol:
        type: string
        enum: [http, https, grpc]
    required:
      - url
      - port

Core Fields

Group and Version

The group and name (version) together form the apiVersion:

group: mycompany.com
name: v1
# Results in apiVersion: mycompany.com/v1

Best Practices:

• Use your organization's domain for the group
• Start with v1 and increment for breaking changes
• Use reverse domain notation: com.mycompany, io.myproject

Kind

The kind identifies the entity type:

kind: Service
# Creates entity type: mycompany.com/v1/Service

Best Practices:

• Use PascalCase for kind names
• Choose descriptive, singular nouns
• Examples: Service, Database, Deployment

List Kind

The listKind is used when returning multiple entities:

kind: Service
listKind: ServiceList

Convention: Add "List" suffix to the kind name.

Singular and Plural

Used in CLI and UI display:

singular: service
plural: services

Schema Definition

The spec.spec field contains a JSON Schema defining entity structure:

Basic Schema

spec:
  spec:
    type: object
    properties:
      name:
        type: string
        description: "Service name"
      enabled:
        type: boolean
        description: "Whether service is enabled"
    required:
      - name

Data Types

Supported JSON Schema types:

properties:
  # String
  name:
    type: string
    minLength: 1
    maxLength: 255

  # Integer
  port:
    type: integer
    minimum: 1
    maximum: 65535

  # Number (float)
  version:
    type: number

  # Boolean
  enabled:
    type: boolean

  # Array
  tags:
    type: array
    items:
      type: string

  # Object
  config:
    type: object
    properties:
      timeout:
        type: integer

  # Enum
  protocol:
    type: string
    enum: [http, https, grpc]

Nested Objects

Define complex nested structures:

spec:
  spec:
    type: object
    properties:
      deployment:
        type: object
        properties:
          replicas:
            type: integer
          resources:
            type: object
            properties:
              cpu:
                type: string
              memory:
                type: string

Arrays

Define list fields:

properties:
  # Array of strings
  tags:
    type: array
    items:
      type: string

  # Array of objects
  endpoints:
    type: array
    items:
      type: object
      properties:
        url:
          type: string
        port:
          type: integer

Creating Entity Definitions

Via API

curl -X POST http://localhost:8000/api/v1/entity-definitions \
  -H "Content-Type: application/json" \
  -H "Devgraph-Environment: {environment-id}" \
  -d '{
    "apiVersion": "meta.devgraph.ai/v1",
    "kind": "EntityDefinition",
    "metadata": {
      "name": "myservice"
    },
    "spec": {
      "group": "mycompany.com",
      "name": "v1",
      "kind": "Service",
      "listKind": "ServiceList",
      "singular": "service",
      "plural": "services",
      "description": "Custom service definition",
      "spec": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string"
          },
          "port": {
            "type": "integer"
          }
        },
        "required": ["url"]
      }
    }
  }'

Via YAML File

Create a file service-definition.yaml:

apiVersion: meta.devgraph.ai/v1
kind: EntityDefinition
metadata:
  name: myservice
spec:
  group: mycompany.com
  name: v1
  kind: Service
  listKind: ServiceList
  singular: service
  plural: services
  description: Custom service definition
  spec:
    type: object
    properties:
      url:
        type: string
        description: Service URL
      port:
        type: integer
        description: Service port
      protocol:
        type: string
        enum: [http, https, grpc]
    required:
      - url
      - port

Apply it:

# Using curl with YAML
curl -X POST http://localhost:8000/api/v1/entity-definitions \
  -H "Content-Type: application/yaml" \
  -H "Devgraph-Environment: {environment-id}" \
  --data-binary @service-definition.yaml

Using Entity Definitions

Once defined, create entities of your custom type:

apiVersion: mycompany.com/v1
kind: Service
metadata:
  name: api-gateway
  namespace: default
spec:
  url: https://api.example.com
  port: 443
  protocol: https

Create via API:

curl -X POST http://localhost:8000/api/v1/entities \
  -H "Content-Type: application/json" \
  -H "Devgraph-Environment: {environment-id}" \
  -d '{
    "apiVersion": "mycompany.com/v1",
    "kind": "Service",
    "metadata": {
      "name": "api-gateway",
      "namespace": "default"
    },
    "spec": {
      "url": "https://api.example.com",
      "port": 443,
      "protocol": "https"
    }
  }'

Validation

Devgraph validates entities against their definitions:

Valid Entity

apiVersion: mycompany.com/v1
kind: Service
metadata:
  name: valid-service
spec:
  url: https://example.com  # Required field present
  port: 443                 # Valid integer
  protocol: https           # Valid enum value

Invalid Entity

apiVersion: mycompany.com/v1
kind: Service
metadata:
  name: invalid-service
spec:
  port: 443                 # Missing required 'url'
  protocol: ftp             # Invalid enum value

Error response:

{
  "error": "Validation failed",
  "details": [
    "Missing required field: url",
    "Invalid value for protocol: ftp (must be one of: http, https, grpc)"
  ]
}

Complete Examples

Microservice Definition

apiVersion: meta.devgraph.ai/v1
kind: EntityDefinition
metadata:
  name: microservice
spec:
  group: platform.mycompany.com
  name: v1
  kind: Microservice
  listKind: MicroserviceList
  singular: microservice
  plural: microservices
  description: Internal microservice
  spec:
    type: object
    properties:
      repository:
        type: string
        description: GitHub repository URL
      language:
        type: string
        enum: [python, go, typescript, java]
      framework:
        type: string
        description: Web framework used
      endpoints:
        type: array
        items:
          type: object
          properties:
            path:
              type: string
            method:
              type: string
              enum: [GET, POST, PUT, DELETE, PATCH]
      dependencies:
        type: array
        items:
          type: string
        description: List of service dependencies
      database:
        type: object
        properties:
          type:
            type: string
            enum: [postgresql, mysql, mongodb, redis]
          host:
            type: string
          port:
            type: integer
    required:
      - repository
      - language

Database Definition

apiVersion: meta.devgraph.ai/v1
kind: EntityDefinition
metadata:
  name: database
spec:
  group: infrastructure.mycompany.com
  name: v1
  kind: Database
  listKind: DatabaseList
  singular: database
  plural: databases
  description: Database instance
  spec:
    type: object
    properties:
      engine:
        type: string
        enum: [postgresql, mysql, mongodb, redis]
        description: Database engine
      version:
        type: string
        description: Database version
      host:
        type: string
        description: Database host
      port:
        type: integer
        minimum: 1
        maximum: 65535
      ssl:
        type: boolean
        description: Whether SSL is enabled
      replication:
        type: object
        properties:
          enabled:
            type: boolean
          replicas:
            type: integer
            minimum: 0
      backups:
        type: object
        properties:
          enabled:
            type: boolean
          frequency:
            type: string
            enum: [hourly, daily, weekly]
          retention:
            type: integer
            description: Retention period in days
    required:
      - engine
      - host
      - port

Best Practices

Naming Conventions

• Groups: Use reverse domain notation

  • Good: platform.mycompany.com, io.myproject
  • Bad: mycompany, platform

• Kinds: Use PascalCase singular nouns

  • Good: Service, Database, APIEndpoint
  • Bad: service, Services, api-endpoint

• Metadata Names: Use lowercase kebab-case

  • Good: my-service, api-gateway
  • Bad: MyService, api_gateway

Schema Design

1. Start Simple: Begin with required fields, add optional ones later
2. Use Descriptions: Document every field
3. Validate Strictly: Use enums, min/max, patterns
4. Version Carefully: Create new versions for breaking changes

Organization

Group related entity definitions:

platform.mycompany.com/v1:
  - Microservice
  - Library
  - Team

infrastructure.mycompany.com/v1:
  - Database
  - Queue
  - Cache

deployment.mycompany.com/v1:
  - Deployment
  - Environment
  - Release

Querying Entity Definitions

List all definitions:

curl http://localhost:8000/api/v1/entity-definitions \
  -H "Devgraph-Environment: {environment-id}"

Get a specific definition:

curl http://localhost:8000/api/v1/entity-definitions/myservice \
  -H "Devgraph-Environment: {environment-id}"

Next Steps

• Learn about Entities
• Explore Built-in Entity Types