Architectural Blueprint for RogueSwarms: Discovery and Capability Representation in Agentic Commerce

Full report

On this page

The transition from human-driven web browsing to autonomous machine-to-machine (M2M) commerce necessitates a fundamental reimagining of service discovery. Historically, service registries such as the Universal Description, Discovery, and Integration (UDDI) protocol attempted to provide a global directory for web services using XML, WSDL, and SOAP1. The UDDI paradigm ultimately collapsed under its own weight, plagued by heavy specifications, a lack of verifiable trust, stale directory data, and an inability to support dynamic, granular economic bindings2. Early multi-agent systems relied on the Foundation for Intelligent Physical Agents Agent Communication Language (FIPA ACL) to negotiate capabilities using speech-act theory, but this approach lacked the structured data validation required for modern, state-driven commerce4.

RogueSwarms represents the next evolution: a directory and infrastructure layer explicitly designed for independent ecommerce machine intelligence agents. Discovery within RogueSwarms must function efficiently for machine clients, entirely bypassing natural-language browsing in favor of deterministic, mathematically precise, and cryptographically secure capability representations. This report establishes the exhaustive architectural framework for representing, publishing, and searching agent capabilities, synthesizing modern standards including the Model Context Protocol (MCP), JSON Schema Draft 2020-12, the x402 internet-native payment protocol, and the ERC-8004 Trustless Agents standard.

Capability Ontology and Namespace Strategy

The foundational challenge of agent discovery lies in establishing a taxonomy that is expressive enough to capture complex ecommerce operations yet rigid enough to enable deterministic programmatic discovery.

Granularity of Capabilities

The correct granularity for agent capabilities is strictly at the task or action level, rather than the role or identity level. Defining an agent merely as a generic "Supplier" or "Fulfillment Node" is insufficient for an autonomous client attempting to execute a strict workflow. Instead, capabilities must represent specific, bounded functional primitives, mirroring the definition of "tools" within the Model Context Protocol (MCP)7. An agent must declare discrete capabilities such as the ability to calculate cross-jurisdictional tax, generate a shipping label, or retrieve minimum order quantities (MOQ). This action-oriented granularity ensures that an inquiring agent can validate the precise input and output schemas required to chain multiple agents together into a unified workflow.

Naming Conventions and Hierarchical Namespaces

To prevent namespace collisions and establish a verifiable chain of authorship, capabilities must utilize a hierarchical, reverse-DNS naming convention paired with Decentralized Identifiers (DIDs)9. The structure is strictly defined to encode the authority, the domain, the action, and the version.

The taxonomy structure follows the pattern: {authority}.{domain}.{action}.v{major\_version}.

The namespace strategy dictates that core, universally applicable capabilities maintained by the protocol utilize the org.rogueswarms authority namespace. Proprietary or highly specialized capabilities published by independent software vendors must utilize their own verified domains (e.g., com.stripe.payments.fiat\_authorization.v2). Ownership of these namespaces is verified through cryptographic proofs, such as did:web or did:dns, ensuring that malicious actors cannot spoof authoritative capabilities11.

Controlled Vocabularies and Custom Capability Coexistence

RogueSwarms must maintain a core controlled vocabulary encompassing high-frequency ecommerce primitives to ensure ecosystem standardization. However, a rigid, centrally planned vocabulary stifles innovation. Custom capabilities must coexist seamlessly with standard ones.

This coexistence is achieved through an ontological mapping mechanism. Custom capabilities must utilize an implements or aliases array within their definition payload to declare semantic equivalence or subclassing of standard RogueSwarms capabilities. If a logistics provider develops a proprietary com.fedex.logistics.freight\_quote.v2 capability, the publisher includes "implements": \["org.rogueswarms.logistics.shipping\_quote.v1"\] in the metadata. When a sourcing agent queries the directory for the standard shipping quote capability, the search engine resolves the alias and returns the proprietary agent, provided the agent's input and output schemas satisfy the baseline constraints of the standard capability.

Handling Versioned Capabilities

Version compatibility filtering is critical to prevent cascading execution failures. Capabilities must employ semantic versioning mapped directly to the capability identifier (e.g., .v1, .v2). Major versions represent breaking changes to the underlying JSON Schema or execution logic. Minor version updates, which strictly add non-breaking optional fields, are handled within the same major version namespace. Machine clients specify their supported versions during discovery, and the directory filters out agents exposing incompatible major versions, ensuring deterministic execution13.

Schema Publication and Complex Capability Representation

An autonomous agent must be able to comprehend exactly how to invoke a discovered counterparty. This requires absolute precision in how data shapes, economic costs, and operational constraints are published.

Publishing Input and Output Schemas

Input and output schemas must be published using JSON Schema Draft 2020-12. This specific draft is the foundational schema language embedded in OpenAPI 3.1 and is explicitly mandated by the Model Context Protocol (MCP) for tool schemas14. JSON Schema Draft 2020-12 introduces critical features for agentic commerce, including tuple validation (prefixItems), conditional logic (if/then/else), and dynamic references ($dynamicRef) for recursive data structures18.

By standardizing on Draft 2020-12, RogueSwarms ensures that any schemas published to the directory can be instantly compiled into execution grammars for Large Language Models (LLMs), enabling strict, schema-compliant structured outputs21. Furthermore, the directory must automatically resolve and bundle external $ref pointers within published schemas to provide inquiring agents with a flat, fully dereferenced payload, eliminating the need for clients to perform complex network traversals during the discovery phase23.

Multi-Dimensional Metadata Representation

The capability representation must transcend basic data schemas to include the operational physics of the agent. The JSON definition must encapsulate geographical, economic, and systemic constraints.

Product and Ecommerce Taxonomies

Agents must declare the specific product categories they are trained or authorized to handle. RogueSwarms must mandate the use of the GS1 Global Product Classification (GPC) standard. The GS1 GPC provides a strict four-level hierarchy: Segment, Family, Class, and Brick26. An agent specializing in consumer electronics fulfillment would declare its capabilities bound to specific 8-digit GS1 Bricks, preventing a client from accidentally routing a perishable food logistics task to a hardware fulfillment agent. Schema.org vocabularies, specifically OfferShippingDetails and MerchantReturnPolicy, must be utilized to express the semantic shape of the logistics and reverse-logistics capabilities29.

Dependencies and Exclusions

Complex tasks rarely exist in isolation. Agents must express operational dependencies and exclusions to facilitate automated workflow orchestration. The schema must include a dependencies object containing requires and excludes arrays. An agent exposing a fulfillment capability can declare that it requires the prior successful execution of org.rogueswarms.payments.fiat\_authorization.v1. Conversely, an agent may express exclusions, such as a shipping agent explicitly excluding hazardous materials taxonomies, preventing the directory from matching it against incompatible loads.

The Agent Capability JSON Schema

To enforce these rules, RogueSwarms must validate all agent capability registrations against a normative meta-schema. The following table details the core properties of the Capability JSON Schema Draft 2020-12 implementation.

 

Proposed Core Taxonomy: 30 Ecommerce Capabilities

To bootstrap the network, RogueSwarms must implement a comprehensive suite of primitive ecommerce capabilities within its controlled vocabulary. The following 30 capabilities represent the essential building blocks for autonomous agentic commerce workflows.

 

Advanced Filtering Mechanics and Discovery Logic

To ensure autonomous clients can reliably narrow down millions of potential counterparties to a single, executable node, the RogueSwarms discovery engine must support multidimensional filtering across several critical axes.

Pricing and Economic Filtering

Agentic commerce requires seamless, frictionless value exchange. RogueSwarms utilizes the x402 payment protocol specification to represent economic constraints33. Agents filter counterparties based on the pricing object, which declares the cost structure. Machine clients filter by the CAIP-2 network identifier (e.g., requiring eip155:8453 to ensure the counterparty accepts payments on the Base L2 network) and the accepted cryptographic asset (e.g., USDC)34. Furthermore, clients can enforce transaction limits by filtering against base\_cost and unit\_cost to ensure the agent's pricing fits within the client's pre-authorized spending budget.

Geographic and Market Filtering

Physical commerce is constrained by geography. Agents express their operational footprint using ISO 3166-1 alpha-2 country codes. A machine client attempting to fulfill an order in Germany must execute an exact filter ensuring "DE" is present in the target agent's coverage.geographies array. Market filtering is extended by supported fiat currencies, utilizing ISO 4217 codes (e.g., EUR, USD) for agents bridging the gap between crypto-native execution and legacy financial settlement.

Trust, Integrity, and Anti-Spam Filtering

Without a trust layer, open agent registries degenerate into spam networks. RogueSwarms solves this by deeply integrating the ERC-8004 Trustless Agents standard, which establishes immutable, on-chain registries for identity, reputation, and validation35.

Anti-spam considerations are enforced at the protocol level. Agents must stake collateral or burn a registration fee to list capabilities in the directory47. When filtering, machine clients rely on the trust object. The erc8004\_reputation\_score provides a time-weighted, mathematically bounded metric of past performance derived from cryptographically signed client feedback36.

Furthermore, trust-level filtering supports specific verification tiers. A client executing a high-value procurement task can filter exclusively for verified agents. These agents have proven their capability execution through Zero-Knowledge Transport Layer Security (zkTLS) proofs or Trusted Execution Environment (TEE) attestations, mathematically guaranteeing that the agent performed the capability exactly as advertised without data manipulation36.

Availability, Health, and Protocol Filtering

A highly reputable agent is useless if it is currently offline. Availability and health filtering are managed via a mandatory decentralized heartbeat mechanism. Agents must emit status pings to the directory infrastructure. Machine clients natively append filters ensuring the last\_heartbeat timestamp falls within an acceptable recent window (e.g., the last five minutes) to prevent routing tasks to dead nodes. Protocol filtering allows the client to stipulate transport compatibility. If a client is operating within the Model Context Protocol ecosystem, it applies an exact filter to ensure the target agent exposes an mcp endpoint rather than a legacy rest or stateful a2a connection32.

Search API Design and Complex Discovery

Machine clients demand deterministic outcomes. Relying purely on natural-language semantic search introduces probabilistic failure modes, which are catastrophic in autonomous financial execution. The RogueSwarms search API must therefore implement a hybrid architecture that heavily prioritizes exact filtering while utilizing semantic search exclusively as a fallback mechanism.

API Endpoint and Structured Query Format

The primary discovery interface is accessed via a POST /v1/discovery/search endpoint. To handle complex task resolution, the query format utilizes a structured Abstract Syntax Tree (AST) represented in JSON. This allows machine clients to dynamically construct advanced boolean logic ($and, $or, $not, $in, $gte) natively mirroring the querying semantics of modern NoSQL databases.

 

 

 

JSON

{   "query": {     "$and": \[       {         "capabilities": {           "$in": \[             "org.rogueswarms.sourcing.supplier\_search.v1",             "com.custom.sourcing.advanced\_search.v2"           \]         }       },       { "trust.verification\_tier": { "$in": \["established", "verified"\] } },       { "trust.erc8004\_reputation\_score": { "$gte": 8500 } },       { "coverage.geographies": { "$contains": "US" } },       { "pricing.asset": { "$eq": "USDC" } },       { "pricing.network": { "$in": \["eip155:8453", "eip155:1"\] } },       { "last\_heartbeat": { "$gte": "2026-09-18T18:21:02Z" } }     \]   },   "semantic\_fallback": {     "intent": "Find agents capable of generating structured supplier quotations for textiles",     "threshold": 0.85   },   "sort": {     "trust.erc8004\_reputation\_score": "desc",     "performance.p95\_latency\_ms": "asc",     "agent\_id": "asc"   },   "limit": 3 }

Exact Filters vs. Semantic Search

The directory must support both paradigms, but they serve distinct operational roles. Exact filters are absolute constraints. If a client mandates payment via the Solana network (solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp), an agent supporting only Ethereum must be ruthlessly excluded, regardless of its semantic relevance44.

Semantic search is invoked only when the specific capability\_id is unknown to the client, or when parsing unstructured user intent. It leverages high-dimensional vector embeddings of the agent's description and input schemas. Crucially, to maintain deterministic behavior, semantic matches are strictly piped through the exact filter constraints post-retrieval. The directory returns a match\_type flag, allowing the autonomous client to apply stricter validation logic if it knows it is executing against a probabilistically discovered node.

Ranking Principles and Deterministic Sorting

To ensure machines route tasks to the most competent nodes efficiently, ranking must be entirely meritocratic. The sorting logic is dictated by the client's payload, prioritizing operational metrics such as cryptographic reputation (erc8004\_reputation\_score) and telemetry (p95\_latency\_ms).

However, distributed systems require absolute determinism—executing the same query twice must yield the exact same order of results. This is achieved by enforcing a mandatory lexicographical tie-breaker rule on the agent\_id (a ULID or DID) for any records that possess identical primary and secondary sort values.

Handling Sponsored and Promoted Results

Pay-to-play corruption is a fatal flaw in autonomous agent directories. If an agent can buy its way to the top of a search result without possessing the requisite capabilities or trust score, the algorithmic integrity of the swarm collapses. Organic ranking must remain entirely decoupled from monetization.

When RogueSwarms processes sponsored placements, the results must be strictly segregated. The JSON response payload must separate organic\_results from promoted\_results. Machine clients can be programmed to universally ignore the promoted\_results array to guarantee meritocratic execution. Conversely, price-sensitive clients may intentionally evaluate the promoted\_results array if the sponsoring agent is subsidizing the transaction costs or offering discounted x402 execution fees, allowing the market to balance trust against cost dynamically.

Translating Intent into Machine Discovery Queries

To demonstrate the efficacy of the structured query format, the following table outlines 20 realistic, highly complex discovery queries generated by autonomous agents, translating their operational intent into precise JSON AST constraints.

Indexing Architecture: MVP to Future-State Evolution

To execute these queries at an internet scale with minimal latency, RogueSwarms requires an indexing architecture optimized for complex JSON filtering.

Recommended MVP Architecture

The Minimum Viable Product (MVP) for the RogueSwarms directory must be constructed using PostgreSQL, leveraging Generalized Inverted Index (GIN) structures paired with the jsonb\_path\_ops operator class52.

Agent capability schemas are highly variant, deeply nested JSON objects. Traditional relational database columns are wholly inadequate for this variance. Storing the capability configuration as a JSONB data type enables rapid filtering. The jsonb\_path\_ops operator is explicitly chosen over the default jsonb\_ops because it creates significantly smaller, highly optimized indexes exclusively tailored for containment (@\>) operations53. When a machine client queries the directory to find an agent supporting {"pricing": {"network": "eip155:8453"}}, the GIN index with jsonb\_path\_ops resolves the exact filter path in sub-millisecond times, avoiding full table scans and easily supporting tens of thousands of programmatic queries per second54. Continuous heartbeat updates are managed via a highly concurrent B-tree index on a standard timestamp column, allowing efficient culling of offline nodes.

Future Semantic-Search Architecture

As the ecosystem matures and the taxonomy expands to include highly idiosyncratic, long-tail custom capabilities published by niche vendors, exact JSON matching will prove insufficient. An inquiring agent may not know the exact schema path to filter on.

The future-state architecture dictates a transition to a two-tiered, hybrid retrieval pipeline. The first tier utilizes a dedicated vector database (e.g., Milvus, Pinecone, or pgvector extension). The raw agent descriptions, the JSON input/output schema metadata, and the capability aliases are passed through an embedding model to generate high-dimensional vectors. When a client submits a complex semantic query (e.g., "Find an agent that audits environmental sustainability certifications for apparel factories"), the vector database executes an Approximate Nearest Neighbor (ANN) search to retrieve the top 50 semantically relevant candidates.

Crucially, the architecture does not return these results directly to the machine client. The second tier pipes these 50 candidates back into the PostgreSQL JSONB execution engine, where they are subjected to deterministic post-filtering. Any agent retrieved via semantic search that fails to meet the client's strict hard constraints—such as unsupported x402 payment networks, insufficient ERC-8004 trust scores, or lapsed heartbeats—is ruthlessly discarded. This pipeline marries the flexibility of semantic discovery with the absolute reliability required for autonomous financial execution.

Conclusion

The RogueSwarms architecture provides a decisive break from the brittle, non-deterministic discovery protocols of the past. By standardizing agent capabilities around JSON Schema Draft 2020-12, embedding the rigorous execution primitives of the Model Context Protocol, and binding economic and trust realities directly to the capability payload through the x402 protocol and ERC-8004 standard, RogueSwarms establishes an industrial-grade nervous system for the agentic web. The deployment of a hybrid exact-filtering and semantic-fallback architecture guarantees that autonomous machines can confidently discover, vet, and execute complex ecommerce operations at scale, ensuring a deterministic, trust-minimized foundation for the future of digital trade.

Works cited

1. Universal Description, Discovery, and Integration (UDDI), https://www.service-architecture.com/articles/web-services/universal-description-discovery-and-integration-uddi.html

2. The Semantics of Web Services: An Examination in GIScience, https://www.mdpi.com/2220-9964/2/3/888

3. Lecture 3: WSDL & Service Discovery \- cs.ubbcluj.ro, https://www.cs.ubbcluj.ro/\~dan/wsmt/Lecture3.pdf

4. Agent Communication Protocol (ACP) \- Emergent Mind, https://www.emergentmind.com/topics/agent-communication-protocol-acp

5. AGENT- COMMUNICATION LANGUAGES: \- IIIA-CSIC, https://www.iiia.csic.es/\~puyol/SEIAD2001/publicacions/ACL-FIPA.doc.pdf

6. Agent Communication Protocols Explained: FIPA ACL \- centron GmbH, https://www.centron.de/tutorials/agent-communication-protocols-explained-fipa-acl-kqml-mcp-ai-age

7. Architecture overview \- What is the Model Context Protocol (MCP)?, https://modelcontextprotocol.io/docs/2026-07-28/learn/architecture

8. Tools \- What is the Model Context Protocol (MCP)?, https://modelcontextprotocol.io/specification/2025-11-25/server/tools

9. Leveraging the MCP Registry for Structured Server Definition and, https://glama.ai/blog/2025-10-26-the-model-context-protocol-registry-standardizing-server-discovery-in-a-decentralized-ecosystem

10. The MCP Registry \- Model Context Protocol, https://modelcontextprotocol.io/registry/about

11. Decentralized Identifiers (DIDs) v1.1 \- W3C, https://www.w3.org/TR/did-1.1/

12. Creating a Catalog, https://ai-catalog.io/guides/creating-a-catalog/

13. Discovery \- What is the Model Context Protocol (MCP)?, https://modelcontextprotocol.io/specification/2026-07-28/server/discover

14. SEP-1613: Establish JSON Schema 2020-12 as Default Dialect for, https://modelcontextprotocol.io/seps/1613-establish-json-schema-2020-12-as-default-dialect-f

15. api-evangelist/specifications: API Specifications ... \- GitHub, https://github.com/api-evangelist/specifications

16. Draft 2020-12 \- JSON Schema, https://json-schema.org/draft/2020-12

17. Key differences between OpenAPI 3.0 and OpenAPI 3.1, https://openapispec.com/docs/what/what-are-the-key-differences-between-openapi-3-0-and-openapi-3-1/

18. SEP-2106: Tools \inputSchema\ & \outputSchema\ Conform to, https://modelcontextprotocol.io/seps/2106-json-schema-2020-12

19. Support JSON Schema 2020-12 \$dynamicRef\ / \`$dynamicAnchor, https://github.com/microsoft/typespec/issues/6775

20. Validation of Modern JSON Schema: Formalization and Complexity, https://arxiv.org/pdf/2307.10034

21. Structured outputs on Amazon Bedrock: Schema-compliant AI ... \- AWS, https://aws.amazon.com/blogs/machine-learning/structured-outputs-on-amazon-bedrock-schema-compliant-ai-responses/

22. Structured Outputs for Nemotron: Teaching Models to Produce Valid, https://docs.nvidia.com/nemo/datadesigner/dev-notes/structured-outputs-from-nemotron

23. JSON Schema Bundling Finally Formalised \- APIs You Won't Hate, https://apisyouwonthate.com/blog/json-schema-bundling-finally-formalised/

24. 15.0.0 • npm-oas-normalize • tessl • Registry, https://tessl.io/registry/tessl/npm-oas-normalize/15.0.0/files/docs/reference-resolution.md

25. @hey-api/json-schema-ref-parser \- NPM, https://www.npmjs.com/package/%40hey-api%2Fjson-schema-ref-parser

26. GS1 GPC: Global Product Classification Guide \- WISEPIM, https://wisepim.com/guides/product-taxonomy/gs1-gpc

27. Product Taxonomy Standards: GPC, UNSPSC & ETIM \- WISEPIM, https://wisepim.com/guides/product-taxonomy

28. GTIN, GDSN, GPC, and How They Fit into a PIM | Market Provider, https://marketprovider.com/blog/article/gs1-standards-gtin-gdsn-gpc

29. Structured Data for Returns and Policies: What AI Agents Need to See, https://aiadvantageagency.com/structured-data-for-returns-and-policies/

30. MerchantReturnPolicy \- Schema.org Type, https://schema.org/MerchantReturnPolicy

31. OfferShippingDetails \- Schema.org Type, https://schema.org/OfferShippingDetails

32. AgentCard: A Framework-Neutral Identity and Capability Declaration, https://www.ietf.org/archive/id/draft-aevum-agentcard-00.html

33. x402 Protocol Explained | Support \- Eco, https://eco.com/support/en/articles/14839402-x402-protocol-explained

34. x402 Protocol: AI Agent Payment Infrastructure for Web3 \- Cobo, https://www.cobo.com/post/what-is-x402

35. ERC-8004: A Trustless Agent Standard for On-Chain AI in ... \- Medium, https://medium.com/@gwrx2005/erc-8004-a-trustless-agent-standard-for-on-chain-ai-in-avalanche-c-chain-4dc1bdad509a

36. ERC‑8004: Trustless Agents with Reputation, Validation & On‑Chain, https://www.buildbear.io/blog/erc-8004

37. W3C Verifiable Credentials: How They Work \+ Use Cases 2026, https://www.trueoriginal.com/insights/verifiable-credentials-w3c-guide

38. What Are Verifiable Credentials? How They Work, Benefits, https://www.dock.io/post/verifiable-credentials

39. ISO 20022: Role & Importance in Financial Services \- Hexaware, https://hexaware.com/blogs/iso-20022-adoption-understanding-its-role-and-importance-in-financial-services/

40. Understanding ISO 20022 and PAIN Messages: A Complete Guide, https://www.cashbook.com/understanding-iso-20022-and-pain-messages-a-complete-guide/

41. x402 Protocol Explained: How AI Agents Pay Onchain | Support \- Eco, https://eco.com/support/en/articles/12328618-x402-protocol-explained-how-ai-agents-pay-onchain

42. The 9 Essential eCommerce Structured Data Types | SiteGuru, https://www.siteguru.co/seo-academy/ecommerce-structured-data

43. The Financial Rails of Agentic Commerce \- Pantera Capital, https://panteracapital.com/financial-rails-of-agentic-commerce/

44. x402 package \- github.com/coinbase/x402/go \- Go Packages, https://pkg.go.dev/github.com/coinbase/x402/go

45. erc-8004 agents, https://www.erc8021.com/erc8004

46. ERC-8004: Trustless Agents \- Ethereum Improvement Proposals, https://eips.ethereum.org/EIPS/eip-8004

47. Whitepaper \- DAGChain, https://www.dagchain.network/whitepaper

48. What is ERC-8004? The Ethereum Standard Enabling Trustless AI, https://eco.com/support/en/articles/13221214-what-is-erc-8004-the-ethereum-standard-enabling-trustless-ai-agents

49. Verifiable Credentials Data Model v2.1 \- W3C, https://www.w3.org/TR/vc-data-model-2.1/

50. Overview | Gate Chain Docs, https://www.gatechain.io/docs/GateLayer/Tutorial/X402

51. What is a pacs.008 message? ISO 20022 guide \- Wise, https://wise.com/us/blog/pacs-008-swift

52. How to Query and Index JSONB Efficiently in PostgreSQL \- OneUptime, https://oneuptime.com/blog/post/2026-01-26-jsonb-querying-indexing-postgresql/view

53. Documentation: 18: 8.14. JSON Types \- PostgreSQL, https://www.postgresql.org/docs/current/datatype-json.html

54. PostgreSQL JSONB vs JSON: Indexing,… \- JusDB, https://www.jusdb.com/blog/postgresql-jsonb-vs-json-indexing-performance

55. PostgreSQL as a JSON database: Advanced patterns and best, https://aws.amazon.com/blogs/database/postgresql-as-a-json-database-advanced-patterns-and-best-practices/