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/{{imo_number}}"
    operations: { ... }

Field	Type	Required	Description
(map key)	`string`	✅	Technical name, used as part of `call:` refs
`path`	`string`	✅	Path relative to `baseUri`, with `{{var}}` 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:`
`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 {{name}} in the resource path (where the key is name).
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

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.