Moonwalk 2026

[earth2marsh]

Focus (and Help Wanted!)

Based on community discussions, this special interest group (SIG) will continue to explore concepts beyond OpenAPI v3. Sometimes this work may find its way into v3 releases, but it exists in part to consider what might be included in some future v4 major release where certain assumptions are revisited (e.g., multi-path segment support).

For 2026, we intend focus on how OpenAPI intersects with LLMs as a new class of smart clients for at least the first 6 months.

The SIG currently has only 1 organizer, which is a risk. Therefore, we are looking for 1-2 additional co-hosts to help facilitate and/or host sessions, etc. If you find this topic interesting and want to get involved, please reach out to @earth2marsh via the OAI Slack with any questions.

Strategic Focus: An LLM-Mediated API Landscape

As LLMs represent a new class of API client. When agents interact on behalf of users, how might we re-evaluate what is needed in an OpenAPI Document (OAD) to be more "agent-ready?"

Proposed Topics

Note: This draft is intended to promote discussion. The community is invited to discuss and refine these questions and topics.

1. Capability Discovery: Additional information to signal what a service can do, rather than just how to call an endpoint
2. Beyond the Technical Contract: Granting LLMs API access requires an understanding of what they will do on your behalf. This suggests a "social" or "intent" contract that agents and people can interpret and negotiate.
3. Workflow & Overlay Integration: How Arazzo (i.e., workflows) and Overlays might help identify and maintain LLM-based journeys

Open Questions for Discussion

In exploring the above topics, some prompting questions are proposed to orient upcoming sessions:

• Capability Surfacing: When technical details are delegated to an LLM or orchestration layer, what metadata is required in an OAD to effectively surface a "capability"?
• Sign-posting: How can we support combining of capabilities into non-linear user journeys (e.g., hypermedia-like use cases and potentially Arazzo-like workflows)?
• The Contract Shift: How should the "social contract" of an API be defined (e.g., access and credential scoping) versus the traditional technical contract?
• Organization: Can structured tags (i.e., tags and tag-kinds) be leveraged to logically group capabilities for agents?
• Intersections: How do Overlays (separating layers of responsibility) and Arazzo (workflows) intersect with agentic access?
• Optimization: Can a service's complete description be simplified or optimized specifically to support LLM-based journeys (e.g., an llms.txt equivalent for APIs or a narrower, task-specific description document)?
• Discovery: Where might discovery of capabilities (or even services) be in scope for OpenAPI?

Participation

Interested contributors are invited to join upcoming Moonwalk meetings or the #sig-moonwalk Slack channel.

[earth2marsh]

We discussed this today on the weekly call and agreed that we should keep improving this proposal and begin to assemble a glossary to help us align our language. Rather than jump into the definition phase, it seems appropriate to collect words that deserve to be included in the glossary, perhaps with links to existing definitions elsewhere (e.g., MCP, a kind of meta-glossary for now). For example, @handrews asked what was different about LLMs as a new kind of client, and we discussed how vibe-coded projects are distinct from agent-based interaction with services. One results in a deterministic integration while the other is oriented more toward natural language.

This seems like a good topic over the next few weeks as we ramp up.

[handrews]

Here are some interesting glossary pages, in no particular order.

I have not read all of these in details and I'm sure there's a lot of overlap, but as I skimmed pages from my initial search, these each jumped out due to either content or readability (this should not be considered an endorsement of any of the companies/product/people providing the lists):

• Nebuly Top 50 LLM Terms: I like that this one covers analytics, as they speak to goals users have that we might want to keep in mind.
• orq.ai LLM Glossary | AI & LLMOps Terminology Dictionary: This one has more technical detail, and I like its ops focus as again it speaks to what people will be trying to do while using LLMs and APIs.
• Swiss Cognitive LLM Terminology Cheat Sheet: This one gets even deeper into training approaches and mechanisms, where there might actually be APIs involved for communicating to LLMs.
• OWASP GenAI Security Project Glossary of Terms: This one is short, but I like that it talks about security. We probably need to go more in depth on LLM-related security concerns.

Some key thoughts just from skimming these:

• We need to remember that APIs might be something LLMs use, but also people use APIs to talk to LLMs
• We would do well to consider business and ops goals that are driving LLM usage
• We need to think about security implications with LLMs

[handrews]

This article, Stop Converting Your REST APIs to MCP (by the guy who build the FastMCP OpenAPI converter) has a lot of interesting thoughts.

The core concept is not surprising, and is the analogue of "stop piping your SQL schema directly through your HTTP API." Mapping API calls to tables works OK for very simple database schemas, but falls apart very quickly beyond that.

But there's some good concepts and terminology for us to start thinking about here:

• atomicity as an LLM anti-pattern: I understand this as not wanting your LLM interactions to be too fine-grained, which points towards Arazzo as being a better interface (not that the article mentions Arazzo)
• "context pollution" as a thing we should think about: Even well-designed APIs can be very "noisy" in terms of available options, and this apparently has specific sorts of costs for LLMs
• "curating" or "pruning", which reduces the context pollution. Incorporating the ability to do this as part of the OAS and/or Arazzo feels important. Overlays might also be a pruning mechanism at a mechanical level. Structured tags probably have potential here, too, although that requires developing conventions (or registered patterns if it fits in our registry)
• "Agent stories" sound like ways to focus Arazzo work on top of an OAD.

[handrews]

Some further thoughts:

• "few-shot learning" is really boosted by 3.2's dataValue and serializedValue Example Object fields
• We should be looking at how to support Retrieval Augmented Generation (RAG) use cases
• XML is used in prompting, but more in the sense of throwing tags into a block of text than well-formed XML documents. Perhaps we should register a media type for this, which we could model with the existing (as of 3.2) XML Object by allowing nodeType: text at the root. text/xml-text? This project (about which I know nothing beyond skimming the beginning of the README) appears to be about parsing the sort of XML-ish data used in LLMs.

[handrews]

One notable extension I've seen is an operation-level set of examples by programming language (or utility like curl). This could be standardized and further help LLMs understand how to write code for operations.