Proposal: Standardized operation intent/effects metadata for agent-ready OpenAPI

[shaalin]

I’m exploring a standardized way to attach machine-readable semantic intent metadata to OpenAPI operations.

The gap is that OpenAPI describes how to call an operation very well, but it does not provide a standard way to describe:

• the semantic class of the operation
• the side effects the operation may cause
• policy-relevant outcome or risk boundaries
• descriptive execution budgets or upper bounds

This matters for gateways, policy engines, and agentic or LLM-driven clients, where understanding what an operation means and what it can cause is as important as understanding the request/response shape.

As a concrete direction, I’m testing an incubating namespaced extension pattern using:

x-ibauth-intent

Minimal example:

paths:
  /payments:
    post:
      summary: Create payment
      x-ibauth-intent:
        ver: "1"
        operation_class: "payment.create"
        effects:
          - kind: mutate
            target: payment
          - kind: financial_transfer
            target: payments-rail
        budgets:
          risk_max: "high"
          cost_max: "medium"

This is not intended to replace OAuth, scopes, or existing security schemes. It is meant to complement them by making operation semantics visible in the OpenAPI description itself.

I have a working Docker-based demo and schemas behind this, and I’m looking for feedback on three things:

1. Does this problem belong in core OAS, a registry-backed convention, or just an extension pattern?
2. I looked for adjacent work in current OpenAPI mechanisms and did not find a standard model for operation intent/effects metadata. If there is already relevant OAI work in this area, I’d appreciate pointers so I can align with it.
3. Which parts seem standardizable:
   - operation semantic class
   - effects taxonomy
   - descriptive budgets
   - agent capability hints

[shaalin]

I also have:
- a runnable Docker demo
- a JSON Schema for the extension value
- a runtime grant schema used by a gateway/policy layer
- example annotated OpenAPI operations

Happy to share links and examples in follow-up comments if useful.

[ralfhandl]

This has some similarity with https://github.com/SAP/openapi-specification/tree/main/sap-schemas/v3.0#x-sap-operation-intent.

[shaalin]

@ralfhandl thanks, this is a very useful pointer. x-sap-operation-intent does look like real prior art in this area, and I agree there is meaningful overlap in spirit.

What I’m exploring, though, is a slightly different problem boundary. SAP’s extension seems to focus on normalized operation classification, which is already helpful and, in my view, strong evidence that operation-level semantic metadata is a real need.
The remaining gap I’m trying to test is whether classification alone is enough, or whether there is also value in a more structured way to describe semantics such as:

• expected side effects
• affected targets
• optional descriptive execution or risk hints

So I do see merit in this direction, and it may well inform the “minimal standardizable core.” My current thought is that a normalized operation classification model may be one important part of the answer, but it may not fully cover the broader semantics needed by gateways, policy engines, or agent/tooling.

[karenetheridge]

Could we use tags (and the tag registry) for this?

[handrews]

@karenetheridge good question! @shaalin if you are not familiar with 3.2 yet, the Tag Object got a big upgrade with the kind, parent, and summary fields.

(separately, why is the Tag Object in between the Header Object and the Reference Object instead of being up with the Info Object and other metadata Objects? meh).

[handrews]

Forgot to link to the tag kind registry

[shaalin]

@handrews and @karenetheridge thanks, this is a very helpful suggestion. I agree the OAS 3.2 Tag Object changes are relevant here, and I had not been thinking about that path carefully enough.

I can absolutely see Tags helping with part of the problem space, especially categorization, grouping, navigation, and perhaps some aspects of capability discovery.

Where I still see a gap is that categorization and semantics are not quite the same thing. Tags seem well suited to answering questions like “what bucket is this operation in?” but less suited to structured questions like:

• what kind of effect can this operation cause?
• what target does that effect apply to?
• are there optional execution or risk characteristics that other systems may want to consume?

So I think there is real merit in using Tags for the classification side of this, but I’m not yet convinced they fully cover the operation-semantics side. That may mean the right direction is narrower than my original post: use Tags where they fit, and only explore a separate structured mechanism for the semantics that go beyond categorization.

What do you folks think?

[lornajane]

I think if you can classify your endpoints into a small number of buckets, the tags are a very good way to do that and perhaps use in combination with an Overlay to apply the metadata for each endpoint according to its classification.

[miqui]

@shaalin > categorization and semantics are not quite the same thing

100% agree.

Your concern gave me the following idea.

Why not let you use extensions as you see fit (that is their goal), but perhaps we could introduce a feature whereby you can reference an extention (and its related attribs like in your example), like so

paths:
  /payments:
    post:
      summary: Create payment
      extentions:
         $ref: "#/components/extentions/ibauth"
 
 
 
 components:
   extentions:
       ibauth:
        ver: "1"
        operation_class: "payment.create"
        effects:
          - kind: mutate
            target: payment
          - kind: financial_transfer
            target: payments-rail
        budgets:
          risk_max: "high"
          cost_max: "medium"

This way you can keep your OADs DRY and enjoy the semantics you need.

Another way would be to well..... implement this using overlays which is slighy more complicated, but still doable.

[shaalin]

@miqui thanks for your suggestions, I have some thoughts. I will wait for others (who you have tagged) to reply and then share my thoughts.

[lornajane]

@miqui this is an interesting one, and I had a similar suggestion for grouping some of the sunset/deprecation headers into a "scheme" that could be applied as a ready-made set of metadata to an operation.

[shaalin]

@miqui thanks, this is helpful. I think Overlay/reuse is a separate representation concern from the main question I’m trying to test here.

My hesitation with Overlay as the primary answer is that it seems better suited to layering or transforming descriptions for different consumers or contexts, whereas the semantics I’m talking about are intrinsic to the operation itself and should not vary based on who is looking at the OAD.

This discussion has also pushed me to tighten the naming. I started with x-ibauth-intent, then moved toward x-ibauth-semantics, and I’m now rethinking the provisional name because the scope here seems broader than authorization and closer to general operation semantics.

I also think reuse/application mechanisms are a separate follow-on concern. For this thread, I’m mainly trying to validate the need for the semantic layer itself before getting into how it might be applied or deduplicated across an OAD.
One reason I’m cautious about optimizing for DRY too early is that semantic blocks may share a shape without being truly repetitive in meaning. For example:

/payments:
  post:
    x-...-semantics:
      operation_class: payment.create
      effects:
        - kind: mutate
          target: payment
        - kind: financial_transfer
          target: payments-rail

/payments/{id}/cancel:
  post:
    x-...-semantics:
      operation_class: payment.cancel
      effects:
        - kind: mutate
          target: payment
        - kind: reversal
          target: payments-rail

/payments/{id}:
  get:
    x-...-semantics:
      operation_class: payment.read
      effects:
        - kind: read
          target: payment

These operations have a similar structure, but the semantic differences are exactly the important part. Inlining keeps those differences visible. A DRY mechanism may help later, but it seems secondary to first establishing whether this kind of structured operation semantics is useful at all.

[miqui]

@shaalin - sure make sense. Although what I am suggesting is no different from when we ref examples today.

[shaalin]

@miqui I am just curious, trying to understand your last comment. Are you saying $ref is a good option even though DRY might not necessarily be the concern to solve?

is the purpose of $ref to keep the higher level API readable and organized?

[lornajane]

I'd recommend starting with an extension pattern, it's a great way to explore something new, and from what I've seen so far, these fields aren't an industry-wide standard between agents yet. Once those conventions are in place then we can get the extensions into the registry and spread the word!

[shaalin]

@lornajane thanks, this is helpful. I agree that starting with an extension pattern is the right place to begin.

One clarification that may help: the proposal is not to standardize agent behavior. It is to give APIs a structured way to publish semantics that machines can consume.

In that sense, agents, gateways, and other tooling are consumers of the metadata, not the authority that defines it. The API description remains the source of truth.

I also do not think this requires a universal cross-industry vocabulary on day one. What may be worth standardizing first is the shape of the metadata, while allowing some semantic values to remain team-, domain-, or organization-specific until stronger conventions emerge.

[miqui]

One clarification that may help: the proposal is not to standardize agent behavior. It is to give APIs a structured way to publish semantics that machines can consume.

In that sense, agents, gateways, and other tooling are consumers of the metadata, not the authority that defines it. The API description remains the source of truth.

I agree here with @shaalin because this is YOUR use case for YOUR context to be understood and/or contextualized for YOUR agentic workloads.

As for gateways, obviously not standard so, if I would setup an agent that would process our context given the extentions and let it configure whatever gateway we are using (If and only if the gateway has the APIs to let the agent do this)

[miqui]

I also do not think this requires a universal cross-industry vocabulary on day one. What may be worth standardizing first is the shape of the metadata, while allowing some semantic values to remain team-, domain-, or organization-specific until stronger conventions emerge

100%. As you can already see, you can use the custom extensions for whatever your use case may be. It is your custom agentic standard at your company.