{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://upjack.dev/schemas/v1/upjack-entity.schema.json",
  "title": "Upjack Entity",
  "description": "Base entity schema for NimbleBrain Upjack apps. App-specific schemas extend this via allOf composition.",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Type-prefixed ULID: 2-4 char prefix, underscore, 26-char Crockford base32 ULID",
      "pattern": "^[a-z]{2,4}_[0-9A-HJKMNP-TV-Z]{26}$"
    },
    "type": {
      "type": "string",
      "description": "Entity type name matching the upjack manifest entity definition",
      "pattern": "^[a-z][a-z0-9_]*$"
    },
    "version": {
      "type": "integer",
      "description": "Schema version (not record version). Enables lazy migration when app schemas evolve.",
      "minimum": 1
    },
    "created_at": {
      "type": "string",
      "description": "ISO 8601 creation timestamp",
      "format": "date-time"
    },
    "updated_at": {
      "type": "string",
      "description": "ISO 8601 last update timestamp",
      "format": "date-time"
    },
    "created_by": {
      "type": "string",
      "description": "Who created this entity",
      "enum": ["user", "agent", "system", "ingestion", "schedule"],
      "default": "agent"
    },
    "status": {
      "type": "string",
      "description": "Entity lifecycle status",
      "enum": ["active", "archived", "deleted"],
      "default": "active"
    },
    "tags": {
      "type": "array",
      "description": "Freeform tags for categorization and filtering",
      "items": {
        "type": "string",
        "pattern": "^[a-z0-9][a-z0-9-]*$",
        "maxLength": 64
      },
      "maxItems": 20,
      "uniqueItems": true,
      "default": []
    },
    "source": {
      "type": "object",
      "description": "Provenance information for imported or enriched entities",
      "properties": {
        "origin": {
          "type": "string",
          "description": "Source system or process name"
        },
        "ref": {
          "type": "string",
          "description": "External identifier in the source system"
        },
        "url": {
          "type": "string",
          "description": "URL to the source record",
          "format": "uri"
        }
      }
    },
    "relationships": {
      "type": "array",
      "description": "Links to other entities",
      "items": {
        "type": "object",
        "properties": {
          "rel": {
            "type": "string",
            "description": "Relationship type (e.g., 'works_at', 'primary_contact', 'related_to')"
          },
          "target": {
            "type": "string",
            "description": "Target entity ID (prefixed ULID)",
            "pattern": "^[a-z]{2,4}_[0-9A-HJKMNP-TV-Z]{26}$"
          },
          "label": {
            "type": "string",
            "description": "Human-readable description of the relationship"
          }
        },
        "required": ["rel", "target"]
      },
      "default": []
    }
  },
  "required": ["id", "type", "version", "created_at", "updated_at"],
  "additionalProperties": true
}