File schema

A component does not embed the large artifacts it needs. Instead it declares them, and the platform provisions each File on the node before the component starts. The declaration is the contract a backend binds against: it names the slots a component fills, the type each slot accepts, and the config parameter that carries the resolved file into the component at runtime.

Declaring file dependencies

Input files are declared under worker.file_schema. Each entry is a named slot:

worker:
  file_schema:
    model:
      file_type: "weights"
      config_key: "model_path"
      is_optional: false
      tag: "detector"

The slot key (model here) is what a backend binds against — ppl backend add-file --key model. file_type gates which uploaded File is allowed in the slot: it is one value, or a |-separated list when the component genuinely reads several formats. The full vocabulary is in File types.

config_key is how the chosen File reaches the running component. The platform synthesises this parameter from the binding and writes it at deploy time, so it must not also appear under config_schema — declaring it twice is a duplicate-parameter error. What the value contains depends on the optional component target: with no target, the File loads into this component and the value is a component-local path like /files/model; with a target set (triton, torchserve, vllm, sglang), the File loads into that service and the value is the File's display name.

The remaining fields tune the slot: is_optional allows the slot to stay unbound, tag surfaces a slot id at binding time and narrows model-artifact candidates, and mutable allows the binding to change while the backend stays deployed.

Declaring files a component produces

A component that writes a File declares it under worker.generated_file_schema:

worker:
  generated_file_schema:
    report:
      name: "Evidence report"
      file_type: "pdf"
      config_key: "report_path"

Output declarations are simpler than inputs: name, a single file_type, and the config_key the component writes the path to. The | list form is not accepted here — an output is exactly one kind of File.

Related

• File types — every file_type value a slot can declare.
• File binding — upload a File and bind it to one of these slots.
• component.yml — the full contract this schema is part of.
• Models — model-artifact slots and the runtime that loads them.