From 7d091be641120e036bd7f837566e2328e8230143 Mon Sep 17 00:00:00 2001
From: Ashish Raj <ashishraj09@gmail.com>
Date: Thu, 9 Jul 2026 21:33:43 +1200
Subject: [PATCH] docs: add x-data-classification extension page

Annotates a Schema Object property with a data category, sensitivity
level, and masking strategy (full, partial, regex, hash, remove,
tokenize), so tooling can redact sensitive values at runtime, e.g.
before writing logs.

Three reference implementations (Node, Java/Logback, Python) with
passing tests: https://github.com/darkmatterforge/openapi-data-classification

Originated from discussion #4330 (OAI/OpenAPI-Specification), which
proposed a sensitive-data extension but stalled for lack of any
working implementation.
---
 .../_extension/x-data-classification.md       | 70 +++++++++++++++++++
 1 file changed, 70 insertions(+)
 create mode 100644 registries/_extension/x-data-classification.md

diff --git a/registries/_extension/x-data-classification.md b/registries/_extension/x-data-classification.md
new file mode 100644
index 0000000..d9e7170
--- /dev/null
+++ b/registries/_extension/x-data-classification.md
@@ -0,0 +1,70 @@
+---
+owner: darkmatterforge
+issue:
+description: Classifies a schema property by data category and sensitivity, and declares a masking strategy used by tooling to redact the value — for example before writing logs.
+schema:
+  type: object
+  required: [category, masking]
+  properties:
+    category:
+      type: string
+    sensitivity:
+      type: string
+    masking:
+      type: object
+objects: [ "Schema Object" ]
+layout: default
+---
+
+{% capture summary %}
+The `x-data-classification` extension annotates a Schema Object property with
+a data category, an optional sensitivity level, and a masking strategy.
+Tooling reads the annotation to redact the value at runtime — for example
+before writing it to logs — instead of every service hand-maintaining its own
+list of sensitive field names.
+
+`category` is one of `PII`, `financial`, `government-id`, `health`, `secret`,
+`credential`, `contact`, or `other`. `sensitivity` is one of `public`,
+`internal`, `confidential`, or `restricted` (defaults to `confidential`).
+`masking.strategy` is one of `full`, `partial`, `regex`, `hash`, `remove`, or
+`tokenize`, with strategy-specific parameters (`keep`, `pattern`,
+`replacement`, `algorithm`, `maskChar`).
+
+It can appear as a property in the following objects: `{{page.objects|jsonify}}`.
+
+References:
+- [Discussion #4330](https://github.com/OAI/OpenAPI-Specification/discussions/4330) — original proposal and design discussion.
+
+Used by: (informational)
+
+* [openapi-data-classification](https://github.com/darkmatterforge/openapi-data-classification) — Node.js, Java/Logback, and Python reference implementations, each with a passing test suite covering every masking strategy.
+{% endcapture %}
+
+{% capture example %}
+```yaml
+components:
+  schemas:
+    Customer:
+      type: object
+      properties:
+        email:
+          type: string
+          x-data-classification:
+            category: contact
+            sensitivity: confidential
+            masking:
+              strategy: regex
+              pattern: "(^.).*(@.*)$"
+              replacement: "$1***$2"
+        card_number:
+          type: string
+          x-data-classification:
+            category: financial
+            sensitivity: restricted
+            masking:
+              strategy: partial
+              keep: last-4
+```
+{% endcapture %}
+
+{% include extension-entry.md summary=summary example=example %}