odp-directory
Canonical directory client for the Offering Discovery Protocol.
This crate owns fixed production and sandbox Directory access, validated Service search results, facets, suggestions, and opaque continuation traversal. Its asynchronous client provides a Rustls-backed HTTP transport and permits callers to inject a compatible transport.
Use Environment::Production for https://directory.offeringprotocol.org or Environment::Sandbox for
https://sandbox.inflowpay.ai. These are the only Directory origins accepted by the client.
use ;
use ;
#
# async
search_services returns one native ODP Service-only response. continue_search_services follows one opaque
next reference. collect_services performs bounded Service-only traversal, stopping at the
response or item limit without fetching another response.
Search filters cover keywords, ODP operations, enrollment protocols, payment protocols, payment
options, trust protocols, and the authentication requirements attached to operations and payments.
Search responses can also carry facets for building data-driven filters without packaging the
Directory's current vocabulary into the Agent.
Each returned Service preserves its enrollment, payment, and trust protocol advertisements.
Unrecognized protocol descriptors are filtered while recognized descriptors remain strictly
validated.
See the workspace guide and the ODP specification.
Search Services and Collections
use ;
#
# async
ResourceSearchRequest.types can restrict results to ResultType::Service or
ResultType::Collection. None selects both; explicit lists must be nonempty and distinct.
Filters apply to the owning Service. An empty query is omitted, allowing browsing.
Collection identity is its owning service.service_id plus its case-sensitive Collection ID.
Several OpenAPI documents can share an API origin without being the same Directory Service.
The result's indexed_at describes the Collection's freshness; service.indexed_at describes
the parent's freshness. Both are timestamp strings. service.service_id identifies the
Directory's Service record. Service results may include optional publisher attribution with publisher_id, name,
and website_url. The website is a display link, not a discovery or execution target.
Omitted or null publisher attribution is accepted, and additional fields are preserved;
Collection attribution is the owning service itself.
For service.source.source_type == "odp", inspect the owning Service's live ODP document, then
use the Agent client's get_collection to retrieve current details. An OpenAPI Collection is a
Directory presentation group, not an ODP operation target. Directory metadata is not authority to execute an Action or send
credentials. Unknown future result types retain their full raw JSON and are not interpreted as
Services. Malformed known results become indexed issues without discarding valid results.
Additional fields are retained in additional maps.
Mixed results use DirectoryIndexedService, separate from the native DirectoryService returned
by search_services. Each mixed Service requires service_id, service_origin, name,
indexed_at and source. Imported descriptions and languages are optional; missing lists become
empty vectors. Imported results do not expose native ODP operations. Native results retain ODP
validation. Unverified execution fields such as http and payment_origins are not returned.
DirectorySource describes the document used for discovery:
source_typeis"odp","openapi", or an unknown future string. Unknown formats remain readable but must not be passed to ODP operations.urlis the exact document URL, including path and query. It may differ from the API origin; do not reconstruct it fromservice_origin.x402_discoveryrecords supporting fixed-path x402 discovery, not proof that an endpoint accepts payments. Advertised evidence remains inprotocols.
The client does not fetch or execute OpenAPI documents.
Filter by source
use ;
#
# async
sources: None omits the filter. An explicit list must contain one or both distinct
SourceType::Odp and SourceType::Openapi values. Sources are alternatives, combined with other
filter categories using AND; Collections inherit the owning Service's source. Native
search_services accepts the filter but remains ODP-only, so an OpenAPI-only filter yields no
native matches. Unsupported source filter values are rejected during deserialization.
Mixed search bounds and suggestions
Mixed search returns at most 100 results. limit: 0 omits the limit, using the server's default
of 100. The server does not currently offer continuation: absent next does not mean every match
was returned. continue_search accepts an opaque same-origin continuation if one is supplied.
Each call returns one response. Facets count all matching targets, not just returned items;
a Service and two Collections count as three. Collection search does not depend on permission
to display its card on the Directory landing page.
suggest sends POST /v1/directory/suggestions. SuggestionRequest.filters accepts the same
ServiceFilters as search, including AEP, keywords, ODP operations, payments, sources and trust.
Collection filters apply to their owning Service. Matching spans names, descriptions and keywords,
but output contains deduplicated names of matching Services and Collections. Despite the
argument name prefix, matching uses substrings and whitespace-separated alternative terms.
suggest_services uses GET /v1/services/suggestions for Service-only keyword-prefix suggestions
and does not accept filters.
Both return strings from the server's items array; the default and maximum limit are 25.
See the canonical Directory example.
Migration
-
Mixed result
servicefields useDirectoryIndexedService; its requiredservice_idis a field rather than an optional accessor. Native Service-only models are unchanged. -
Explicit
ServiceFiltersliterals includesources: Noneor..Default::default(). -
Known mixed results require
sourcemetadata from the Directory. Missing sources are reported as item issues, not assumed to be ODP. -
Service-only
searchcalls becomesearch_services;continue_searchcalls becomecontinue_search_services. -
Aggregating
search_services(request, options)calls becomecollect_services(request, options). -
search_pagesis removed. To retain individual responses, callsearch_servicesfollowed bycontinue_search_serviceswith an explicit application limit. -
Service-only
suggestcalls becomesuggest_services. -
search,continue_search, andsuggestselect mixed discovery.