Skip to content

YAML Definition Reference

Product definitions live in a GitHub repository with a .kiket/ directory. When a customer registers, Kiket syncs these definitions to their organization.

Directory Structure

your-product-repo/
└── .kiket/
    ├── project.yaml          # Manifest: custom fields, team roles
    ├── issue_types.yaml      # Issue type definitions
    ├── workflows/
    │   └── main.yaml         # Workflow state machine
    ├── intakes/
    │   └── request.yaml      # Public intake form
    ├── boards/
    │   └── default.yaml      # Board column layout
    └── agents/
        └── classifier.yaml   # AI agent definition

Workflow Definition

Workflows define states, transitions, SLA timers, checklists, approvals, and automated actions.

Example: GDPR DSAR Workflow

model_version: "1.0"
workflow:
  id: gdpr-dsar
  name: GDPR Data Subject Request
  version: 1.0.0
  description: Handles GDPR data subject access requests with 30-day SLA.

states:
  received:
    type: initial
    category: pending
    metadata:
      label: Received
      color: info
      icon: "📬"
      description: DSAR received, awaiting classification.
    on_enter:
      - action: ai_analyze
        agent: ai.gdpr.classifier
        store_result_in: custom_fields.request_type

  verification:
    type: active
    category: in_progress
    metadata:
      label: Identity Verification
      color: warning
      icon: "🔐"
      description: Verifying the identity of the data subject.
    checklist:
      id: verification_checklist
      title: Identity Verification
      required_mode: all
      items:
        - id: id_verified
          label: Government ID or proof of identity received
          check_type: manual
          required: true
        - id: address_matched
          label: Address matches records
          check_type: manual
          required: true
    sla:
      warning: 72h
      breach: 168h
      business_hours: true
      on_warning:
        - action: notify
          recipients:
            user: assignee
          message: "Identity verification for {{issue.title}} approaching deadline"

  processing:
    type: active
    category: in_progress
    metadata:
      label: Data Processing
      color: primary
      icon: "⚙️"
      description: Collecting and preparing the requested data.
    sla:
      warning: 480h
      breach: 600h
      business_hours: true
      on_breach:
        - action: notify
          recipients:
            roles: [manager, dpo]
          message: "CRITICAL: DSAR {{issue.title}} approaching 30-day GDPR deadline"
          level: critical

  review:
    type: active
    category: review
    metadata:
      label: DPO Review
      color: warning
      icon: "👁️"
      description: Data Protection Officer reviews the response.
    approval:
      required: 1
      approvers:
        - role: dpo
        - role: manager

  completed:
    type: terminal
    category: done
    metadata:
      label: Completed
      color: success
      icon: "✅"
      description: DSAR fulfilled and response sent to data subject.

  rejected:
    type: terminal
    category: done
    metadata:
      label: Rejected
      color: danger
      icon: "❌"
      description: Request rejected (invalid identity or out of scope).

transitions:
  - from: received
    to: verification
    trigger: manual
    label: Start Verification

  - from: received
    to: rejected
    trigger: manual
    label: Reject Request
    guard:
      require_comment: true

  - from: verification
    to: processing
    trigger: manual
    label: Identity Verified

  - from: verification
    to: rejected
    trigger: manual
    label: Verification Failed

  - from: processing
    to: review
    trigger: manual
    label: Submit for Review

  - from: review
    to: completed
    trigger: approval
    label: Approve & Complete

  - from: review
    to: processing
    trigger: manual
    label: Request Changes

Key Concepts

Concept Description
states Named states with type (initial/active/terminal), category, and metadata
transitions Allowed moves between states with trigger (manual/automatic/approval)
sla Timer with warning and breach durations, optional business_hours
checklist Required items that must be checked before leaving a state
approval Required approvals from specific roles before transition
on_enter Actions triggered when entering a state (AI analysis, notifications)
guard Conditions that must be met for a transition (require_comment, custom checks)

SLA Duration Format

72h = 72 hours, 30d = 30 days, 480h = 20 business days.

Intake Form Definition

Example: GDPR DSAR Submission Form

model_version: "1.0"
intake_form:
  id: gdpr-dsar-request
  name: Data Subject Access Request
  slug: gdpr-request
  description: Submit a request to access, correct, or delete your personal data.
  version: 1.0.0

  settings:
    public: true
    captcha_enabled: true
    embed_enabled: true
    rate_limit: 10
    requires_approval: true
    default_issue_type: dsar
    default_priority: high
    confirmation_message: |
      Your request has been received. We will verify your identity
      and respond within 30 days as required by GDPR.
      Reference: {{submission_id}}

  branding:
    title: "Data Subject Request"
    subtitle: "Exercise your rights under GDPR Article 15-21"

  issue:
    type: dsar
    workflow: gdpr-dsar
    initial_state: received
    title_template: "[DSAR] {{request_type}} - {{requester_name}}"

  fields:
    - key: requester_name
      type: string
      label: Full Name
      required: true
      placeholder: "Your full legal name"
      maps_to: custom_fields.requester_name

    - key: requester_email
      type: email
      label: Email Address
      required: true
      placeholder: "your@email.com"
      maps_to: custom_fields.requester_email

    - key: request_type
      type: enum
      label: Request Type
      required: true
      options:
        - value: access
          label: "Access my data (Article 15)"
        - value: rectification
          label: "Correct my data (Article 16)"
        - value: erasure
          label: "Delete my data (Article 17)"
        - value: portability
          label: "Export my data (Article 20)"
        - value: objection
          label: "Object to processing (Article 21)"
      maps_to: custom_fields.request_type

    - key: description
      type: text
      label: Details
      required: false
      placeholder: "Describe your request in detail..."
      maps_to: description

    - key: id_document
      type: file
      label: Identity Verification Document
      required: false
      helper_text: "Upload a government-issued ID to speed up verification"
      options:
        allowed_types:
          - application/pdf
          - image/*
        max_size_mb: 10
        max_files: 2

    - key: consent_confirmation
      type: boolean
      label: "I confirm this request is made in good faith under GDPR"
      required: true

Field Types

Type Description
string Single-line text
text Multi-line text
email Email with validation
phone Phone number
url URL with validation
number Numeric value
boolean Checkbox
enum Single-select dropdown
multi_enum Multi-select
date / datetime / time Date/time pickers
file File upload
rating / scale Rating widget
heading / paragraph / divider Layout elements (non-input)

Field Mapping (maps_to)

Value Maps To
title Issue title
description Issue description
priority Issue priority
assignee Issue assignee
due_date Issue due date
label Issue labels
custom_fields.{key} Custom field value

Issue Types

issue_types:
  - key: dsar
    label: Data Subject Request
    icon: "shield-check"
    color: "primary"
    description: GDPR data subject access, rectification, or erasure request

  - key: breach
    label: Data Breach
    icon: "exclamation-triangle"
    color: "danger"
    description: Personal data breach notification (72-hour GDPR deadline)

  - key: consent
    label: Consent Record
    icon: "check-circle"
    color: "success"
    description: Data processing consent management record

  - key: audit
    label: Compliance Audit
    icon: "clipboard-check"
    color: "info"
    description: Internal GDPR compliance audit task

Custom Fields (in project.yaml)

model_version: "1.0"
project:
  key: gdpr
  name: GDPR Compliance
  version: 1.0.0
  description: GDPR data subject request management

  custom_fields:
    - key: requester_name
      label: Requester Name
      type: string
      required: true

    - key: requester_email
      label: Requester Email
      type: email
      required: true

    - key: request_type
      label: Request Type
      type: enum
      required: true
      options:
        - value: access
          label: Access (Art. 15)
        - value: rectification
          label: Rectification (Art. 16)
        - value: erasure
          label: Erasure (Art. 17)
        - value: portability
          label: Portability (Art. 20)
        - value: objection
          label: Objection (Art. 21)

    - key: deadline
      label: Response Deadline
      type: date
      required: false
      helper_text: "Auto-calculated: 30 days from receipt"

    - key: data_categories
      label: Data Categories
      type: text
      required: false
      helper_text: "Which categories of personal data are involved"

  team:
    roles:
      - key: dpo
        label: Data Protection Officer
      - key: processor
        label: Data Processor
      - key: manager
        label: Manager

Board Definition

model_version: "1.0"
board:
  id: gdpr-board
  name: DSAR Pipeline
  version: 1.0.0

columns:
  - state: received
    label: Received
    wip_limit: 20

  - state: verification
    label: Verification
    wip_limit: 5

  - state: processing
    label: Processing
    wip_limit: 10

  - state: review
    label: DPO Review
    wip_limit: 3

  - state: completed
    label: Completed
    collapsed: true

  - state: rejected
    label: Rejected
    collapsed: true

card_template:
  fields:
    primary:
      - custom_fields.requester_name
      - custom_fields.request_type
    secondary:
      - custom_fields.requester_email
  badges:
    - field: priority
      colors:
        critical: danger
        high: warning

JSON Schemas

Machine-readable JSON schemas for all YAML types are available at:

These schemas are used by the visual editors and AI assistants within Kiket.