Bundle structure syntax
A component slot's file_type: is not only a flat enum like safetensors or json. It is a small structure with three forms: a leaf (one file of a type), a union a|b (one file matching any listed type), or a bundle bundle{ … } that describes a whole directory — a model repository with its config, weights, and tokenizer files. A bundle arrives as an archive (an uploaded or HTTP archive, or a git/HuggingFace snapshot) and is unpacked into the slot's directory at deploy.
Members
A bundle lists members written KEY QUANT?: TYPE:
- KEY is either a literal stem (a bare filename without its extension, like
config, which matchesconfig.<ext>for an extension the type allows) or a[glob]pattern over whole filenames (like[*.safetensors], which needs an explicit type). - TYPE is a leaf or a union of leaves — or, for a subdirectory, a nested
bundle{…}. - QUANT sets how many entries the key binds: none = exactly one,
?= optional,+= one or more,*= zero or more. Literal keys take none or?; pattern keys take?,+,*and default to*.
The important idea is that a literal member is keyed by stem, and the type decides the allowed extension: config: json matches config.json, while config: json|yaml matches config.json or config.yaml — the same logical file in either format. Writing config.json is sugar for config: json.
Open and closed
A bundle is closed by default — every file in the directory must be claimed by a member, like additionalProperties: false. A trailing .. opens it so extra files (READMEs, license files) are allowed; most real bundles end with , ...
Literal members bind first, then patterns claim the remaining files their glob and type match (first pattern wins; a glob hit whose type does not match is not an error, it simply falls through). A nested bundle{…} member describes a subdirectory and is validated recursively.
Examples
| Layout | file_type |
|---|---|
| HuggingFace transformers repo | bundle{ config: json, [*.safetensors]+: safetensors, .. } |
| Diffusers pipeline | bundle{ model_index: json, .. } |
| One or more ONNX graphs | bundle{ [*.onnx]+: onnx, .. } |
The component author declares the required layout on the slot; a linked File stores the layout its source actually delivers, and binds when its layout satisfies the slot's. The platform validates the bundle at link time against the source's file listing and again at deploy over the extracted bytes, with the same matcher.
The full grammar, the claiming rules, and the ppl file link --bundle syntax live in the CLI:
ppl docs get file-api/bundle-syntaxppl docs get file-api/file-typesppl docs get file-api/file-schemappl docs get concepts/models