Ikanos — Schema — Consumes¶

The consumes array declares the external sources the capability uses internally. Each entry is currently an HTTP adapter (type: http).

capability:
  consumes:
    - namespace: registry
      type: http
      baseUri: "https://api.example.com/v1"
      authentication: {...}
      resources: { ... }

Consumes Object — fixed fields¶

Field	Type	Required	Description
`namespace`	`string`	✅	Unique identifier used for routing from `exposes` to this source
`type`	`string`	✅	Currently always `"http"`
`baseUri`	`string`	✅	Base URI for all resources under this adapter
`authentication`	`Authentication`		Bearer, API key, Basic, Digest, or OAuth 2.1
`inputParameters`	`map<string, InputParameter>`		Adapter-level parameters (typically headers like `Registry-Version`) injected on every request — keyed by parameter name
`resources`	`map<string, ConsumedResource>`		Endpoint groupings under this base URI — keyed by resource name

Rules¶

namespace MUST be unique across all consumes (and exposes, and binds) entries.
baseUri SHOULD NOT have a trailing slash (enforced by polychro:governance).
Additional properties are not allowed.

Authentication¶

authentication:
  type: bearer        # bearer | apiKey | basic | digest | oauth2
  token: "REGISTRY_TOKEN"

`type`	Required fields
`bearer`	`token` (bind reference or literal)
`apiKey`	`name`, `in: header\|query`, `value`
`basic`	`username`, `password`
`digest`	`username`, `password`
`oauth2`	`tokenUrl`, `clientId`, `clientSecret`, `scopes[]`

Secrets are usually bind references — uppercase identifiers like REGISTRY_TOKEN that resolve through a binds block.

ConsumedResource¶

resources:                              # keyed map; key IS the resource name
  ship:
    display: "Ship by IMO"
    path: "/ships/"
    operations: { ... }

Field	Type	Required	Description
(map key)	`string`	✅	Technical name, used as part of `call:` refs
`path`	`string`	✅	Path relative to `baseUri`, with `` placeholders
`display`	`string`		Human-readable name
`description`	`string`		Improves agent discoverability
`operations`	`map<string, ConsumedOperation>`	✅	At least one HTTP operation — keyed by operation name

ConsumedOperation¶

operations:                             # keyed map; key IS the operation name
  get-ship:
    method: GET
    inputParameters:                    # keyed map
      imo_number: { in: path, required: true }
      format:     { in: query, required: false }
    outputParameters:
      - { name: vessel_name, type: string, value: "$.vessel_name" }
      - { name: dimensions,  type: object, value: "$.dimensions" }

Field	Type	Description
(map key)	`string`	Unique within the resource — combined as `{namespace}.{operationId}`
`method`	`string`	`GET`, `POST`, `PUT`, `PATCH`, `DELETE`
`inputParameters`	`map<string, InputParameter>`	Path, query, header, cookie, or body parameters
`outputParameters`	`MappedOutputParameter[]`	Typed extraction via JSONPath `value:`
`outputRawFormat`	`string`	Interpret the response entity as a raw format instead of JSON: `xml`, `yaml`, `toml`, `ini`, … or `binary` (new in Beta 1 — see Binary responses)
`outputMediaType`	`string`	Pin the contract media type for downstream exposures, overriding the upstream `Content-Type` (e.g. `image/jpeg`, `application/vnd.github.v3+json`)
`maxBinarySize`	`string`	Hard cap on buffered binary size; grammar `^\d+(\.\d+)?(B\\|KiB\\|MiB\\|GiB)?$`, default `10MiB`
`body`	`RequestBody`	For mutating verbs

Input parameters¶

inputParameters:                        # keyed map; key IS the parameter name
  imo_number:
    in: path          # path | query | header | cookie | body
    required: true
    type: string      # string | number | integer | boolean | object | array
    description: "International Maritime Organization number"
    pattern: "^IMO-\\d+$"

in: path placeholders MUST match ` in the resource path (where the key isname`).
in: query parameters are appended automatically.
in: header parameters are injected per-request.
in: body is mutually exclusive with the body field — use one or the other.

Output parameters (JSONPath mapping)¶

outputParameters:
  - name: userId
    type: string
    value: $.id                       # top-level field
  - name: email
    type: string
    value: $.contact.email            # nested
  - name: allNames
    type: array
    value: $.users[*].name            # extract all .name values

Common JSONPath patterns:

Pattern	Returns
`$.field`	A field
`$.users[0].name`	The first user's name
`$.users[*].name`	An array of all user names
`$.a.b.c`	A deeply nested field

Binary responses¶

New in Beta 1

Declarative binary response handling on consumed HTTP operations is available starting with Ikanos 1.0.0-beta1. Earlier releases decoded every response entity as UTF-8 text, which corrupted images, audio, PDFs, and other binary payloads at the source.

Set outputRawFormat: binary on a consumed HTTP operation to tell the engine not to decode the entity as text. The raw bytes are buffered as-is and the original Content-Type is propagated, so the payload can flow byte-faithfully through aggregate flows and out through any REST or MCP exposure.

consumes:
  photoLibrary:
    type: http
    baseUri: "https://photos.example.com/v1"
    resources:
      photo:
        path: "/photos//binary"
        operations:
          download-photo:
            method: GET
            outputRawFormat: binary       # do not UTF-8 decode the response
            outputMediaType: image/jpeg   # pin the contract media type
            maxBinarySize: 5MiB           # hard cap; default is 10MiB

Rules¶

Binary detection is declarative, never heuristic — the engine does not sniff response bodies. An operation must opt in explicitly.
outputParameters are skipped on a binary operation (JSONPath mapping over raw bytes is meaningless); the engine logs this at INFO.
outputMediaType is a declaration, not a transform — the engine never re-encodes the bytes. Labeling a PNG as image/jpeg yields a mislabeled (but byte-intact) payload, which is treated as a spec bug.
maxBinarySize is a hard cap. A response larger than the limit fails with a clear error rather than truncating or exhausting memory. The default is 10 MiB; it can be set per operation or on the adapter.
outputMediaType is not binary-specific — it also pins vendor JSON variants (application/hal+json, application/problem+json) and text subtypes (text/csv, text/markdown) for text/JSON responses.

Format conversion¶

Non-JSON payloads are normalized to JSON before mapping. Declare the inbound format on the operation with the produces field on the consumed adapter:

- type: http
  namespace: legacy
  baseUri: "https://legacy.example.com"
  produces: application/xml          # XML, Avro, CSV, TSV, PSV, HTML, Markdown
  resources: { ... }

The engine selects the corresponding format adapter automatically. Supported inbound formats include JSON, XML, Avro, Protobuf, CSV, TSV, PSV, HTML, Markdown, and YAML.