Type catalog
TL;DR
- The type catalog is the registry of named types Pipelogic ships by default:
Image,AudioFrame,Tensor,BoundingBox,Polygon, and the rest of the domain vocabulary. - Catalog types are global: every workspace sees the same registry. Components reference them by name in
component.yml; the platform validates at wire time. - For ad-hoc shapes that do not justify a catalog entry, anonymous records on the wire (
{x: Double, y: Double}) work fine. The catalog is the shared vocabulary, not the only one. - The page you are reading is the mental model and category map. For the full per-type record schema, every variant, every wrapper class, fetch the reference from the CLI:
ppl docs get type-api/catalog.
Why a shared catalog
Two components from different teams agree on Image because the registry says exactly what Image is — a record with width, height, a color-space variant, and a pixel buffer. The producer encodes once, the consumer decodes once, and the type checker rejects any wire where the two ends disagree. Without the shared catalog, every team would invent their own Image record and the wiring would only work by accident.
Category map
The catalog clusters around the data shapes real AI products move:
| Category | Representative named types | Purpose |
|---|---|---|
| Imaging | Image, DepthImage | Frames at various bit-depths and color spaces. |
| Audio | AudioFrame | Sample-rate-tagged float audio. |
| Tensors | Tensor, Embedding, PointMap3D, MetricDepthMap, DensityMap, OpticalFlow | Shape-tagged N-D arrays; named aliases carry semantic meaning. |
| Geometry | Point, Rectangle, Ellipse, Polygon, BoundingBox, Landmark, Mask | 2-D / 3-D primitives composable with imaging types. |
| Detection | DetectedClass, BoundingBox, Landmark | Inference outputs that downstream consumers can chain on. |
| Domain | Audio subtitles, RAG records, mesh / 3-D, observation / metrics, … | Use-case-specific vocabularies the platform ships. |
Each category has its own internal layering — Image has color-space variants, Tensor has two scalar dtypes, DepthImage has three pixel-depth variants — but a component author only needs to know the names and the shapes the wrapper exposes.
Atomic vs composite vs named
- Atomic — built-in scalar types from the Pipelang grammar:
Int32,UInt32,Int64,UInt64,Float,Double,Bool,Char,String,Bytes. - Composite — built from anything via the grammar:
[T](list),(A, B)(tuple),{x: A, y: B}(record),A | B(union),Name<T>(generic). - Named — registered in the catalog.
Image,AudioFrame,BoundingBox, … are records or unions with a stable name that components can reference.
The catalog is the named layer. The grammar that lets you compose new types from atoms is documented separately: see /type-api/type-syntax.
Reaching for the right vocabulary
When writing a component:
- Use an atomic when the wire carries a scalar (
Doublefor a confidence threshold,Stringfor a label). - Use a named type when an obvious one exists for the domain (
Imagefor a frame,BoundingBoxfor a detection); the rest of the ecosystem will plug in automatically. - Use a composite of named types when the obvious one is a list, a tuple, or an optional (
[BoundingBox],(Image, String),Maybe<Tensor>). - Use an anonymous record (
{label: String, score: Double}) when the shape is one-off; if it shows up in three places, it earns a catalog entry.
Where this fits
Named types are the lingua franca of Pipelogic backends. Every component output you produce flows through one of these names; every input you accept is named the same way. The catalog is the reason two components written months apart by different authors compose without translation glue.
For the full reference
The website covers the model and the category map. For per-type record schemas, the full variant tables, JSON encoding details, and the Python and C++ wrapper APIs, fetch the reference from the CLI:
ppl docs get type-api/catalog
ppl docs get type-api/type-syntaxRelated
- /type-api/types — the type system as a platform concept.
- /type-api/named-types — when to extend the named catalog vs use an anonymous record.
- /type-api/type-syntax — the grammar.
- /component-api/component-contract — where you declare these types.