AI Contributions

[duncanbeevers]

AI-assisted and AI-initiated contributions are becoming increasingly prevalent across the Open Source world.
I haven't seen any official guidance within this project around expectations for this flavor of contribution, and thought it might be prudent to get out ahead of the deluge.

In particular, I would like to provide clear guidance for contributors regarding:

• Are AI-assisted contributions welcome, and if so, how, and to whom are they attributed?
• Are AI-initiated contributions welcome, and if so, how, and to whom, are they attributed?
• Are there guidelines around how AI agents present and conduct themselves?
  • How does the Code-of-Conduct apply to AI agents?
  • Are AI agents expected to identify themselves as such?
  • Are AI agents expected to indicate to whom they are beholden? Are driverless contributions accepted?

Some starting guidelines I'd personally like to see:

• AI agents should not use human or near-human avatars
• AI agents should not use false information in their bios
• AI agents should indicate their nature in their PR descriptions
• AI agents should indicate who are their operators.
• AI-submitted PRs should not be merged until their operators have been explicitly-engaged, and both operators and repository owners have indicated they understand the agentic nature of the contribution.

[jmertic]

There is an existing LF policy that OpenAPI should leverage, and can build upon if needed....

https://www.linuxfoundation.org/legal/generative-ai

[karenetheridge]

FWIW, I have recently added this boilerplate to READMEs of open source work that are primarily written/maintained by me:

I will not accept AI-generated or AI-assisted contributions unless the nature of the AI assistance is clearly identified with the pull request. Ignoring this request will result in a ban of future contributions to any of my work.

i.e. you can still use AI, but I require full disclosure.

[miqui]

This is a great note @karenetheridge

[lornajane]

I think we're taking about two things here. One is an AI-assisted review and update of the spec, yes let's do that but perhaps in another thread? The other is a general AI policy which looking at my other notifications we may already be late with .

I'm hugely in favour of AI assisted human contributions and reviews, but I would like to have guardrails about disclosure and I expect the humans to be knowledgeable and responsive to follow-ups. I'm not super keen on AI-originated work but perhaps I just haven't seen good contributions from that approach yet.

We do already have some minimum account age settings in our repositories which I hope will also help with drive-by inputs from either species.

Do we have consensus about the sort of guardrails we'd like in place?

[handrews]

Created #5221 for using LLMs on 3.2.1. I'll hide my comments here to discourage further replies in this thread.

[miqui]

my 2 cents

The OpenAPI Overlay Specification aims to provide a "standardized way to apply targeted modifications to an existing OpenAPI document without directly editing the source document. " (was this not the original goal????) Think of it as a patch or transformation layer that sits on top of a base OpenAPI spec.

The core (IMHO) goals are:

Separation of concerns — Keep the source (often auto-generated) OpenAPI document pristine while layering on additional or corrected metadata separately. This is especially useful when the base spec is generated from code annotations and you don't want to pollute the source with documentation-only concerns.

Reusability — A single overlay can be applied to multiple versions of a spec, or multiple overlays can be composed together (e.g., one for documentation enrichment, one for gateway-specific extensions, one for audience-specific views).

Non-destructive workflows — Teams that generate specs from code (e.g., using frameworks like Gin, FastAPI, or Postman's own tooling) often can't easily add rich descriptions, examples, or x- extensions at the source level. Overlays let technical writers, API governance teams, or tooling pipelines augment the spec downstream.

Targeted transformations — Using JSONPath-based targeting, an overlay can surgically add, replace, or remove fields on specific operations, parameters, schemas, etc., rather than requiring a full spec fork right?????

[miqui]

Sorry, I hope I am not stating the obvious, but felt the need to circle back to why we have the spec in the first place.