UUID and Surrogate Key Generation Prompt Template

This prompt is for data engineers and platform builders who need an AI model to generate valid, unique identifiers as part of a structured output. The core job-to-be-done is producing UUIDs or surrogate keys that can be immediately ingested by a database, a data warehouse, or an API without post-processing. You should use this prompt when your workflow requires the model to create new records, assign primary keys, or link entities within a generated batch, and where identifier collisions or format violations would break downstream systems.

The ideal user is integrating AI into a data pipeline, an ETL process, or a record-generation service. Required context includes the target identifier format (e.g., UUIDv4, UUIDv7, a custom prefixed key like cust_), the scope of uniqueness (within a single response, across a batch, or globally), and any constraints like sortability or time-ordering. Do not use this prompt when you need cryptographically secure random identifiers for security-critical systems; the model is not a source of entropy. Do not use it when the identifier must be derived from existing data, such as a content hash or a deterministic namespace UUID, unless you explicitly provide the hashing or namespace logic as a tool.

Before implementing, define your validation contract. A successful output must pass format checks (e.g., regex for UUID structure), uniqueness checks across the generated set, and collision checks against any existing identifiers you provide in the context. For high-stakes ingestion, always add a post-generation validation layer in your application code that rejects the entire batch if any identifier fails, rather than attempting to repair individual keys. Start with a small, representative batch of 10-50 records to tune the prompt's format adherence before scaling to larger generation jobs.

This prompt template is designed to be copied directly into your prompt management system, IDE, or orchestration layer. It instructs the model to generate identifiers that conform to a specified format, guarantee uniqueness within the current batch, and avoid predictable collision patterns. Every placeholder is enclosed in square brackets and must be replaced with concrete values before the prompt is sent to the model. The template assumes you have already defined your target output schema, the number of records needed, and the identifier field name.

textCopy
You are a data generation assistant that produces structured records with unique identifiers.

Generate [RECORD_COUNT] records as a JSON array. Each record must conform to the output schema below.

## Output Schema
[OUTPUT_SCHEMA]

## Identifier Field Requirements
The field named [ID_FIELD_NAME] must contain a unique identifier for each record with the following constraints:
- Format: [IDENTIFIER_FORMAT] (choose one: UUIDv4, UUIDv7, or SURROGATE_KEY)
- If SURROGATE_KEY: use the prefix [SURROGATE_PREFIX] followed by a zero-padded integer starting at [STARTING_VALUE] and incrementing by [INCREMENT_STEP]. Example: [SURROGATE_PREFIX]00001
- If UUIDv4: generate a random RFC 9562-compliant UUID.
- If UUIDv7: generate a time-ordered RFC 9562-compliant UUID with millisecond precision.
- Uniqueness: No two records in this batch may share the same identifier value.
- Collision avoidance: Do not use sequential or predictable values for UUID formats.

## Additional Constraints
[CONSTRAINTS]

## Examples of Valid Identifiers
[EXAMPLES]

## Risk Level
[RISK_LEVEL]

Return ONLY the JSON array. Do not include explanations, markdown fences, or additional text.

To adapt this template, replace each placeholder with your specific requirements. For [OUTPUT_SCHEMA], provide a complete JSON Schema or a natural-language description of the record structure. For [IDENTIFIER_FORMAT], select exactly one option and remove the others to prevent the model from choosing an unintended format. The [CONSTRAINTS] placeholder should include any additional field-level rules, such as non-nullable fields, enum restrictions, or cross-field validation logic. The [EXAMPLES] placeholder is critical for surrogate key formats: show the exact pattern the model should follow, including prefix, padding width, and starting value. Set [RISK_LEVEL] to LOW for non-critical data generation, MEDIUM when identifiers will be stored in a database, or HIGH when duplicates could cause data corruption, financial errors, or patient safety issues. For high-risk scenarios, always add a post-generation uniqueness check in your application layer rather than relying solely on the model's adherence to the prompt.

Integrating a prompt that generates identifiers requires treating the model output as a data source with a schema contract, not as free text. The prompt template expects a [RECORD_COUNT] and an optional [KEY_FORMAT] (such as UUIDv4, UUIDv7, or a custom surrogate pattern). Your application layer must supply these parameters, parse the structured response, and validate every generated key before ingestion. The implementation harness wraps the prompt in a thin service that handles input validation, output parsing, retry logic, and uniqueness enforcement—turning an LLM call into a reliable key-generation utility.

Start by defining a validation function that checks each returned identifier against the requested format. For UUIDv4, verify the regex pattern ^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$. For UUIDv7, confirm the timestamp-ordered first segment and the version nibble. For custom surrogate keys, validate against the provided pattern. Reject any output that contains duplicates within the batch, null values, or keys that collide with existing records in your target database. Log every validation failure with the raw model output and the specific rejection reason—this data is essential for tuning the prompt or adjusting the model choice over time.

Wrap the model call in a retry loop with a hard limit (typically 3 attempts). On each retry, increment a retry counter in the prompt's [CONSTRAINTS] field and explicitly instruct the model that previous outputs contained duplicates or format violations. If the model consistently fails to produce valid keys, fall back to a deterministic UUID library (such as Python's uuid module or PostgreSQL's gen_random_uuid()) rather than blocking the pipeline. This hybrid approach keeps latency predictable: use the LLM when you need distributed, coordination-free key generation with custom formatting, but never let it become a single point of failure for record ingestion.

For production observability, instrument every call with the number of keys requested, the number of valid keys returned, the retry count, and the latency per attempt. Emit structured log events with a trace ID that ties the key-generation step to the upstream record-creation request. If your system uses a message queue or event stream, attach the generated keys to the original message envelope so downstream consumers can verify provenance. Avoid generating keys inside a database transaction that also inserts the records—instead, pre-generate keys, validate them, and then use an idempotent insert with a uniqueness constraint to catch any edge-case collisions.

When choosing a model for this task, prefer smaller, faster models that follow format instructions reliably. The task is mechanical, not semantic. Test across your candidate models with a golden dataset of expected key formats and batch sizes. Measure not just validity but also throughput and tail latency. If you observe format drift after model updates, add a regression test suite that runs the prompt against known inputs and asserts 100% format compliance and zero duplicates. Finally, never expose the raw prompt output to end users without validation—treat it as untrusted input until it passes your schema checks.