feat: 2026-09-25 Formal submission of security profile proposal to SIG

[SensibleWood]

Summary

Adds proposals/2026-09-25-Security-Profiles.md, a proposal for decoupling security requirements from the core OpenAPI Specification so that complex, profile-based security models — starting with FAPI 2.0 and GNAP — can be described explicitly and deterministically, rather than approximated through today's Security Scheme / OAuth Flow objects.

The core problem: OAuth Flow Objects require a fixed, static metadata footprint (tokenUrl, authorizationUrl, etc.) that duplicates the real source of truth (OAuth Server Metadata / OIDC Discovery), risks drift, and has no room to express the additional constraints that profiles like FAPI 2.0 layer on top of plain OAuth 2.0.

Proposed approach

A three-layer model, each layer with a clear owner:

Layer	Purpose	Maintained by
OpenAPI Security Specification (OSS)	A separate, dedicated vocabulary of security primitives (JWT, MTLS, Credential, Access Request, Token, PAR, OAuth Profile, Discovery, etc.), each grounded in a specific RFC	Security SIG
Security Profile Framework	Additional constraints a specific profile (e.g. FAPI 2.0) layers on top of the OSS vocabulary	Security Profile working group
Ecosystem Registry	Jurisdiction/industry-specific tailoring of a Security Profile (e.g. UK/Brazil/KSA/UAE Open Banking variants of FAPI 2.0)	Ecosystem team

Highlights:

• A catalog of candidate OSS objects (Discovery, MTLS, JSON Web Token, Credential, Access Request, Token, Pushed Authorization Request, OAuth Profile), each with a worked YAML example.
• An implements property, used consistently across objects to point at the underlying RFC, BCP, or Security Profile an object instance conforms to — giving both humans and agentic tooling a deterministic hook back to the source of truth.
• A set of explicit design constraints (e.g. "JWTs are not just data," structured request/consent content is always by reference to a Schema Object, never embedded in the OSS or Security Profile layers).
• Worked alignment sections showing how the model maps onto FAPI 2.0 (via the Security Profile Framework) and GNAP (which, being a standalone protocol rather than an OAuth profile, is proposed to live largely in the OSS itself).

What feedback is most useful right now

• Does the OSS / Security Profile Framework / Ecosystem Registry split make sense, and is the "who maintains what" division right?
• Is the implements property the right mechanism for signaling RFC/profile compliance?
• Reactions to the specific object shapes (particularly Access Request vs. JSON Web Token overlap, and the still-open questions around GNAP's Discovery/Access Request split).
• Anything in the "Outstanding Design Considerations" table at the end of the proposal.

Checklist

• schema changes are included in this pull request
• schema changes are needed for this pull request but not done yet
• no schema changes are needed for this pull request

---

🤖 Generated with Claude Code

[SensibleWood]

@SensibleWood could you add a complete OAD example showing how this all fits together with real endpoints, and walk through how a tool is expected to process the instructions? Given that the focus is on giving tools enough information to perform the auth, I'd like to understand exactly how that works with a realistic OAD.

@handrews bringing this request over here from the informal review PR. I will act on it, but not today.