# PROV-JSON Export Schema
# Based on REF-062 W3C PROV-DM
# Issue: #138

$schema: "https://json-schema.org/draft/2020-12/schema"
$id: "https://aiwg.io/schemas/prov-json/v1"
title: "W3C PROV-JSON Export Schema"
description: |
  Schema for exporting AIWG provenance as W3C PROV-JSON format.
  Enables interoperability with standard provenance tools.

type: object
required:
  - prefix
  - entity

properties:
  prefix:
    type: object
    description: "Namespace prefixes"
    properties:
      prov:
        type: string
        const: "http://www.w3.org/ns/prov#"
      aiwg:
        type: string
        const: "https://aiwg.io/provenance/"
      xsd:
        type: string
        const: "http://www.w3.org/2001/XMLSchema#"
    additionalProperties:
      type: string

  entity:
    type: object
    additionalProperties:
      $ref: "#/$defs/Entity"
    description: "PROV entities (artifacts, documents)"

  activity:
    type: object
    additionalProperties:
      $ref: "#/$defs/Activity"
    description: "PROV activities (workflow executions)"

  agent:
    type: object
    additionalProperties:
      $ref: "#/$defs/Agent"
    description: "PROV agents (users, AI agents)"

  wasGeneratedBy:
    type: object
    additionalProperties:
      $ref: "#/$defs/Generation"
    description: "Entity generated by activity"

  used:
    type: object
    additionalProperties:
      $ref: "#/$defs/Usage"
    description: "Activity used entity"

  wasAttributedTo:
    type: object
    additionalProperties:
      $ref: "#/$defs/Attribution"
    description: "Entity attributed to agent"

  wasAssociatedWith:
    type: object
    additionalProperties:
      $ref: "#/$defs/Association"
    description: "Activity associated with agent"

  wasDerivedFrom:
    type: object
    additionalProperties:
      $ref: "#/$defs/Derivation"
    description: "Entity derived from entity"

  actedOnBehalfOf:
    type: object
    additionalProperties:
      $ref: "#/$defs/Delegation"
    description: "Agent acted on behalf of agent"

$defs:
  Entity:
    type: object
    properties:
      "prov:type":
        type: string
      "prov:value":
        type: string
      "prov:generatedAtTime":
        type: string
        format: date-time
      "prov:invalidatedAtTime":
        type: string
        format: date-time
      "aiwg:version":
        type: string
      "aiwg:artifactType":
        type: string
        enum:
          - UseCase
          - UserStory
          - Requirement
          - Architecture
          - SourceCode
          - Test
          - Documentation
          - Research
    additionalProperties: true

  Activity:
    type: object
    properties:
      "prov:type":
        type: string
      "prov:startedAtTime":
        type: string
        format: date-time
      "prov:endedAtTime":
        type: string
        format: date-time
      "aiwg:phase":
        type: string
        enum: [concept, inception, elaboration, construction, transition]
      "aiwg:workflow":
        type: string
      "aiwg:iteration":
        type: integer
    additionalProperties: true

  Agent:
    type: object
    properties:
      "prov:type":
        type: string
        enum:
          - "prov:Person"
          - "prov:SoftwareAgent"
          - "aiwg:AIAgent"
      "aiwg:role":
        type: string
      "aiwg:model":
        type: string
        description: "AI model if applicable"
    additionalProperties: true

  Generation:
    type: object
    required:
      - "prov:entity"
      - "prov:activity"
    properties:
      "prov:entity":
        type: string
        description: "Generated entity ID"
      "prov:activity":
        type: string
        description: "Generating activity ID"
      "prov:time":
        type: string
        format: date-time

  Usage:
    type: object
    required:
      - "prov:activity"
      - "prov:entity"
    properties:
      "prov:activity":
        type: string
        description: "Using activity ID"
      "prov:entity":
        type: string
        description: "Used entity ID"
      "prov:time":
        type: string
        format: date-time

  Attribution:
    type: object
    required:
      - "prov:entity"
      - "prov:agent"
    properties:
      "prov:entity":
        type: string
        description: "Attributed entity ID"
      "prov:agent":
        type: string
        description: "Responsible agent ID"

  Association:
    type: object
    required:
      - "prov:activity"
      - "prov:agent"
    properties:
      "prov:activity":
        type: string
        description: "Associated activity ID"
      "prov:agent":
        type: string
        description: "Associated agent ID"
      "prov:plan":
        type: string
        description: "Plan entity ID"

  Derivation:
    type: object
    required:
      - "prov:generatedEntity"
      - "prov:usedEntity"
    properties:
      "prov:generatedEntity":
        type: string
        description: "Derived entity ID"
      "prov:usedEntity":
        type: string
        description: "Source entity ID"
      "prov:activity":
        type: string
        description: "Deriving activity ID"
      "prov:type":
        type: string
        enum:
          - "prov:Revision"
          - "prov:Quotation"
          - "prov:PrimarySource"
          - "aiwg:Implementation"
          - "aiwg:Test"

  Delegation:
    type: object
    required:
      - "prov:delegate"
      - "prov:responsible"
    properties:
      "prov:delegate":
        type: string
        description: "Delegate agent ID"
      "prov:responsible":
        type: string
        description: "Responsible agent ID"
      "prov:activity":
        type: string
        description: "Associated activity ID"

# AIWG to PROV-JSON mapping
mapping:
  artifacts_to_entities:
    use_case: "aiwg:UseCase"
    user_story: "aiwg:UserStory"
    requirement: "aiwg:Requirement"
    architecture: "aiwg:Architecture"
    source_code: "aiwg:SourceCode"
    test: "aiwg:Test"
    documentation: "aiwg:Documentation"
    research: "aiwg:Research"

  workflows_to_activities:
    sdlc_phase: "aiwg:SDLCPhase"
    ralph_iteration: "aiwg:RalphIteration"
    agent_invocation: "aiwg:AgentInvocation"

  agents_to_agents:
    human_user: "prov:Person"
    ai_agent: "aiwg:AIAgent"
    tool: "prov:SoftwareAgent"

# Export formats
export_formats:
  prov_json:
    extension: ".prov.json"
    mime_type: "application/json"
    description: "Standard PROV-JSON"

  prov_n:
    extension: ".prov.n"
    mime_type: "text/provenance-notation"
    description: "PROV-N notation"

  graphviz_dot:
    extension: ".dot"
    mime_type: "text/vnd.graphviz"
    description: "GraphViz DOT for visualization"

# Agent protocol
agent_protocol:
  export_workflow:
    description: "Export provenance as PROV-JSON"
    steps:
      - load_provenance_records
      - build_entity_map
      - build_activity_map
      - build_agent_map
      - build_relationships
      - validate_prov_json
      - write_output

  validation:
    description: "Validate PROV-JSON conformance"
    checks:
      - required_fields_present
      - entity_references_valid
      - activity_references_valid
      - agent_references_valid
      - timestamps_valid

# Visualization
visualization:
  graphviz:
    node_styles:
      entity: "shape=ellipse, color=yellow"
      activity: "shape=box, color=blue"
      agent: "shape=house, color=green"
    edge_styles:
      wasGeneratedBy: "color=blue"
      used: "color=blue, style=dashed"
      wasAttributedTo: "color=green"
      wasDerivedFrom: "color=red"

# Examples
examples:
  simple_derivation:
    prefix:
      prov: "http://www.w3.org/ns/prov#"
      aiwg: "https://aiwg.io/provenance/"
    entity:
      "aiwg:artifact/UC-001.md":
        "prov:type": "aiwg:UseCase"
        "aiwg:version": "1.0"
        "prov:generatedAtTime": "2026-01-25T10:00:00Z"
      "aiwg:artifact/src/auth/login.ts":
        "prov:type": "aiwg:SourceCode"
        "aiwg:version": "1.0"
    activity:
      "aiwg:workflow/construction-001":
        "prov:type": "aiwg:SDLCPhase"
        "aiwg:phase": "construction"
        "prov:startedAtTime": "2026-01-25T11:00:00Z"
        "prov:endedAtTime": "2026-01-25T12:00:00Z"
    agent:
      "aiwg:agent/software-implementer":
        "prov:type": "aiwg:AIAgent"
        "aiwg:role": "SoftwareImplementer"
    wasGeneratedBy:
      "_:wGB1":
        "prov:entity": "aiwg:artifact/src/auth/login.ts"
        "prov:activity": "aiwg:workflow/construction-001"
    wasDerivedFrom:
      "_:wDF1":
        "prov:generatedEntity": "aiwg:artifact/src/auth/login.ts"
        "prov:usedEntity": "aiwg:artifact/UC-001.md"
        "prov:type": "aiwg:Implementation"

# References
references:
  research:
    - "@.aiwg/research/findings/REF-062-w3c-prov.md"
  implementation:
    - "#138"
  related:
    - "@agentic/code/frameworks/sdlc-complete/schemas/provenance/prov-record.yaml"
    - "@agentic/code/frameworks/sdlc-complete/schemas/provenance/derivation-graph.yaml"
  external:
    - "https://www.w3.org/TR/prov-json/"
    - "https://www.w3.org/TR/prov-dm/"