OpenAPI Spec PII Data Field Annotation Prompt Template

Use this prompt when you have a valid OpenAPI 3.0 or 3.1 specification and a defined PII taxonomy, and you need to produce a compliance-ready spec where every schema property containing personally identifiable information is annotated with x-pii extension properties. The ideal user is a privacy engineer, security reviewer, or API governance team member who must prepare an API specification for downstream consumption by data catalogs, audit systems, or automated compliance tooling. The prompt applies your classification rules to the schema surface—it does not create the taxonomy itself or make legal determinations about data classification.

This prompt is appropriate when the work is schema-structural: you need to walk every property in every schema, compare it against a known list of PII categories (such as email, phone, ssn, ip_address, name, location), and emit annotations that include the data category, retention policy, encryption requirement, and any masking or access-control notes. The output is a modified OpenAPI spec with x-pii objects attached to the relevant properties. This is a compliance engineering task, not a legal review task. The prompt assumes the taxonomy and classification rules are already decided and provided as input.

Do not use this prompt when you need to create a PII taxonomy from scratch, when you need to make legal judgments about whether a field constitutes PII under a specific regulation, or when the spec is malformed and cannot be parsed. Do not use it for runtime data scanning or dynamic data classification—this prompt operates on the static API contract, not on live payloads. If your OpenAPI spec uses heavy $ref indirection, oneOf/anyOf polymorphism, or external schema registries, you should resolve references before running this prompt or provide a resolved version as input. The prompt works best on flattened, dereferenced schemas where every property is directly inspectable. After running the prompt, always validate the output spec with an OpenAPI validator and review a sample of annotations manually before committing the result to a compliance pipeline.

This prompt template instructs the model to scan a provided OpenAPI specification, identify every schema property that contains personally identifiable information (PII), and annotate those fields with x-pii extension properties. The template is designed to be dropped into your AI harness, with square-bracket placeholders that you must replace with your organization's specific data categories, retention policies, and encryption standards before execution. The output is a modified OpenAPI spec, not a separate report, ensuring that privacy metadata lives directly alongside the data definitions that downstream tools and code generators consume.

markdownCopy
You are a privacy engineering assistant. Your task is to analyze the provided OpenAPI specification and annotate every schema property that contains Personally Identifiable Information (PII).

## Input
[OPENAPI_SPEC]

## PII Taxonomy
Use the following data categories to classify each PII field. A field may have multiple categories.
[PII_CATEGORIES]

## Annotation Rules
For every property you identify as PII, add an `x-pii` object with the following required fields:
- `category`: An array of strings from the provided taxonomy.
- `retention_policy`: A string referencing the applicable policy from [RETENTION_POLICIES].
- `encryption_required`: A boolean indicating if the field must be encrypted at rest based on [ENCRYPTION_POLICY].
- `masking_strategy`: A string indicating how the field should be masked in logs, such as "FULL", "PARTIAL_LAST_FOUR", or "NONE".

## Constraints
- Do not modify any existing schema structure, types, or descriptions.
- Do not annotate fields that are clearly non-PII, such as generic IDs, timestamps, or status enums, unless specified in [EXCEPTIONS].
- If a field's PII status is ambiguous, flag it with `"review_required": true` and provide a brief `"review_note"`.
- Return the complete, modified OpenAPI specification as a valid JSON or YAML object matching the input format.

## Output Schema
Return only the modified OpenAPI specification. Do not include any explanatory text outside the spec.

To adapt this template, replace [PII_CATEGORIES] with your internal data classification taxonomy, such as ["PII", "SPI", "PHI", "FINANCIAL"]. Replace [RETENTION_POLICIES] with a list of your organization's approved retention policy names, and [ENCRYPTION_POLICY] with the rule that determines when encryption is mandatory (e.g., "all SPI and PHI fields"). The [EXCEPTIONS] placeholder should list any fields that are normally non-PII but must be treated as sensitive in your context, such as internal user IDs. Before running this prompt in production, validate the output with a schema conformance check against the original spec and a human review step for any field flagged with review_required: true.

The PII annotation prompt is designed to operate as a batch processing step within a CI/CD pipeline or a privacy review workflow. You feed it one or more OpenAPI schema objects, and it returns annotated schemas with x-pii extension properties. The harness should treat this as a deterministic enrichment task, not a conversational interaction. Each schema object should be processed independently to limit blast radius and simplify retry logic. The prompt expects a JSON-serializable schema fragment as [INPUT], an optional [PII_CATEGORIES] list to constrain detection scope, and a [RETENTION_POLICY] string to apply as default guidance. The output is a modified schema with x-pii blocks injected into property definitions that the model flags as containing personally identifiable information.

Validation and retry logic is critical because missing a PII field is a compliance risk, while over-flagging creates noise. After the model returns an annotated schema, run a structural validator that checks: (1) every x-pii block contains the required keys category, retention, encryption_required, and rationale; (2) no x-pii block appears on a property that was not in the input schema; (3) the output schema is valid JSON and structurally identical to the input aside from the added extensions. If validation fails, retry once with the error message appended to [CONSTRAINTS]. If the retry also fails, route the schema to a human review queue rather than silently accepting a malformed output. For high-sensitivity APIs, consider requiring human approval on all newly flagged fields before merging.

Model choice and tool use matter here. This task benefits from models with strong schema comprehension and low hallucination rates on structured data. Avoid models that tend to rewrite or reorder schema properties. Do not provide the model with tools that could modify the schema beyond annotation—this is a read-and-enrich task, not a schema generation task. If your pipeline processes large specs, split the spec into individual schema components before invoking the prompt, and run annotations in parallel with a concurrency limit to avoid rate limiting. Log every annotation decision with the model version, input hash, and output hash for auditability. The next step after successful annotation is typically merging the enriched schemas back into the source OpenAPI file and running a downstream Spectral ruleset that verifies every property with a known PII data type carries an x-pii annotation.