Skip to content

PATH-MAPPING.md

Latest commit

 

History

History
129 lines (97 loc) · 3.55 KB

PATH-MAPPING.md

File metadata and controls

129 lines (97 loc) · 3.55 KB

Path Mapping and .prism.json

KiCAD Prism supports both convention-based repository layouts and explicit path configuration.

Why .prism.json Exists

Without explicit config, the backend has to inspect the repository and infer where files live. That works for common layouts, but it is slower and less predictable on unusual repos or monorepos.

A complete .prism.json gives you:

  • deterministic file resolution
  • less path auto-detection work
  • clearer project metadata
  • fewer surprises when importing or syncing repositories

Resolution Order

Current path resolution follows this order:

  1. explicit .prism.json
  2. auto-detection for missing fields
  3. fallback legacy defaults where applicable

A key current behavior is that explicit fields are honored first, and only missing fields are auto-detected.

Supported Fields

Top-level metadata:

  • project_name
  • description
  • workflows

Path fields:

  • schematic
  • pcb
  • subsheets
  • designOutputs
  • manufacturingOutputs
  • documentation
  • thumbnail
  • readme
  • jobset

Example

{
  "project_name": "Flight Controller Rev B",
  "description": "Main avionics control board.",
  "paths": {
    "schematic": "hardware/fc.kicad_sch",
    "pcb": "hardware/fc.kicad_pcb",
    "subsheets": "hardware/subsheets",
    "designOutputs": "outputs/design",
    "manufacturingOutputs": "outputs/manufacturing",
    "documentation": "docs",
    "thumbnail": "assets/thumbnail",
    "readme": "README.md",
    "jobset": "Outputs.kicad_jobset"
  }
}

API Endpoints

Get effective config

GET /api/projects/{project_id}/config

Returns:

  • config: effective path and metadata config
  • resolved: resolved absolute paths
  • source: explicit or auto-detected

Preview auto-detection

POST /api/projects/{project_id}/detect-paths

Returns a detected config plus validation without writing .prism.json.

Save config

PUT /api/projects/{project_id}/config
Content-Type: application/json

{
  "project_name": "Flight Controller Rev B",
  "description": "Main avionics control board.",
  "schematic": "hardware/fc.kicad_sch",
  "pcb": "hardware/fc.kicad_pcb",
  "documentation": "docs"
}

Saving config writes .prism.json in the project root.

Auto-Detection Heuristics

If you do not provide a .prism.json, KiCAD Prism looks for common patterns such as:

  • root .kicad_sch and .kicad_pcb files
  • common docs folders like docs, documentation, wiki
  • common output folders like Design-Outputs, Manufacturing-Outputs, outputs, exports
  • common thumbnail/image directories under assets, images, or renders
  • README-like files such as README* or OVERVIEW*

Recommendations

  • use explicit config for monorepos or non-standard layouts
  • set readme and documentation explicitly if your documentation is not under README.md and docs/
  • keep output directories stable across workflow runs
  • store project metadata and path mapping together in .prism.json

Validation and Troubleshooting

If a file is not showing up where expected:

  1. call GET /api/projects/{project_id}/config
  2. inspect resolved paths
  3. run POST /api/projects/{project_id}/detect-paths to compare inferred values
  4. save an explicit .prism.json if the repo layout is unusual

For schematic and PCB fields, glob-like values are supported where the backend expects them, but explicit file paths are usually the least ambiguous option.

Related Docs