Proposal for OpenAPI Extension: x-sensitive-data

[cristigirbovan]

1. Summary
   This proposal introduces a standardized way to define sensitive data fields in OpenAPI specifications using the x-sensitive-data extension. By integrating this directly into API contracts, we enable automatic data masking, hashing, and redaction across various API tools, including logging systems, API gateways, and security scanners.

2. Problem Statement
   Currently, OpenAPI lacks a standard way to identify and handle sensitive fields such as passwords, personal identifiable information (PII), or financial data. API providers must manually implement security policies, leading to inconsistencies and potential security gaps. This proposal addresses:

• Automated masking for sensitive request/response data
• Standardized compliance with regulations (GDPR, HIPAA, PCI-DSS)
• Security enhancement by reducing accidental data leaks in logs
• Developer-friendly API design with built-in security metadata

3. Proposed Solution: x-sensitive-data Extension
   We introduce x-sensitive-data as an optional extension for OpenAPI Schema Objects. This extension allows defining sensitive fields, specifying masking strategies, and enabling annotation-based processing where applicable.

3.1 Example OpenAPI Usage

openapi: 3.1.0
info:
  title: User API
  version: 1.0.0
paths:
  /users:
    post:
      summary: Create a new user
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '200':
          description: Successfully created user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        username:
          type: string
        password:
          type: string
          x-sensitive-data: 
            mask: full
        email:
          type: string
          x-sensitive-data:
            mask: regex
            pattern: "^[^@]+"
        ssn:
          type: string
          x-sensitive-data:
            mask: hash
            algorithm: sha256

4. Features and Benefits

4.1 Masking Strategies - examples
Strategy Description

• full -> Replace entire value with ***
• regex -> Mask specific parts using regex pattern
• hash -> Hash value (e.g., SHA-256)
• remove -> Remove field completely from logs

4.2 How It Works in API Tools

• API Gateways: Enforce automatic masking before responses are sent.
• Logging Systems: Automatically obfuscate sensitive fields.
• Security Scanners: Detect misconfigured APIs exposing sensitive data.
• Validation Tools: Ensure compliance with security policies.

5. Optional Integration: Annotations for Code-Level Mapping
   For languages like Java, TypeScript, and Python, we propose introducing standardized annotations that can be mapped to OpenAPI x-sensitive-data fields. Example:

@MaskSensitive
public class User {
    private String username;

    @SensitiveData(strategy = MaskStrategy.FULL)
    private String password;

    @SensitiveData(strategy = MaskStrategy.HASH, algorithm = "SHA-256")
    private String ssn;
}

E.g. annotations are automatically generated from OpenAPI definitions:
- @MaskSensitive (class-level) → indicates that some fields in the class should be masked based on their @SensitiveData annotations;
- @SensitiveData (field-level) → specifies which fields are sensitive and how they should be masked.

Frameworks (Spring, FastAPI, Express) can use these annotations to automatically generate OpenAPI definitions with x-sensitive-data fields.

[mikekistler]

This seems reasonable to me. As proposed, I don't think this would be documented in the OpenAPI spec but rather in the OAI extensions registry.