@forwardimpact/schema 0.1.0

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@forwardimpact/schema",
+  "version": "0.1.0",
+  "description": "Schema definitions and validation for Engineering Pathway framework",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/forwardimpact/pathway",
+    "directory": "apps/schema"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "bin": {
+    "fit-schema": "./bin/fit-schema.js"
+  },
+  "scripts": {
+    "validate": "node ./bin/fit-schema.js validate",
+    "generate-index": "node ./bin/fit-schema.js generate-index",
+    "validate:shacl": "node ./bin/fit-schema.js validate:shacl"
+  },
+  "files": [
+    "bin/",
+    "examples/",
+    "lib/",
+    "schema/"
+  ],
+  "exports": {
+    ".": "./lib/index.js",
+    "./loader": "./lib/loader.js",
+    "./validation": "./lib/validation.js",
+    "./schema-validation": "./lib/schema-validation.js",
+    "./index-generator": "./lib/index-generator.js",
+    "./levels": "./lib/levels.js",
+    "./examples/*": "./examples/*",
+    "./schema/json/*": "./schema/json/*",
+    "./schema/rdf/*": "./schema/rdf/*"
+  },
+  "dependencies": {
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
+    "yaml": "^2.3.4"
+  },
+  "devDependencies": {
+    "n3": "^2.0.1"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/schema/json/behaviour-questions.schema.json

@@ -0,0 +1,68 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schema.forwardimpact.team/json/behaviour-questions.schema.json",
+  "title": "Behaviour Interview Questions",
+  "description": "Interview questions for a behaviour, organized by maturity level",
+  "type": "object",
+  "properties": {
+    "emerging": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/question" }
+    },
+    "developing": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/question" }
+    },
+    "practicing": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/question" }
+    },
+    "role_modeling": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/question" }
+    },
+    "exemplifying": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/question" }
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "question": {
+      "type": "object",
+      "required": ["id", "text", "lookingFor"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9_]*$",
+          "description": "Unique question identifier (format: {abbrev}_{maturity_abbrev}_{number})"
+        },
+        "text": {
+          "type": "string",
+          "maxLength": 150,
+          "description": "The question text (second person, under 150 characters)"
+        },
+        "lookingFor": {
+          "type": "array",
+          "description": "2-4 bullet points of good answer indicators",
+          "minItems": 1,
+          "maxItems": 4,
+          "items": { "type": "string" }
+        },
+        "expectedDurationMinutes": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Expected duration in minutes (default: 5 for emerging/developing, 8-10 for higher)"
+        },
+        "followUps": {
+          "type": "array",
+          "description": "1-3 probing questions for deeper exploration",
+          "minItems": 1,
+          "maxItems": 3,
+          "items": { "type": "string" }
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/schema/json/behaviour.schema.json

@@ -0,0 +1,73 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schema.forwardimpact.team/json/behaviour.schema.json",
+  "title": "Behaviour",
+  "description": "Mindset and way of working that underpins effective application of skills",
+  "type": "object",
+  "required": ["name", "human"],
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Human-readable behaviour name"
+    },
+    "human": {
+      "$ref": "#/$defs/behaviourHumanSection",
+      "description": "Human-specific content"
+    },
+    "agent": {
+      "$ref": "#/$defs/behaviourAgentSection",
+      "description": "Agent-specific content"
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "behaviourHumanSection": {
+      "type": "object",
+      "required": ["description", "maturityDescriptions"],
+      "properties": {
+        "description": {
+          "type": "string",
+          "description": "Description of the behaviour"
+        },
+        "maturityDescriptions": {
+          "$ref": "#/$defs/maturityDescriptions",
+          "description": "Description of expectations at each maturity level"
+        }
+      },
+      "additionalProperties": false
+    },
+    "maturityDescriptions": {
+      "type": "object",
+      "properties": {
+        "emerging": { "type": "string" },
+        "developing": { "type": "string" },
+        "practicing": { "type": "string" },
+        "role_modeling": { "type": "string" },
+        "exemplifying": { "type": "string" }
+      },
+      "required": [
+        "emerging",
+        "developing",
+        "practicing",
+        "role_modeling",
+        "exemplifying"
+      ],
+      "additionalProperties": false
+    },
+    "behaviourAgentSection": {
+      "type": "object",
+      "required": ["title", "workingStyle"],
+      "properties": {
+        "title": {
+          "type": "string",
+          "description": "Short title for the behaviour's agent application"
+        },
+        "workingStyle": {
+          "type": "string",
+          "description": "How the agent should apply this behaviour"
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/schema/json/capability.schema.json

@@ -0,0 +1,220 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schema.forwardimpact.team/json/capability.schema.json",
+  "title": "Capability",
+  "description": "Capability area that groups related skills with responsibilities and checklists",
+  "type": "object",
+  "required": ["name"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9_]*$",
+      "description": "Capability identifier (derived from filename if not specified)"
+    },
+    "name": {
+      "type": "string",
+      "description": "Human-readable capability name"
+    },
+    "emojiIcon": {
+      "type": "string",
+      "description": "Emoji for visual representation"
+    },
+    "displayOrder": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Order for display in UI"
+    },
+    "description": {
+      "type": "string",
+      "description": "Description of the capability area"
+    },
+    "professionalResponsibilities": {
+      "$ref": "#/$defs/responsibilitiesByLevel",
+      "description": "Responsibilities for professional/IC track by level"
+    },
+    "managementResponsibilities": {
+      "$ref": "#/$defs/responsibilitiesByLevel",
+      "description": "Responsibilities for management track by level"
+    },
+    "skills": {
+      "type": "array",
+      "description": "Skills within this capability",
+      "items": {
+        "$ref": "#/$defs/skill"
+      }
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "responsibilitiesByLevel": {
+      "type": "object",
+      "properties": {
+        "awareness": { "type": "string" },
+        "foundational": { "type": "string" },
+        "working": { "type": "string" },
+        "practitioner": { "type": "string" },
+        "expert": { "type": "string" }
+      },
+      "required": [
+        "awareness",
+        "foundational",
+        "working",
+        "practitioner",
+        "expert"
+      ],
+      "additionalProperties": false
+    },
+    "skill": {
+      "type": "object",
+      "required": ["id", "name", "human"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9_]*$",
+          "description": "Unique skill identifier (snake_case)"
+        },
+        "name": {
+          "type": "string",
+          "description": "Human-readable skill name"
+        },
+        "isHumanOnly": {
+          "type": "boolean",
+          "description": "If true, this skill is excluded from agent profiles"
+        },
+        "human": {
+          "$ref": "#/$defs/skillHumanSection",
+          "description": "Human-specific content for the skill"
+        },
+        "agent": {
+          "$ref": "#/$defs/skillAgentSection",
+          "description": "Agent-specific content for the skill"
+        },
+        "implementationReference": {
+          "type": "string",
+          "description": "Implementation patterns and code examples in markdown format (shared by human and agent)"
+        },
+        "toolReferences": {
+          "type": "array",
+          "description": "Recommended tools for this skill",
+          "items": { "$ref": "#/$defs/toolReference" }
+        }
+      },
+      "additionalProperties": false
+    },
+    "toolReference": {
+      "type": "object",
+      "required": ["name", "description", "useWhen"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Tool name"
+        },
+        "url": {
+          "type": "string",
+          "format": "uri",
+          "description": "Link to tool documentation"
+        },
+        "simpleIcon": {
+          "type": "string",
+          "pattern": "^[a-z0-9]+$",
+          "description": "Simple Icons slug for the tool icon (e.g., 'terraform', 'docker')"
+        },
+        "description": {
+          "type": "string",
+          "description": "What this tool does"
+        },
+        "useWhen": {
+          "type": "string",
+          "description": "When to use this tool"
+        }
+      },
+      "additionalProperties": false
+    },
+    "skillHumanSection": {
+      "type": "object",
+      "required": ["description", "levelDescriptions"],
+      "properties": {
+        "description": {
+          "type": "string",
+          "description": "Description of the skill"
+        },
+        "levelDescriptions": {
+          "$ref": "#/$defs/levelDescriptions",
+          "description": "Description of expectations at each level"
+        }
+      },
+      "additionalProperties": false
+    },
+    "levelDescriptions": {
+      "type": "object",
+      "properties": {
+        "awareness": { "type": "string" },
+        "foundational": { "type": "string" },
+        "working": { "type": "string" },
+        "practitioner": { "type": "string" },
+        "expert": { "type": "string" }
+      },
+      "required": [
+        "awareness",
+        "foundational",
+        "working",
+        "practitioner",
+        "expert"
+      ],
+      "additionalProperties": false
+    },
+    "skillAgentSection": {
+      "type": "object",
+      "required": ["name", "description", "useWhen", "stages"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]*$",
+          "description": "Agent skill name (kebab-case)"
+        },
+        "description": {
+          "type": "string",
+          "description": "Brief description of what this skill provides"
+        },
+        "useWhen": {
+          "type": "string",
+          "description": "Triggering conditions - when agents should use this skill"
+        },
+        "stages": {
+          "type": "object",
+          "description": "Stage-specific guidance for applying the skill",
+          "properties": {
+            "specify": { "$ref": "#/$defs/skillStage" },
+            "plan": { "$ref": "#/$defs/skillStage" },
+            "code": { "$ref": "#/$defs/skillStage" },
+            "review": { "$ref": "#/$defs/skillStage" },
+            "deploy": { "$ref": "#/$defs/skillStage" }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "skillStage": {
+      "type": "object",
+      "required": ["focus", "activities", "ready"],
+      "properties": {
+        "focus": {
+          "type": "string",
+          "description": "Primary focus for this stage"
+        },
+        "activities": {
+          "type": "array",
+          "description": "Key activities to perform in this stage",
+          "items": { "type": "string" }
+        },
+        "ready": {
+          "type": "array",
+          "description": "Criteria that indicate readiness to move to next stage",
+          "items": { "type": "string" }
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/schema/json/defs.schema.json

@@ -0,0 +1,132 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schema.forwardimpact.team/json/defs.schema.json",
+  "title": "Engineering Pathway Common Definitions",
+  "description": "Shared definitions for all pathway schemas",
+  "$defs": {
+    "skillLevel": {
+      "type": "string",
+      "enum": [
+        "awareness",
+        "foundational",
+        "working",
+        "practitioner",
+        "expert"
+      ],
+      "description": "Skill proficiency level from lowest to highest"
+    },
+    "behaviourMaturity": {
+      "type": "string",
+      "enum": [
+        "emerging",
+        "developing",
+        "practicing",
+        "role_modeling",
+        "exemplifying"
+      ],
+      "description": "Behaviour maturity level from lowest to highest"
+    },
+    "stageId": {
+      "type": "string",
+      "enum": ["plan", "code", "review"],
+      "description": "Lifecycle stage identifier"
+    },
+    "levelDescriptions": {
+      "type": "object",
+      "description": "Description of expectations at each skill level",
+      "properties": {
+        "awareness": { "type": "string" },
+        "foundational": { "type": "string" },
+        "working": { "type": "string" },
+        "practitioner": { "type": "string" },
+        "expert": { "type": "string" }
+      },
+      "required": [
+        "awareness",
+        "foundational",
+        "working",
+        "practitioner",
+        "expert"
+      ],
+      "additionalProperties": false
+    },
+    "maturityDescriptions": {
+      "type": "object",
+      "description": "Description of expectations at each behaviour maturity level",
+      "properties": {
+        "emerging": { "type": "string" },
+        "developing": { "type": "string" },
+        "practicing": { "type": "string" },
+        "role_modeling": { "type": "string" },
+        "exemplifying": { "type": "string" }
+      },
+      "required": [
+        "emerging",
+        "developing",
+        "practicing",
+        "role_modeling",
+        "exemplifying"
+      ],
+      "additionalProperties": false
+    },
+    "responsibilitiesByLevel": {
+      "type": "object",
+      "description": "Responsibility descriptions by skill level",
+      "properties": {
+        "awareness": { "type": "string" },
+        "foundational": { "type": "string" },
+        "working": { "type": "string" },
+        "practitioner": { "type": "string" },
+        "expert": { "type": "string" }
+      },
+      "required": [
+        "awareness",
+        "foundational",
+        "working",
+        "practitioner",
+        "expert"
+      ],
+      "additionalProperties": false
+    },
+    "skillId": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9_]*$",
+      "description": "Skill identifier (snake_case)"
+    },
+    "behaviourId": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9_]*$",
+      "description": "Behaviour identifier (snake_case)"
+    },
+    "capabilityId": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9_]*$",
+      "description": "Capability identifier (snake_case)"
+    },
+    "gradeId": {
+      "type": "string",
+      "pattern": "^[A-Z][A-Z0-9]*$",
+      "description": "Grade identifier (uppercase)"
+    },
+    "disciplineId": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9_]*$",
+      "description": "Discipline identifier (snake_case)"
+    },
+    "trackId": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9_]*$",
+      "description": "Track identifier (snake_case)"
+    },
+    "modifier": {
+      "type": "integer",
+      "description": "Modifier value for adjusting levels"
+    },
+    "normalizedModifier": {
+      "type": "integer",
+      "minimum": -1,
+      "maximum": 1,
+      "description": "Modifier value restricted to -1, 0, or 1"
+    }
+  }
+}

package/schema/json/discipline.schema.json

@@ -0,0 +1,132 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schema.forwardimpact.team/json/discipline.schema.json",
+  "title": "Discipline",
+  "description": "Engineering specialization that defines T-shaped skill profiles",
+  "type": "object",
+  "required": ["specialization", "roleTitle", "coreSkills", "validTracks"],
+  "properties": {
+    "specialization": {
+      "type": "string",
+      "description": "Name of the specialization (e.g., Software Engineering)"
+    },
+    "roleTitle": {
+      "type": "string",
+      "description": "Base role title (e.g., Software Engineer)"
+    },
+    "isProfessional": {
+      "type": "boolean",
+      "description": "If true, this is an IC/professional discipline (default true)"
+    },
+    "isManagement": {
+      "type": "boolean",
+      "description": "If true, this is a management discipline (default false)"
+    },
+    "validTracks": {
+      "type": "array",
+      "description": "REQUIRED. Explicit list of valid tracks. Use null to allow trackless (generalist). Empty array = no valid combinations.",
+      "items": {
+        "oneOf": [
+          { "type": "null" },
+          { "type": "string", "pattern": "^[a-z][a-z0-9_]*$" }
+        ]
+      }
+    },
+    "minGrade": {
+      "type": "string",
+      "description": "Minimum grade required for this discipline"
+    },
+    "description": {
+      "type": "string",
+      "description": "Description of the discipline's focus"
+    },
+    "coreSkills": {
+      "type": "array",
+      "description": "Primary skills for deep expertise (references skill IDs)",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z][a-z0-9_]*$"
+      }
+    },
+    "supportingSkills": {
+      "type": "array",
+      "description": "Secondary skills for supporting capabilities (references skill IDs)",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z][a-z0-9_]*$"
+      }
+    },
+    "broadSkills": {
+      "type": "array",
+      "description": "Skills for general awareness (references skill IDs)",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z][a-z0-9_]*$"
+      }
+    },
+    "behaviourModifiers": {
+      "type": "object",
+      "description": "Modifiers to behaviour expectations (behaviour ID → modifier)",
+      "additionalProperties": {
+        "type": "integer",
+        "minimum": -1,
+        "maximum": 1
+      }
+    },
+    "human": {
+      "$ref": "#/$defs/disciplineHumanSection",
+      "description": "Human-specific content"
+    },
+    "agent": {
+      "$ref": "#/$defs/disciplineAgentSection",
+      "description": "Agent-specific content"
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "disciplineHumanSection": {
+      "type": "object",
+      "properties": {
+        "professionalRoleSummary": {
+          "type": "string",
+          "description": "Role summary for professional/IC track. May use {roleTitle} placeholder."
+        },
+        "managementRoleSummary": {
+          "type": "string",
+          "description": "Role summary for management track. May use {specialization} placeholder."
+        }
+      },
+      "additionalProperties": false
+    },
+    "disciplineAgentSection": {
+      "type": "object",
+      "required": ["identity"],
+      "properties": {
+        "identity": {
+          "type": "string",
+          "description": "Core identity statement for the agent. May use {roleTitle} or {roleName} placeholder."
+        },
+        "priority": {
+          "type": "string",
+          "description": "Priority guidance for the agent"
+        },
+        "beforeMakingChanges": {
+          "type": "array",
+          "description": "Checklist items to consider before making changes",
+          "items": { "type": "string" }
+        },
+        "delegation": {
+          "type": "string",
+          "description": "Guidance on when and how to delegate to subagents"
+        },
+        "constraints": {
+          "type": "array",
+          "description": "Things the agent should avoid or never do",
+          "items": { "type": "string" }
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}