Task Schema

The Task Schema defines the structure for task documents in JACS. Tasks represent work items with defined states, assigned agents, and completion criteria.

Schema Location

https://hai.ai/schemas/task/v1/task.schema.json

Overview

Task documents manage:

• Workflow States: From creation through completion
• Agent Assignment: Customer and assigned agent tracking
• Actions: Desired outcomes and completion criteria
• Agreements: Start and end agreements between parties
• Relationships: Sub-tasks, copies, and merges

Schema Structure

The task schema extends the Header Schema:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://hai.ai/schemas/task/v1/task-schema.json",
  "title": "Task",
  "description": "General schema for stateful resources.",
  "allOf": [
    { "$ref": "https://hai.ai/schemas/header/v1/header.schema.json" },
    { "type": "object", "properties": { ... } }
  ]
}

Task States

Tasks progress through defined workflow states:

{
  "jacsTaskState": "started"
}

State Transitions

creating → rfp → proposal → negotiation → started → review → completed
                    ↑_______________|
                (may cycle back for renegotiation)

Task Properties

Core Fields (from Header)

Tasks inherit all document header fields plus task-specific fields.

Task-Specific Fields

Relationship Fields

Actions

Actions define what needs to be accomplished:

{
  "jacsTaskActionsDesired": [
    {
      "name": "Create API Endpoint",
      "description": "Build REST endpoint for user registration",
      "cost": {
        "value": 500,
        "unit": "USD"
      },
      "duration": {
        "value": 8,
        "unit": "hours"
      },
      "completionAgreementRequired": true,
      "tools": [...]
    }
  ]
}

Action Schema Fields

Unit Schema

Costs and durations use the unit schema:

{
  "cost": {
    "value": 100,
    "unit": "USD"
  },
  "duration": {
    "value": 2,
    "unit": "days"
  }
}

Agreements

Tasks can include start and end agreements:

Start Agreement

Signed when parties agree to begin work:

{
  "jacsStartAgreement": {
    "agentIDs": ["customer-uuid", "agent-uuid"],
    "question": "Do you agree to begin this work?",
    "context": "Project XYZ - Phase 1",
    "signatures": [...]
  }
}

End Agreement

Signed when parties agree work is complete:

{
  "jacsEndAgreement": {
    "agentIDs": ["customer-uuid", "agent-uuid"],
    "question": "Do you agree this work is complete?",
    "context": "Final deliverables reviewed",
    "signatures": [...]
  }
}

Complete Example

{
  "$schema": "https://hai.ai/schemas/task/v1/task.schema.json",
  "jacsId": "550e8400-e29b-41d4-a716-446655440000",
  "jacsType": "task",
  "jacsVersion": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "jacsVersionDate": "2024-01-15T10:30:00Z",
  "jacsOriginalVersion": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "jacsOriginalDate": "2024-01-15T10:30:00Z",
  "jacsLevel": "artifact",

  "jacsTaskName": "Build Authentication System",
  "jacsTaskSuccess": "Users can register, login, and manage sessions",
  "jacsTaskState": "started",

  "jacsTaskCustomer": {
    "agentID": "customer-agent-uuid",
    "agentVersion": "customer-version-uuid",
    "date": "2024-01-15T10:30:00Z",
    "signature": "customer-signature...",
    "publicKeyHash": "customer-key-hash",
    "signingAlgorithm": "ring-Ed25519",
    "fields": ["jacsTaskName", "jacsTaskActionsDesired"]
  },

  "jacsTaskAgent": {
    "agentID": "assigned-agent-uuid",
    "agentVersion": "agent-version-uuid",
    "date": "2024-01-16T09:00:00Z",
    "signature": "agent-signature...",
    "publicKeyHash": "agent-key-hash",
    "signingAlgorithm": "ring-Ed25519",
    "fields": ["jacsTaskName", "jacsTaskActionsDesired"]
  },

  "jacsTaskStartDate": "2024-01-16T09:00:00Z",

  "jacsStartAgreement": {
    "agentIDs": ["customer-agent-uuid", "assigned-agent-uuid"],
    "question": "Do you agree to begin work on this task?",
    "signatures": [
      {
        "agentID": "customer-agent-uuid",
        "signature": "...",
        "responseType": "agree",
        "date": "2024-01-16T09:00:00Z"
      },
      {
        "agentID": "assigned-agent-uuid",
        "signature": "...",
        "responseType": "agree",
        "date": "2024-01-16T09:05:00Z"
      }
    ]
  },

  "jacsTaskActionsDesired": [
    {
      "name": "User Registration",
      "description": "Implement user registration with email verification",
      "duration": { "value": 4, "unit": "hours" },
      "completionAgreementRequired": true
    },
    {
      "name": "User Login",
      "description": "Implement secure login with password hashing",
      "duration": { "value": 3, "unit": "hours" },
      "completionAgreementRequired": true
    },
    {
      "name": "Session Management",
      "description": "Implement JWT-based session tokens",
      "duration": { "value": 2, "unit": "hours" },
      "completionAgreementRequired": false
    }
  ],

  "jacsSignature": {
    "agentID": "customer-agent-uuid",
    "agentVersion": "customer-version-uuid",
    "date": "2024-01-15T10:30:00Z",
    "signature": "document-signature...",
    "publicKeyHash": "key-hash...",
    "signingAlgorithm": "ring-Ed25519",
    "fields": ["jacsId", "jacsTaskName", "jacsTaskActionsDesired"]
  }
}

Task Relationships

Sub-Tasks

Break large tasks into smaller units:

{
  "jacsTaskSubTaskOf": ["parent-task-uuid"]
}

Task Copies (Branching)

Create variations or branches:

{
  "jacsTaskCopyOf": ["original-task-uuid"]
}

Merged Tasks

Combine completed tasks:

{
  "jacsTaskMergedTasks": [
    "subtask-1-uuid",
    "subtask-2-uuid"
  ]
}

Task Workflow

1. Creating a Task

import jacs
import json

agent = jacs.JacsAgent()
agent.load('./jacs.config.json')

task = agent.create_document(json.dumps({
    'jacsTaskName': 'Build Feature X',
    'jacsTaskSuccess': 'Feature is deployed and tested',
    'jacsTaskState': 'creating',
    'jacsTaskActionsDesired': [
        {
            'name': 'Implementation',
            'description': 'Write the code',
            'completionAgreementRequired': True
        }
    ]
}), custom_schema='https://hai.ai/schemas/task/v1/task.schema.json')

2. Assigning an Agent

When an agent accepts the task, add their signature to jacsTaskAgent and update state to started.

3. Signing Start Agreement

Both parties sign the start agreement to confirm work begins.

4. Completing Work

Update state to review, then both parties sign the end agreement.

5. Final Completion

After end agreement is signed by all parties, update state to completed.

State Machine Rules

See Also

• Document Schema - Base document fields
• Agent Schema - Agent structure
• Agreements - Working with agreements
• JSON Schemas Overview - Schema architecture