Wrapped Source

A Wrapped Source is an outside source an API Product wraps, declared as one descriptor: its operations, Offer, meters, limits, tenancy and error map.

Parts

Field	Type	Required	What it is
`slug`	`string`	required	The source id, unique among sources.
`title`	`string`		The display name of the source.
`description`	`string`		What the source holds, in one line.
`origin`	`string`		The base URL every request goes to.
`transport`	`Transport`		How requests reach the upstream.
`auth`	`Auth`		How the source authenticates to the upstream.
`resources`	`Record<string, Resource>`		The operations of the upstream, by resource, each a list or a detail lookup.
`cache`	`CachePolicy`		The cache policy of every operation.
`retry`	`Retry`		The retry policy of every operation.
`transform`	`TransformStep[]`		The steps that shape each record, as data: `select`, `coerce`, `derive`, `validate` or `module`.
`composition`	`Composition`		How several steps combine: chain, parallel, race, hedge, merge or fallback.
`schedule`	`Schedule`		The jobs the source runs on a clock.
`offer`	`Offer`		The pricing document of the source: free or metered, checked fail-closed.
`scopes`	`Scope[]`		The scopes a caller can hold, each named.
`meters`	`Meter[]`		What the source counts: each meter with its name and unit.
`rateLimit`	`RateLimit`		A window and the most calls it allows.
`spendCeiling`	`SpendCeiling`		A ceiling on total spend, separate from the rate limit.
`tenancy`	`Tenancy`		Who owns the listing, whether it is house or third-party, and its mint.
`errorVocabulary`	`Record<string, Outcome>`		Maps each upstream error onto `OK`, `EMPTY`, `BLOCKED`, `NOT_FOUND` or `UPSTREAM`.
`discovery`	`Discovery`		The home of the source, its llms.txt and its examples.
`generatedBy`	`GeneratedBy`		On a descriptor a family expands: the family, catalog row, snapshot date and license.

Checks

A descriptor names its source by a slug.
A descriptor holds only the members its grammar defines, and any other member is refused.
A house listing carries a mint, and a third-party upstream never does.
An Offer declares its model, free or metered; free is never silent.
A metered Offer declares a hard ceiling above 0.
A metered Offer names the channel that answers a call over its ceiling.
A metered Offer names where it is paid for.
No field links the rate limit to the spend ceiling, so paying never lifts a rate limit.

Example

tidecharts.example: the descriptor

slug: tidecharts
title: Tidecharts
description: Tide predictions for coastal stations, wrapped from one public upstream.
origin: https://tides.example/api
resources:
  stations:
    list:
      path: /stations
      method: GET
    detail:
      path: /stations/{id}/predictions
      method: GET
      idQuery: id
offer:
  model: metered
  hardCeiling: 50
  overCeiling:
    channel: email
  monetization:
    surface: pricing
meters:
  - name: predictions
    unit: per-request
rateLimit:
  window: 1m
  max: 600
spendCeiling:
  ceiling: 50
tenancy:
  owner: tidecharts.example
  visibility: house
  mint:
    brand: Tidecharts
errorVocabulary:
  "404": NOT_FOUND
  "429": BLOCKED
  "503": UPSTREAM
discovery:
  home: https://tidecharts.example
  llmsTxt: /llms.txt

PartsCopy Anchor Link

ChecksCopy Anchor Link

ExampleCopy Anchor Link

Parts

Checks

Example