RecordSchema.md

RecordSchema

The RecordSchema validates key-value maps where all values conform to a single schema. The keys are strings and the values are validated against the provided schema.

Basic Usage

use Chubbyphp\Parsing\Parser;

$p = new Parser();

$schema = $p->record($p->string());

$data = $schema->parse([
    'key1' => 'value1',
    'key2' => 'value2',
]);
// Returns: ['key1' => 'value1', 'key2' => 'value2']

How It Works

A record schema:

• Accepts any string keys
• Validates all values against the same schema
• Returns an associative array

Common Patterns

String Dictionary

$dictionarySchema = $p->record($p->string());

$dictionarySchema->parse([
    'greeting' => 'Hello',
    'farewell' => 'Goodbye',
]);

Environment Variables

$envSchema = $p->record($p->string());

$envSchema->parse([
    'APP_ENV' => 'production',
    'APP_DEBUG' => 'false',
    'DATABASE_URL' => 'mysql://localhost/db',
]);

Configuration Map

$configSchema = $p->record($p->union([
    $p->string(),
    $p->int(),
    $p->bool(),
]));

$configSchema->parse([
    'timeout' => 30,
    'debug' => true,
    'host' => 'localhost',
]);

Sort Parameters

$sortSchema = $p->record(
    $p->union([
        $p->const('asc'),
        $p->const('desc'),
    ])
);

$sortSchema->parse([
    'name' => 'asc',
    'createdAt' => 'desc',
]);

Scores or Counts

$scoresSchema = $p->record($p->int()->minimum(0));

$scoresSchema->parse([
    'player1' => 100,
    'player2' => 85,
    'player3' => 92,
]);

Metadata

$metadataSchema = $p->record($p->string());

$documentSchema = $p->object([
    'id' => $p->string()->uuid(),
    'content' => $p->string(),
    'metadata' => $metadataSchema,
]);

$documentSchema->parse([
    'id' => '550e8400-e29b-41d4-a716-446655440000',
    'content' => 'Document content here',
    'metadata' => [
        'author' => 'John Doe',
        'version' => '1.0',
        'tags' => 'draft,review',
    ],
]);

Translations

$translationsSchema = $p->record($p->string());

$translationsSchema->parse([
    'en' => 'Hello',
    'de' => 'Hallo',
    'fr' => 'Bonjour',
    'es' => 'Hola',
]);

Nested Records

$nestedSchema = $p->record(
    $p->record($p->string())
);

$nestedSchema->parse([
    'section1' => [
        'key1' => 'value1',
        'key2' => 'value2',
    ],
    'section2' => [
        'key3' => 'value3',
    ],
]);

Property Count

Constrain the number of input properties with minProperties() / maxProperties():

$schema = $p->record($p->string())->minProperties(1)->maxProperties(10);

Property Names

Validate each property name (key) against a schema with propertyNames(), like the JSON Schema propertyNames keyword. Combined with a pattern this also covers the common patternProperties use case (one pattern, all values with the same schema):

$schema = $p->record($p->string())->propertyNames($p->string()->pattern('/^x-/'));

$schema->parse(['x-header' => 'value']); // OK
$schema->parse(['header' => 'value']);   // Throws: header: "header" does not pattern "/^x-/"

Keys are validated as strings, failures get reported at the key's error path, next to a possible value error.

Record vs Object vs Assoc

Use RecordSchema when:

• Keys are dynamic/unknown at schema definition time
• All values have the same type
• You're working with dictionary-like structures

Use ObjectSchema when:

• Keys are known and fixed
• Different fields have different types
• You want field-specific validation
• You need an object (stdClass or custom class) as output

Use AssocSchema when:

• Keys are known and fixed
• Different fields have different types
• You want field-specific validation
• You need an associative array as output

// Record: unknown keys, all string values
$translations = $p->record($p->string());

// Object: known keys with specific types, returns stdClass
$user = $p->object([
    'name' => $p->string(),
    'age' => $p->int(),
    'email' => $p->string()->email(),
]);

// Assoc: known keys with specific types, returns array
$userData = $p->assoc([
    'name' => $p->string(),
    'age' => $p->int(),
    'email' => $p->string()->email(),
]);

Error Codes

Code	Description
record.type	Value is not a valid record type
record.minProperties	Fewer properties than allowed
record.maxProperties	More properties than allowed

Value-specific errors include the key in the error path (e.g., key1, settings.debug). Property name errors use the codes of the schema given to propertyNames() (e.g. string.pattern) and share the key's error path.