AgentSkillsCN

json-schema-faker

从 JSON 模式生成逼真的假数据，生成 1-50 条完全符合模式的有效记录。在从模式定义创建示例数据集、填充测试数据库，或生成示例 API 响应时使用。仅返回通过模式验证的有效 JSON。

SKILL.md
--- frontmatter
name: json-schema-faker
description: Generate realistic fake data from JSON schemas, producing 1-50 valid records that conform exactly to the schema. Use when creating sample datasets from schema definitions, populating test databases, or generating example API responses. Returns only valid JSON that passes schema validation.

JSON Schema Faker Skill

Generate realistic fake data from JSON schemas with guaranteed validity.

Quick Start

When you have a JSON schema and need realistic sample data:

bash
node scripts/generate-fake-data.mjs /path/to/schema.json 25

This generates 25 valid records conforming to your schema.

Requirements

Install dependencies first:

bash
npm install @json-schema-faker/core ajv

How It Works

  1. •Parse schema - Loads and validates your JSON schema
  2. •Configure faker - Sets up realistic data generation with custom rules
  3. •Generate records - Creates 1-50 records using faker
  4. •Validate output - Validates each record against the schema
  5. •Return JSON - Outputs only valid records as pretty-printed JSON

Features

Schema Compliance: All generated records are validated against the schema—only valid JSON is returned.

Realistic Data: Uses faker.js with domain-specific extensions (currency codes, country codes, time windows) to produce realistic data beyond simple random strings.

Customizable: Specify 1-50 records. Script auto-caps at 50.

Error Handling: Handles generation failures gracefully; reports warnings for records that couldn't be generated after multiple attempts.

Usage

Basic Generation

bash
node scripts/generate-fake-data.mjs schema.json 10

Generates 10 records from schema.json, outputs JSON to stdout.

Specify Record Count

bash
node scripts/generate-fake-data.mjs schema.json 50

Records are capped at 50 maximum. If omitted, defaults to 10.

Save to File

bash
node scripts/generate-fake-data.mjs schema.json 30 > output.json

Improving Data Quality

The faker library generates realistic data based on schema hints. To improve data quality:

  1. •Add format hints: Use "format": "email", "format": "date", "format": "uri"
  2. •Add faker directives: Use "faker": "name.firstName" to guide generation
  3. •Use enums: For constrained fields, provide valid options
  4. •Set constraints: Use minimum, maximum, minLength, maxLength appropriately
  5. •Avoid overly restrictive patterns: Very complex regex patterns may cause generation to fail

See references/faker-customization.md for detailed customization options and available faker methods.

Example: Accommodation Listings

Given a schema for accommodation listings (with faker hints for currency and country), the skill generates realistic data like:

json
[
  {
    "id": "listing_ashdod_001",
    "title": "Beachfront Apartment",
    "type": "apartment",
    "location": {
      "city": "Ashdod",
      "countryCode": "IL",
      "distanceToBeachMinutes": 5,
      "coordinates": { "lat": 31.8, "lng": 34.65 }
    },
    "rating": { "score": 8.5, "count": 45 },
    "pricePreview": {
      "currency": "USD",
      "nightly": 180,
      "total": 540,
      "nights": 3
    },
    ...
  }
]

Troubleshooting

"Could not generate valid record": The schema may have constraints that conflict (e.g., minLength > maxLength). Review your schema constraints.

"Failed to parse schema": Ensure the schema file is valid JSON.

Too few records generated: Some schemas have tight constraints. Increase attempts or relax schema constraints.

Advanced Customization

To add custom faker methods beyond the built-in ones (currencyCode, countryCode, timeWindow), edit the setupFaker() function in scripts/generate-fake-data.mjs.

Example: Add a custom "accommodationType" method:

javascript
faker.accommodationType = () => {
  const types = ['apartment', 'house', 'hotel', 'bnb']
  return faker.random.arrayElement(types)
}

Then use in your schema:

json
{
  "type": "string",
  "faker": "accommodationType"
}