@swagger-api/apidom-parser-adapter-a2a-yaml-1

@swagger-api/apidom-parser-adapter-a2a-yaml-1 is a parser adapter for A2A (Agent-to-Agent) Protocol v1.0 AgentCard documents in YAML format. Under the hood this adapter uses apidom-parser-adapter-yaml-1-2 to parse a source string into generic ApiDOM in base ApiDOM namespace which is then refracted with A2A 1.x.y Refractors.

Installation

After prerequisites for installing this package are satisfied, you can install it via npm CLI by running the following command:

 $ npm install @swagger-api/apidom-parser-adapter-a2a-yaml-1

Parser adapter API

This parser adapter is fully compatible with parser adapter interface required by @swagger-api/apidom-parser and implements all required properties.

mediaTypes

Defines list of media types that this parser adapter recognizes.

[
  'application/vnd.a2a;version=1.0.0',
  'application/vnd.a2a+yaml;version=1.0.0',
]

detect

A2A AgentCard documents have no version discriminator field (unlike OpenAPI's "openapi": "3.1.0" or Arazzo's "arazzo": "1.0.1"). Detection is therefore structural: a YAML document is treated as an A2A AgentCard when it parses as YAML and contains both a capabilities mapping and a skills sequence. False positives are possible — set the mediaType on the File explicitly when the type is known.

namespace

This adapter exposes an instance of A2A 1.x.y ApiDOM namespace.

parse

parse function consumes various options as a second argument. Here is a list of these options:

Option | Type | Default | Description --- | --- | --- | --- specObj | Object | Specification Object | This specification object drives the YAML AST transformation to A2A 1.x.y ApiDOM namespace. sourceMap | Boolean | false | Indicate whether to generate source maps. refractorOpts | Object | {} | Refractor options are passed to refractors during refracting phase.

All unrecognized arbitrary options will be ignored.

Usage

This parser adapter can be used directly or indirectly via @swagger-api/apidom-parser.

Direct usage

During direct usage you don't need to provide mediaType as the parse function is already pre-bound with supported media types.

import { parse, detect } from '@swagger-api/apidom-parser-adapter-a2a-yaml-1';

// detecting
await detect('capabilities:\n  streaming: true\nskills: []'); // => true
await detect('test'); // => false

// parsing
const parseResult = await parse('capabilities:\n  streaming: true\nskills: []', { sourceMap: true });

Indirect usage

You can omit the mediaType option here, but please read Word on detect vs mediaTypes before you do so.

import ApiDOMParser from '@swagger-api/apidom-parser';
import * as a2aYamlAdapter from '@swagger-api/apidom-parser-adapter-a2a-yaml-1';

const parser = new ApiDOMParser();

parser.use(a2aYamlAdapter);

const parseResult = await parser.parse(yamlSource, { mediaType: a2aYamlAdapter.mediaTypes.latest('yaml') });

License

Apache-2.0