Profile schema

Source: docs/11-profiles-and-reports.md

1. Profile schema (v1)

A profile is a small JSON document of the factual limits a toolpath is checked against plus the import defaults needed to lift slicer G-code. version MUST be 1. Unknown keys are ignored (forward-compatibility). Several fields accept deserialization aliases (kept for ergonomics); the schema validates the canonical names.

Section	Field (canonical)	Type	Aliases	Notes
—	version	1	—	profile schema version
—	name	string	—	human-readable, for reports
firmware	flavor	string	—	marlin / klipper / duet
machine	build_volume	[[x_lo,x_hi],[y_lo,y_hi],[z_lo,z_hi]] mm	bounds
machine	feedrate_range	[min,max] mm/min	speed_range	extruding moves
machine	kinematics.max_acceleration_mm_s2	mm/s² > 0	—	drives the balanced arc centripetal limit
machine	kinematics.max_junction_velocity_mm_s	mm/s > 0	—	caps the balanced per-junction feedrate
material	filament_diameter	mm > 0	—
material	max_volumetric_flow_mm3_s	mm³/s > 0	max_flow, max_volumetric_flow
material	min_nozzle_temperature_c	°C > 0	min_temp, min_nozzle_temp	cold-extrusion guard
process	line_width	mm > 0	—	import/review default
process	layer_height	mm > 0	—	import/review default
process	monotonic_z	bool	—	require non-decreasing Z
process	max_retraction_distance	mm > 0	—
process	max_retraction_speed	mm/min > 0	—
process	max_travel_without_retraction	mm > 0	—
process	first_layer_height_range	[min,max] mm ≥ 0	—
process	first_layer_speed_range	[min,max] mm/min ≥ 0	—
—	start_gcode / end_gcode	string | [string]	—	a multi-line string or a list of command lines

Validation rules (enforced by Profile::validate): version == 1; every range has lo ≤ hi; positive fields are finite and > 0; range fields are finite with a non-negative lower bound; when present, both machine.kinematics fields are finite and > 0. A profile maps to verifier contracts (§2), import params, resolve params and emit params.

machine.kinematics is a small, optional, firmware-agnostic motion model: a max acceleration and a max junction / square-corner velocity. It has two optional numeric fields:

• max_acceleration_mm_s2 — the toolhead's maximum acceleration in mm/s². When set, the peak-acceleration verifier rule (§2) flags arcs whose centripetal acceleration v²/r exceeds this value, and the balanced rewrite mode (§3.4) caps arc speed to respect it.
• max_junction_velocity_mm_s — the maximum velocity change allowed at a sharp junction (a per-junction feedrate cap), in mm/s. When set, the junction-velocity verifier rule (§2, warning severity) fires on contiguous printing segments with a velocity change Δv exceeding this value, and balanced mode (§3.4) limits per-junction speed to respect it. This rule is an advisory approximation of cornering — a flat Δv-vs-limit check, not a reproduction of firmware junction kinematics (Klipper's square-corner-velocity feeds a junction-deviation formula that permits larger Δv on shallow corners), so on real slicer g-code it may warn on corners the printer handles fine. It is a Warning, never a gate. (The peak-acceleration rule, by contrast, evaluates every arc — including travel arcs — against the acceleration limit.)

Kinematic limits feed the balanced optimisation pipeline but are not enforced by the core verifier (they are gated in the rewrite process). Pressure-advance and input-shaper models are deliberately out of scope for v1.

Versioning: profile version is independent of the IR schema version. Additive optional fields are a minor change; removing/renaming/retyping a field or changing a default is a major change (a new version).