trueppm-api 0.4.0__py3-none-any.whl

trueppm_api/apps/projects/schemas/seed_v1.json

@@ -0,0 +1,492 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://trueppm.com/schemas/seed/v1.json",
+  "title": "TruePPM seed data v1",
+  "description": "Canonical JSON seed format for sample projects and universal import/export (ADR-0109, epic #613). One document describes one program and its projects. Stable cross-references use file-local slugs and ltree wbs paths; UUIDs and derived fields (server_version, CPM outputs, short_id) are never present.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "program", "projects"],
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "description": "Schema major.minor. validate_seed() rejects unsupported majors.",
+      "const": "1.0"
+    },
+    "program": { "$ref": "#/$defs/program" },
+    "accounts": {
+      "type": "array",
+      "maxItems": 2000,
+      "description": "User logins referenced by the seed. Created only when import runs with --create-users.",
+      "items": { "$ref": "#/$defs/account" }
+    },
+    "calendars": {
+      "type": "array",
+      "maxItems": 200,
+      "items": { "$ref": "#/$defs/calendar" }
+    },
+    "resources": {
+      "type": "array",
+      "maxItems": 5000,
+      "items": { "$ref": "#/$defs/resource" }
+    },
+    "risks": {
+      "type": "array",
+      "maxItems": 5000,
+      "description": "Program-scoped risks. Project-scoped risks live under each project.",
+      "items": { "$ref": "#/$defs/risk" }
+    },
+    "projects": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 200,
+      "items": { "$ref": "#/$defs/project" }
+    }
+  },
+  "$defs": {
+    "slug": {
+      "type": "string",
+      "description": "File-local stable identifier, kebab-case. Capped at 40 so the program slug fits Program.code.",
+      "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
+      "maxLength": 40
+    },
+    "wbsPath": {
+      "type": "string",
+      "description": "ltree path, e.g. \"1.2.3\". Per-project task identity.",
+      "pattern": "^[A-Za-z0-9_]+(\\.[A-Za-z0-9_]+)*$",
+      "maxLength": 255
+    },
+    "taskRelation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["target", "link_type"],
+      "description": "An informational task-to-task cross-reference (ADR-0455), authored on a task's `links` array with that task as the source. `target` is a task ref (bare wbs path for the enclosing project, or \"<project-slug>:<wbs-path>\" for a sibling project in the same program). Distinct from a scheduling `dependency`: inert, no CPM edge, no lag.",
+      "properties": {
+        "target": { "$ref": "#/$defs/taskRef" },
+        "link_type": {
+          "enum": ["relates_to", "blocks", "duplicates"],
+          "description": "RELATES_TO is symmetric; BLOCKS and DUPLICATES are directional (source → target)."
+        },
+        "note": { "type": "string", "maxLength": 280 }
+      }
+    },
+    "taskRef": {
+      "type": "string",
+      "description": "A task by wbs path. Bare for the enclosing project, or \"<project-slug>:<wbs-path>\" for a sibling project.",
+      "pattern": "^([a-z0-9]+(-[a-z0-9]+)*:)?[A-Za-z0-9_]+(\\.[A-Za-z0-9_]+)*$"
+    },
+    "color": {
+      "type": "string",
+      "pattern": "^#[0-9A-Fa-f]{6}$"
+    },
+    "program": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["slug", "name", "methodology"],
+      "properties": {
+        "slug": {
+          "$ref": "#/$defs/slug",
+          "description": "Program natural key. Persisted into Program.code; re-import upserts on (workspace, code)."
+        },
+        "name": { "type": "string", "minLength": 1, "maxLength": 255 },
+        "description": { "type": "string", "maxLength": 100000 },
+        "methodology": { "enum": ["WATERFALL", "AGILE", "HYBRID"] },
+        "color": { "$ref": "#/$defs/color" },
+        "lead": {
+          "$ref": "#/$defs/slug",
+          "description": "Account slug of the program lead."
+        }
+      }
+    },
+    "account": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["slug", "username"],
+      "properties": {
+        "slug": { "$ref": "#/$defs/slug" },
+        "username": { "type": "string", "minLength": 1, "maxLength": 150 },
+        "email": { "type": "string", "format": "email" },
+        "display_name": { "type": "string", "maxLength": 255 },
+        "role": {
+          "enum": ["VIEWER", "MEMBER", "SCHEDULER", "ADMIN", "OWNER"],
+          "description": "Program membership role granted on import."
+        }
+      }
+    },
+    "projectMember": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["account", "role"],
+      "description": "One project-level membership. See project.members.",
+      "properties": {
+        "account": { "$ref": "#/$defs/slug" },
+        "role": {
+          "enum": ["VIEWER", "MEMBER", "SCHEDULER", "ADMIN", "OWNER"],
+          "description": "Project membership role granted on import."
+        }
+      }
+    },
+    "boardLane": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["key", "label"],
+      "description": "A named lane WITHIN a board column (#2967). Keys are unique project-wide.",
+      "properties": {
+        "key": { "$ref": "#/$defs/slug" },
+        "label": { "type": "string", "minLength": 1, "maxLength": 32 },
+        "wip_limit": { "type": ["integer", "null"], "minimum": 1 }
+      }
+    },
+    "boardColumn": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["status", "label"],
+      "description": "One Kanban column. Mirrors BoardColumnConfig.columns; the seed cannot express a shape the board API would reject.",
+      "properties": {
+        "status": {
+          "enum": ["BACKLOG", "NOT_STARTED", "IN_PROGRESS", "REVIEW", "COMPLETE"]
+        },
+        "label": { "type": "string", "minLength": 1, "maxLength": 32 },
+        "visible": { "type": "boolean" },
+        "color": { "type": ["string", "null"], "pattern": "^#[0-9A-Fa-f]{6}$" },
+        "wip_limit": { "type": ["integer", "null"], "minimum": 1 },
+        "age_threshold_days": { "type": ["integer", "null"], "minimum": 1 },
+        "lanes": {
+          "type": "array",
+          "maxItems": 6,
+          "items": { "$ref": "#/$defs/boardLane" }
+        }
+      }
+    },
+    "taskAttachment": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["external_url"],
+      "description": "An external reference on a task. URL-only: TaskAttachment stores a file XOR an external_url, and a seed is a text document, so the file half is deliberately not expressible.",
+      "properties": {
+        "external_url": { "type": "string", "format": "uri", "maxLength": 2048 },
+        "external_title": { "type": "string", "maxLength": 255 },
+        "is_pinned": { "type": "boolean" },
+        "uploaded_by": { "$ref": "#/$defs/slug" }
+      }
+    },
+    "taskBlocker": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "The explicit human blocker flag (#1135, ADR-0124). A present cluster means blocked. `reason` is optional: an export withholds the private reason text from anyone but the task's assignee or an @-mentioned user (#4082), and the importer stamps a placeholder so the task still imports as blocked. NOT the derived has-incomplete-predecessors signal, and `blocking_task` is a soft 'waiting on' link that never enters CPM.",
+      "properties": {
+        "reason": { "type": "string", "minLength": 1, "maxLength": 100000 },
+        "since": { "type": "string", "format": "date" },
+        "type": { "enum": ["dependency", "resource", "vendor", "decision", "other"] },
+        "blocking_task": { "type": "string", "maxLength": 512 },
+        "by": { "$ref": "#/$defs/slug" }
+      }
+    },
+    "calendar": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["slug", "name"],
+      "properties": {
+        "slug": { "$ref": "#/$defs/slug" },
+        "name": { "type": "string", "minLength": 1, "maxLength": 255 },
+        "working_days": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 127,
+          "description": "Bitmask Mon=1..Sun=64. Default 31 (Mon-Fri)."
+        },
+        "hours_per_day": { "type": "number", "exclusiveMinimum": 0, "maximum": 24 },
+        "timezone": { "type": "string", "maxLength": 64 },
+        "exceptions": {
+          "type": "array",
+          "description": "Non-working date ranges (holidays, shutdowns, PTO). Materialized as CalendarException rows on import.",
+          "maxItems": 500,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["exc_start", "exc_end"],
+            "properties": {
+              "exc_start": { "type": "string", "format": "date" },
+              "exc_end": { "type": "string", "format": "date" },
+              "description": { "type": "string", "maxLength": 255 }
+            }
+          }
+        }
+      }
+    },
+    "resource": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["slug", "name"],
+      "properties": {
+        "slug": { "$ref": "#/$defs/slug" },
+        "name": { "type": "string", "minLength": 1, "maxLength": 255 },
+        "email": { "type": "string", "format": "email" },
+        "job_role": { "type": "string", "maxLength": 120 },
+        "max_units": {
+          "type": "number",
+          "exclusiveMinimum": 0,
+          "maximum": 99.99,
+          "description": "Availability fraction. 1.0 = full-time. 0.1 = 10% advisor."
+        },
+        "calendar": { "$ref": "#/$defs/slug" },
+        "account": {
+          "$ref": "#/$defs/slug",
+          "description": "Optional account slug linking this resource to a user login (Resource.user)."
+        }
+      }
+    },
+    "estimate": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["optimistic", "most_likely", "pessimistic"],
+      "description": "Three-point PERT estimate in working days. All-or-none: present means all three; omit entirely for unestimated tasks. Never set on summary or milestone tasks.",
+      "properties": {
+        "optimistic": { "type": "integer", "minimum": 0 },
+        "most_likely": { "type": "integer", "minimum": 0 },
+        "pessimistic": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "task": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["wbs_path", "name"],
+      "properties": {
+        "wbs_path": { "$ref": "#/$defs/wbsPath" },
+        "name": { "type": "string", "minLength": 1, "maxLength": 512 },
+        "type": {
+          "enum": ["epic", "story", "task", "bug", "spike", "tech_debt"],
+          "description": "TaskType. tech_debt is accepted here too: the v1 (final-state) exporter writes Task.type verbatim, so without it a program holding tech-debt work exported a document its own schema rejected (#3496)."
+        },
+        "status": {
+          "enum": ["BACKLOG", "NOT_STARTED", "IN_PROGRESS", "REVIEW", "ON_HOLD", "COMPLETE"]
+        },
+        "is_milestone": { "type": "boolean" },
+        "duration": { "type": "integer", "minimum": 0 },
+        "planned_start": { "type": "string", "format": "date" },
+        "percent_complete": { "type": "number", "minimum": 0, "maximum": 100 },
+        "notes": { "type": "string", "maxLength": 10000 },
+        "estimate": { "$ref": "#/$defs/estimate" },
+        "story_points": { "type": "integer", "minimum": 0 },
+        "remaining_points": { "type": "integer", "minimum": 0 },
+        "assignee": { "$ref": "#/$defs/slug" },
+        "sprint": { "$ref": "#/$defs/slug" },
+        "parent_epic": {
+          "$ref": "#/$defs/wbsPath",
+          "description": "wbs_path of the epic task grouping this story (Task.parent_epic)."
+        },
+        "dor": { "enum": ["idea", "refine", "ready"] },
+        "sprint_rank": { "type": "integer", "minimum": 0 },
+        "governance_class": { "enum": ["gated", "flow", "hybrid"] },
+        "delivery_mode": { "enum": ["waterfall", "scrum", "kanban", "milestone"] },
+        "color": { "$ref": "#/$defs/color" },
+        "labels": {
+          "type": "array",
+          "description": "Slugs of project labels (ADR-0400) attached to this task, referencing project.labels.",
+          "items": { "$ref": "#/$defs/slug" }
+        },
+        "board_lane": {
+          "$ref": "#/$defs/slug",
+          "description": "Named lane WITHIN this task's status column (#2967); must match a lane key on the project's board_columns entry for that status."
+        },
+        "blocked": { "$ref": "#/$defs/taskBlocker" },
+        "links": {
+          "type": "array",
+          "default": [],
+          "description": "Informational task-to-task relations (ADR-0455) authored on this task as the source, e.g. \"relates to\" / \"blocks\" / \"duplicates\". A relation is a non-scheduling cross-reference — distinct from a CPM `dependency` — so it carries no lag, dep_type, or schedule effect.",
+          "items": { "$ref": "#/$defs/taskRelation" }
+        },
+        "attachments": {
+          "type": "array",
+          "maxItems": 50,
+          "items": { "$ref": "#/$defs/taskAttachment" }
+        },
+        "assignments": {
+          "type": "array",
+          "description": "Resource allocations on this task. assignee is the responsible user; assignments are capacity (Resource + units fraction of max_units).",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["resource"],
+            "properties": {
+              "resource": { "$ref": "#/$defs/slug" },
+              "units": { "type": "number", "exclusiveMinimum": 0, "maximum": 99.99 }
+            }
+          }
+        }
+      }
+    },
+    "dependency": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["predecessor", "successor", "dep_type"],
+      "properties": {
+        "predecessor": { "$ref": "#/$defs/taskRef" },
+        "successor": { "$ref": "#/$defs/taskRef" },
+        "dep_type": { "enum": ["FS", "SS", "FF", "SF"] },
+        "lag": {
+          "type": "integer",
+          "description": "Calendar days. Positive = delay, negative = lead."
+        }
+      }
+    },
+    "sprint": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["slug", "name", "state", "start_date", "finish_date"],
+      "properties": {
+        "slug": { "$ref": "#/$defs/slug" },
+        "name": { "type": "string", "minLength": 1, "maxLength": 255 },
+        "goal": { "type": "string", "maxLength": 10000 },
+        "notes": { "type": "string", "maxLength": 10000 },
+        "start_date": { "type": "string", "format": "date" },
+        "finish_date": { "type": "string", "format": "date" },
+        "state": { "enum": ["PLANNED", "ACTIVE", "COMPLETED", "CANCELLED"] },
+        "committed_points": { "type": "integer", "minimum": 0 },
+        "completed_points": { "type": "integer", "minimum": 0 },
+        "capacity_points": { "type": "integer", "minimum": 0 },
+        "target_milestone": {
+          "$ref": "#/$defs/wbsPath",
+          "description": "wbs_path of a milestone task in the same project."
+        }
+      }
+    },
+    "baselineTask": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["task"],
+      "properties": {
+        "task": { "$ref": "#/$defs/wbsPath" },
+        "start": { "type": "string", "format": "date" },
+        "finish": { "type": "string", "format": "date" },
+        "duration": { "type": "integer", "minimum": 0 },
+        "story_points": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "baseline": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "tasks"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1, "maxLength": 255 },
+        "is_active": { "type": "boolean" },
+        "captured_at": {
+          "type": "string",
+          "format": "date",
+          "description": "When this baseline was captured. Sets Baseline.created_at, which is otherwise auto_now_add — the interval between two baselines is what planned-vs-actual is measured over."
+        },
+        "tasks": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/baselineTask" }
+        }
+      }
+    },
+    "risk": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["slug", "title", "status", "probability", "impact"],
+      "properties": {
+        "slug": { "$ref": "#/$defs/slug" },
+        "title": { "type": "string", "minLength": 1, "maxLength": 512 },
+        "description": { "type": "string", "maxLength": 100000 },
+        "status": { "enum": ["OPEN", "MITIGATING", "RESOLVED", "ACCEPTED", "CLOSED"] },
+        "probability": { "type": "integer", "minimum": 1, "maximum": 5 },
+        "impact": { "type": "integer", "minimum": 1, "maximum": 5 },
+        "category": { "enum": ["TECHNICAL", "EXTERNAL", "ORGANIZATIONAL", "PROJECT_MANAGEMENT"] },
+        "response": { "enum": ["AVOID", "MITIGATE", "TRANSFER", "ACCEPT"] },
+        "mitigation_due_date": { "type": "string", "format": "date" },
+        "trigger": { "type": "string", "maxLength": 10000 },
+        "contingency": { "type": "string", "maxLength": 10000 },
+        "notes": { "type": "string", "maxLength": 10000 },
+        "owner": { "$ref": "#/$defs/slug" },
+        "tasks": {
+          "type": "array",
+          "description": "Task refs this risk is linked to. Bare wbs path = enclosing project; \"<slug>:<wbs>\" = sibling project (program-scoped risks only).",
+          "items": { "$ref": "#/$defs/taskRef" }
+        }
+      }
+    },
+    "label": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["slug", "name"],
+      "description": "A project-scoped, colored task label (ADR-0400). Referenced by task.labels via slug.",
+      "properties": {
+        "slug": { "$ref": "#/$defs/slug" },
+        "name": { "type": "string", "minLength": 1, "maxLength": 50 },
+        "color": {
+          "enum": ["slate", "teal", "purple", "blue", "rose", "amber", "green", "cyan"],
+          "description": "Stable categorical palette key (LabelColor), never a raw hex."
+        },
+        "position": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "project": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["slug", "name", "methodology", "start_date"],
+      "properties": {
+        "slug": { "$ref": "#/$defs/slug" },
+        "name": { "type": "string", "minLength": 1, "maxLength": 255 },
+        "description": { "type": "string", "maxLength": 100000 },
+        "methodology": { "enum": ["WATERFALL", "AGILE", "HYBRID"] },
+        "start_date": { "type": "string", "format": "date" },
+        "calendar": { "$ref": "#/$defs/slug" },
+        "code": { "type": "string", "maxLength": 12 },
+        "lead": {
+          "$ref": "#/$defs/slug",
+          "description": "Account slug of this project's lead. Distinct from the program lead and from the OWNER membership: a workstream lead is who a program manager asks about this project, and is what the project header and program roll-up display."
+        },
+        "default_view": { "enum": ["SCHEDULE", "BOARD", "TABLE", "OVERVIEW"] },
+        "health": {
+          "enum": ["AUTO", "ON_TRACK", "AT_RISK", "CRITICAL"],
+          "description": "PM override for the project health chip (#520). Omit or AUTO to defer to the rollup; the explicit values are a manual judgment that surfaces immediately in lists and on the program overview."
+        },
+        "estimation_mode": { "enum": ["open", "suggest_approve", "pm_only"] },
+        "members": {
+          "type": "array",
+          "maxItems": 2000,
+          "description": "Per-project memberships. Omit to grant every account its program-level accounts[].role on this project. Final-state data, so it lives in v1 as well as v2.",
+          "items": { "$ref": "#/$defs/projectMember" }
+        },
+        "agile_features": {
+          "type": "boolean",
+          "deprecated": true,
+          "description": "Accepted and ignored. The model field was removed in migration 0123 and the value is now derived from the project's own sprints; a document carrying this key still imports so an existing hand-authored seed does not break on upgrade."
+        },
+        "board_columns": {
+          "type": "array",
+          "maxItems": 5,
+          "description": "Kanban board configuration (BoardColumnConfig). All five canonical statuses must appear exactly once. Omit to leave the project on the API's hardcoded defaults.",
+          "items": { "$ref": "#/$defs/boardColumn" }
+        },
+        "labels": {
+          "type": "array",
+          "description": "Project label catalog (ADR-0400). Tasks reference these by slug via task.labels.",
+          "items": { "$ref": "#/$defs/label" }
+        },
+        "tasks": {
+          "type": "array",
+          "maxItems": 20000,
+          "items": { "$ref": "#/$defs/task" }
+        },
+        "dependencies": {
+          "type": "array",
+          "maxItems": 50000,
+          "items": { "$ref": "#/$defs/dependency" }
+        },
+        "sprints": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/sprint" }
+        },
+        "baselines": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/baseline" }
+        },
+        "risks": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/risk" }
+        }
+      }
+    }
+  }
+}