$schema: http://json-schema.org/draft-07/schema#
$id: https://w3id.org/aac/schema/aac.schema.json
title: Agentic Automation Canvas Schema
description: JSON Schema for validating Agentic Automation Canvas data structure
type: object
required:
- project
properties:
  version:
    type: string
    description: Semantic version of the canvas (e.g., '0.1.0'). Should follow semantic
      versioning standards (https://semver.org/).
    pattern: ^\d+\.\d+\.\d+(-[\w\-]+)?(\+[\w\-]+)?$
  versionDate:
    type: string
    format: date
    description: Date when the version was downloaded or created (ISO date format)
  persons:
    type: array
    description: Centralized Person entities. All persons involved in the project
      are managed here and referenced by stakeholders and agents.
    items:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the Person (e.g., 'person-0', 'person-1')
        name:
          type: string
          minLength: 1
        affiliation:
          type: string
          description: Optional disambiguation field
        orcid:
          type: string
          format: uri
          description: Optional stable identifier (e.g., ORCID)
      required:
      - id
      - name
  project:
    type: object
    required:
    - title
    - description
    - projectStage
    properties:
      title:
        type: string
        minLength: 1
      description:
        type: string
        minLength: 1
      objective:
        type: string
      projectStage:
        type: string
      startDate:
        type: string
        format: date
      endDate:
        type: string
        format: date
      domain:
        type: array
        items:
          type: string
      keywords:
        type: array
        items:
          type: string
      fundingGrant:
        type: string
      leadOrganization:
        type: string
      projectId:
        type: string
        format: uri
      headlineValue:
        type: string
      primaryValueDriver:
        type: string
        enum:
        - time
        - quality
        - risk
        - enablement
        - cost
      roughEstimateValue:
        type: number
        minimum: 0
        description: Optional manual estimate of project-level benefit value when
          getting started (before task-level benefits)
      roughEstimateUnit:
        type: string
        description: Unit for the rough estimate (e.g., 'hours/month', '% error reduction',
          'incidents prevented/month')
      version:
        type: string
        description: Semantic version of the canvas (e.g., '0.1.0'). Should follow
          semantic versioning standards (https://semver.org/).
        pattern: ^\d+\.\d+\.\d+(-[\w\-]+)?(\+[\w\-]+)?$
      versionDate:
        type: string
        format: date
        description: Date when the version was downloaded or created (ISO date format)
  userExpectations:
    type: object
    properties:
      requirements:
        type: array
        items:
          type: object
          properties:
            id:
              type: string
            title:
              type: string
              minLength: 1
            description:
              type: string
            userStory:
              type: string
            priority:
              type: string
              enum:
              - low
              - medium
              - high
              - critical
            status:
              type: string
              enum:
              - planned
              - in-progress
              - completed
              - cancelled
            value:
              type: string
            unitOfWork:
              type: string
              minLength: 1
            unitCategory:
              type: string
              enum:
              - item
              - interaction
              - computation
              - other
            volumePerMonth:
              type: number
              minimum: 1
            timeUnit:
              type: string
              enum:
              - minutes
              - hours
              description: Standardized time unit for this requirement's time benefits
                and oversight. All time values use this unit for consistency.
            benefits:
              type: array
              description: Array of benefit metrics for this requirement
              items:
                $ref: '#/$defs/Benefit'
            dependsOn:
              type: array
              items:
                type: string
              description: IDs of requirements this task depends on
            stakeholders:
              type: array
              items:
                type: string
              description: Person IDs of stakeholders for this task
            targetPopulation:
              type: string
              description: The user population whose benefit estimates this task captures
                (e.g., 'junior researchers', 'clinical staff with 3+ years experience').
                Specifying this makes heterogeneity explicit when different user groups
                are expected to benefit differently from the same type of task.
            feasibility:
              type: object
              description: Optional per-task feasibility (overrides project-level
                defaults)
              properties:
                technicalRisk:
                  type: string
                  enum:
                  - low
                  - medium
                  - high
                  - critical
                effortEstimate:
                  type: object
                  properties:
                    value:
                      type: number
                      minimum: 0
                    unit:
                      type: string
                      enum:
                      - weeks
                      - person-hours
                  required:
                  - value
                  - unit
                feasibilityNotes:
                  type: string
                algorithms:
                  type: array
                  items:
                    type: string
                tools:
                  type: array
                  items:
                    type: string
                modelSelection:
                  type: string
                  enum:
                  - open-source
                  - frontier-model
                  - fine-tuned
                  - custom
                  - other
                  - none
                  description: Type of model to be used (if applicable). Set to 'none'
                    if task is deterministic.
                modelName:
                  type: string
                  description: Specific model name or identifier (e.g., 'claude-opus-4-5',
                    'Qwen2.5-72B-Instruct')
                modelCardUri:
                  type: string
                  format: uri
                  description: URI pointing to the model's model card
                technologyApproach:
                  type: object
                  description: Technology architecture approach for this task. Set
                    architecture to 'none' if task is deterministic and doesn't require
                    LLMs.
                  properties:
                    architecture:
                      type: string
                      enum:
                      - none
                      - simple-prompting
                      - rag
                      - fine-tuning
                      - agents
                      - other
                      description: Primary technology architecture. 'none' indicates
                        deterministic task without LLM requirement.
                    ragDetails:
                      type: object
                      properties:
                        retrievalMethod:
                          type: string
                        embeddingModel:
                          type: string
                        chunkingStrategy:
                          type: string
                    fineTuningDetails:
                      type: object
                      properties:
                        baseModel:
                          type: string
                          description: Base model that was fine-tuned
                        tuningApproach:
                          type: string
                          description: Method used for fine-tuning (e.g., LoRA, QLoRA,
                            full fine-tuning)
                        dataset:
                          type: string
                          description: Dataset used for fine-tuning
                    agenticDetails:
                      type: object
                      properties:
                        framework:
                          type: array
                          items:
                            type: string
                          description: e.g. ReAct, MCP, Plan-and-Execute
                        tools:
                          type: array
                          items:
                            type: string
                          description: MCP tools, custom tools
                        orchestration:
                          type: array
                          items:
                            type: string
                          description: e.g. LangGraph
                risks:
                  type: array
                  description: Per-task risk assessments paralleling benefits
                  items:
                    $ref: '#/$defs/Risk'
                deploymentCost:
                  type: object
                  description: Estimated deployment/operational cost for running this
                    automated task
                  properties:
                    costPerUnit:
                      type: number
                      minimum: 0
                      description: Cost per interaction/unit of work
                    costPerMonth:
                      type: number
                      minimum: 0
                      description: Flat monthly deployment cost
                    aggregationBasis:
                      type: string
                      enum:
                      - perUnit
                      - perMonth
                      description: Whether cost is specified per interaction (multiplied
                        by volume) or as a flat monthly figure
                    currency:
                      type: string
                      pattern: ^[A-Z]{3}$
                      description: Currency for the cost estimate as a 3-letter code
                        (e.g., USD, EUR, GBP)
                    costNotes:
                      type: string
                      description: Assumptions or notes about the cost estimate
                  required:
                  - aggregationBasis
                  - currency
          required:
          - id
          - title
          - benefits
  developerFeasibility:
    type: object
    description: Project-level feasibility (simple, generic defaults that apply to
      all tasks unless overridden)
    properties:
      trlLevel:
        type: object
        description: Technology Readiness Level - project-level maturity assessment
        properties:
          current:
            type: integer
            minimum: 1
            maximum: 9
          target:
            type: integer
            minimum: 1
            maximum: 9
      technicalRisk:
        type: string
        enum:
        - low
        - medium
        - high
        - critical
        description: Overall technical risk for the project
      effortEstimate:
        type: object
        description: Overall effort estimate for the project
        properties:
          value:
            type: number
            minimum: 0
          unit:
            type: string
            enum:
            - weeks
            - person-hours
        required:
        - value
        - unit
      feasibilityNotes:
        type: string
        description: Project-level feasibility notes
  governance:
    type: object
    properties:
      stages:
        type: array
        items:
          type: object
          properties:
            id:
              type: string
            name:
              type: string
            startDate:
              type: string
              format: date
            endDate:
              type: string
              format: date
            agents:
              type: array
              items:
                type: object
                properties:
                  personId:
                    type: string
                    description: Reference to Person entity ID (required when type
                      is 'person')
                  name:
                    type: string
                    description: Name for organization/software agents (required when
                      type is not 'person')
                  role:
                    type: string
                  type:
                    type: string
                    enum:
                    - person
                    - organization
                    - software
                  roleContext:
                    type: string
                    description: Optional role context
                required:
                - type
                if:
                  properties:
                    type:
                      const: person
                then:
                  required:
                  - personId
                else:
                  required:
                  - name
            milestones:
              type: array
              items:
                type: string
            complianceStandards:
              type: array
              description: Compliance standards as plain strings or structured framework
                references
              items:
                oneOf:
                - type: string
                - type: object
                  properties:
                    framework:
                      type: string
                      description: Name of the compliance framework (e.g., 'NIST AI
                        RMF', 'ISO/IEC 42001', 'EU AI Act')
                    clauses:
                      type: array
                      items:
                        type: string
                      description: Specific clauses or tokens (e.g., 'GOVERN-1', 'Article
                        72')
                    uri:
                      type: string
                      format: uri
                      description: URI to the framework or standard document
                  required:
                  - framework
            policyCardUri:
              type: string
              format: uri
              description: URI pointing to a Policy Card (machine-readable deployment
                governance artifact) governing this stage
          required:
          - id
          - name
  dataAccess:
    type: object
    properties:
      datasets:
        type: array
        items:
          type: object
          properties:
            id:
              type: string
            title:
              type: string
            description:
              type: string
            format:
              type: string
            license:
              type: string
              format: uri
            accessRights:
              type: string
            duoTerms:
              type: array
              items:
                type: string
                format: uri
            pid:
              type: string
              format: uri
            datasetSheetUri:
              type: string
              format: uri
              description: URI pointing to a FAIR dataset sheet
            publisher:
              type: string
            containsPersonalData:
              type: boolean
            sensitivityLevel:
              type: string
          required:
          - id
          - title
          - accessRights
  outcomes:
    type: object
    properties:
      deliverables:
        type: array
        items:
          type: object
          properties:
            id:
              type: string
            title:
              type: string
            type:
              type: string
            description:
              type: string
            date:
              type: string
              format: date
            pid:
              type: string
              format: uri
          required:
          - id
          - title
          - type
      publications:
        type: array
        items:
          type: object
          properties:
            id:
              type: string
            title:
              type: string
            doi:
              type: string
              format: uri
            authors:
              type: array
              description: Publication authors. Each author is either a reference
                to a Person entity or a free-text organization/consortium name.
              items:
                type: object
                properties:
                  type:
                    type: string
                    enum:
                    - person
                    - organization
                  personId:
                    type: string
                    description: Reference to Person entity ID (required when type
                      is 'person')
                  name:
                    type: string
                    description: Name for organization authors (required when type
                      is 'organization')
                required:
                - type
                if:
                  properties:
                    type:
                      const: person
                then:
                  required:
                  - personId
                else:
                  required:
                  - name
            date:
              type: string
              format: date
          required:
          - id
          - title
      evaluations:
        type: array
        items:
          type: object
          properties:
            id:
              type: string
            type:
              type: string
            date:
              type: string
              format: date
            metrics:
              type: object
              additionalProperties: true
            results:
              type: string
          required:
          - id
          - type
$defs:
  BenefitValue:
    description: 'A benefit value: numeric, categorical, or binary'
    oneOf:
    - type: object
      properties:
        type:
          const: numeric
        value:
          type: number
      required:
      - type
      - value
    - type: object
      properties:
        type:
          const: categorical
        category:
          type: string
          enum:
          - low
          - medium
          - high
      required:
      - type
      - category
    - type: object
      properties:
        type:
          const: binary
        bool:
          type: boolean
      required:
      - type
      - bool
  Benefit:
    type: object
    description: A benefit metric for a requirement
    properties:
      benefitType:
        type: string
        enum:
        - time
        - quality
        - risk
        - enablement
        - cost
        description: Type of benefit
      metricId:
        type: string
        description: Identifier for the metric (controlled vocabulary or 'custom')
      metricLabel:
        type: string
        description: Human-readable label for the metric
      direction:
        type: string
        enum:
        - increaseIsBetter
        - decreaseIsBetter
        - targetIsBetter
        - boolIsBetter
        description: Indicates whether higher values, lower values, hitting a target,
          or boolean true is the desired outcome
      valueMeaning:
        type: string
        enum:
        - absolute
        - delta
        description: Whether baseline/expected are absolute measured values or improvement
          deltas
      target:
        type: number
        description: Target value when direction is 'targetIsBetter'
      aggregationBasis:
        type: string
        enum:
        - perUnit
        - perMonth
        - oneOff
        default: perUnit
        description: How the benefit value is aggregated
      benefitUnit:
        type: string
        description: Unit for the benefit value (e.g., 'minutes', '%', 'incidents/month')
      baseline:
        $ref: '#/$defs/BenefitValue'
        description: Baseline value before automation
      expected:
        $ref: '#/$defs/BenefitValue'
        description: Expected value after automation
      oversightMinutesPerUnit:
        type: number
        minimum: 0
        description: Human oversight per unit in minutes. Only used when aggregationBasis
          is 'perUnit'. Mutually exclusive with oversightMinutesPerMonth. Subtracted
          from gross time benefit.
      oversightMinutesPerMonth:
        type: number
        minimum: 0
        description: Human oversight per month in minutes. Only used when aggregationBasis
          is 'perMonth'. Mutually exclusive with oversightMinutesPerUnit. Subtracted
          from gross time benefit.
      confidenceUser:
        type: string
        enum:
        - low
        - medium
        - high
        description: User's confidence in the benefit estimate
      confidenceDev:
        type: string
        enum:
        - low
        - medium
        - high
        description: Developer's confidence in the benefit estimate
      assumptions:
        type: string
        description: Key assumptions underlying the benefit estimate
    required:
    - benefitType
    - metricId
    - metricLabel
    - direction
    - valueMeaning
    - benefitUnit
    - baseline
    - expected
  Risk:
    type: object
    description: A risk assessment for a requirement, paralleling benefit metrics
    properties:
      id:
        type: string
        description: Unique identifier for the risk
      riskCategory:
        type: string
        enum:
        - technical
        - data
        - compliance
        - operational
        - ethical
        - adoption
        description: Category of risk
      title:
        type: string
        minLength: 1
        description: Short title for the risk
      description:
        type: string
        description: Detailed description of the risk
      likelihood:
        type: string
        enum:
        - low
        - medium
        - high
        - critical
        description: Probability of the risk occurring
      impact:
        type: string
        enum:
        - low
        - medium
        - high
        - critical
        description: Severity if the risk materialises
      mitigation:
        type: string
        description: Strategy to mitigate or address the risk
      status:
        type: string
        enum:
        - identified
        - mitigated
        - accepted
        - resolved
        description: Current status of the risk
    required:
    - id
    - riskCategory
    - title
    - likelihood
    - impact
    - status