c0de.it/docs/rack-planner/plugin-spec.md

Plugin Specification

Goal

The plugin system should allow additional rack components to be imported without changing application code.

Plugins should be data packages, not executable extensions.

Principles

• no arbitrary code execution
• manifest-based validation
• stable schema versioning
• internal conversion of optional CAD-derived assets

Package structure

Example:

vendor-pack-1/
  manifest.json
  components/
    switch-24p.json
    patchpanel-24p.json
  assets/
    front/
      switch-24p.svg
      patchpanel-24p.svg
    preview3d/
      switch-24p.gltf

Manifest example

{
  "manifestVersion": 1,
  "name": "Example Network Pack",
  "vendor": "Example Vendor",
  "version": "1.0.0",
  "components": [
    "components/switch-24p.json",
    "components/patchpanel-24p.json"
  ]
}

Component definition example

{
  "name": "24-Port Patch Panel",
  "manufacturer": "Example Vendor",
  "partNumber": "PP-24-1U",
  "category": "patch_panel",
  "rackStandard": "19_inch",
  "heightU": 1,
  "depthMm": 95,
  "weightKg": 1.2,
  "priceNet": 79.0,
  "currency": "EUR",
  "assets": {
    "frontSvg": "assets/front/patchpanel-24p.svg"
  },
  "ports": [
    {
      "name": "Port 1",
      "side": "front",
      "offsetXmm": 18,
      "offsetYmm": 10,
      "offsetZmm": 0,
      "portType": "rj45"
    }
  ]
}

Supported file formats

V1 mandatory

• JSON for manifest and component metadata
• SVG for 2D visuals

V1 optional

• glTF for future 3D preview assets

Later import formats

These should be handled through an import pipeline, not as runtime-native editor formats:

• DXF
• STEP
• OBJ

Validation rules

• schema version must be supported
• required metadata fields must exist
• asset references must resolve inside the package
• all dimensions must be plausible and positive
• category values must match allowed enums
• unsupported formats are rejected or ignored

Security model

Plugins must never contain executable JavaScript for the editor.

Allowed plugin content:

• metadata
• images
• vector graphics
• optional validated model assets

Rejected:

• scripts
• external network callbacks
• embedded active content

Import workflow

1. upload package
2. unpack in isolated temporary storage
3. validate manifest
4. validate component schema
5. validate assets
6. register catalog entries
7. make components available to selected users or globally

Versioning strategy

• application schema versioning is independent from plugin pack version
• manifest schema must be explicitly versioned
• deprecated fields should have a migration path where possible