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?

[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.

[miqui]

@karenetheridge , @ralfhandl , @handrews - thoughts?

[miqui]

I think this way it would require a simple proposal.