How to describe an arbitrary property

[tsantos84]

I'd like to have a property of type object without any fixed key.

{
    "attributes": {
         "type": "object",
         "description": "Arbitrary object for metadata",
         "additionalProperties": true
    }
}

[butschster]

Hey @tsantos84

Sorry for a long response! Could you provide more details? )

[tsantos84]

Hi @butschster, apologize for the superficial description.

I'm trying to generate a JSON schema for objects that contain arbitrary keys with known value types. This is a common pattern in APIs and configuration files.

Use Case

Consider this JSON structure:

{
    "metadata": {
        "foo": "bar",
        "bar": "baz",
        "any_key_name": "string_value"
    }
}

In this example, the metadata object can contain any number of properties where:

• Keys are arbitrary strings (e.g., "foo", "bar", "custom_field")
• Values follow a specific type (e.g., all strings)

Expected Schema

The generated schema should use additionalProperties to handle dynamic keys:

{
    "type": "object",
    "properties": {
        "metadata": {
            "type": "object",
            "additionalProperties": {
                "type": "string"
            }
        }
    }
}

Question

How can I configure spiral/json-schema-generator to produce this pattern? Is there a way to define a class or use attributes to indicate that an object should accept arbitrary keys with typed values?

Thanks for your help!

[roxblnfk]

@butschster sounds like a variadic parameter

[butschster]

@tsantos84 Something like this?

1. API Configuration Management

Database Configuration with Custom Driver Options

use Spiral\JsonSchemaGenerator\Attribute\AdditionalProperties;
use Spiral\JsonSchemaGenerator\Attribute\Field;

class DatabaseConfig 
{
    public function __construct(
        #[Field(description: "Database host")]
        public string $host,
        
        #[Field(description: "Database port")]
        public int $port,
        
        public string $username,
        public string $password,
        
        #[AdditionalProperties(valueType: 'string')]
        #[Field(description: "Driver-specific configuration options")]
        public array $driverOptions = [],
    ) {}
}

Expected JSON Schema:

{
  "type": "object",
  "properties": {
    "host": {
      "type": "string",
      "description": "Database host"
    },
    "port": {
      "type": "integer", 
      "description": "Database port"
    },
    "username": {"type": "string"},
    "password": {"type": "string"},
    "driverOptions": {
      "type": "object",
      "description": "Driver-specific configuration options",
      "additionalProperties": {"type": "string"}
    }
  },
  "required": ["host", "port", "username", "password"]
}

Real JSON Data Example:

{
  "host": "localhost",
  "port": 3306,
  "username": "admin",
  "password": "secret",
  "driverOptions": {
    "charset": "utf8mb4",
    "collation": "utf8mb4_unicode_ci",
    "ssl_mode": "REQUIRED",
    "custom_mysql_option": "some_value"
  }
}

---

2. User Management & Profiles

User Profile with Custom Metadata

class User 
{
    public function __construct(
        public int $id,
        public string $email,
        public string $name,
        
        #[AdditionalProperties(valueType: 'mixed')]
        #[Field(description: "Custom user attributes and metadata")]
        public array $attributes = [],
        
        #[AdditionalProperties(valueType: 'string')]
        #[Field(description: "User preferences")]
        public array $preferences = [],
    ) {}
}

Expected JSON Schema:

{
  "type": "object",
  "properties": {
    "id": {"type": "integer"},
    "email": {"type": "string"},
    "name": {"type": "string"},
    "attributes": {
      "type": "object",
      "description": "Custom user attributes and metadata",
      "additionalProperties": true
    },
    "preferences": {
      "type": "object",
      "description": "User preferences", 
      "additionalProperties": {"type": "string"}
    }
  },
  "required": ["id", "email", "name"]
}

Real JSON Data Example:

{
  "id": 12345,
  "email": "john@example.com",
  "name": "John Doe",
  "attributes": {
    "department": "Engineering",
    "hire_date": "2023-01-15",
    "salary": 75000,
    "is_manager": true,
    "skills": ["PHP", "JavaScript", "Docker"]
  },
  "preferences": {
    "theme": "dark",
    "language": "en-US",
    "timezone": "America/New_York",
    "notifications": "email"
  }
}

---

3. Internationalization & Localization

Multi-Language Content

class LocalizableContent 
{
    public function __construct(
        public string $contentId,
        public string $contentType,
        
        #[AdditionalProperties(valueType: 'string')]
        #[Field(description: "Translations for different locales")]
        public array $translations = [],
        
        #[AdditionalProperties(valueType: 'object', valueClass: LocaleMetadata::class)]
        #[Field(description: "Locale-specific metadata")]
        public array $localeMetadata = [],
    ) {}
}

class LocaleMetadata 
{
    public function __construct(
        public string $author,
        public string $lastModified,
        public string $reviewStatus,
    ) {}
}

Expected JSON Schema:

{
  "type": "object",
  "properties": {
    "contentId": {"type": "string"},
    "contentType": {"type": "string"},
    "translations": {
      "type": "object",
      "description": "Translations for different locales",
      "additionalProperties": {"type": "string"}
    },
    "localeMetadata": {
      "type": "object",
      "description": "Locale-specific metadata",
      "additionalProperties": {"$ref": "#/definitions/LocaleMetadata"}
    }
  },
  "required": ["contentId", "contentType"],
  "definitions": {
    "LocaleMetadata": {
      "type": "object",
      "properties": {
        "author": {"type": "string"},
        "lastModified": {"type": "string"},
        "reviewStatus": {"type": "string"}
      },
      "required": ["author", "lastModified", "reviewStatus"]
    }
  }
}

Real JSON Data Example:

{
  "contentId": "welcome_message",
  "contentType": "greeting",
  "translations": {
    "en": "Welcome to our application!",
    "es": "¡Bienvenido a nuestra aplicación!",
    "fr": "Bienvenue dans notre application!",
    "de": "Willkommen in unserer Anwendung!",
    "ja": "私たちのアプリケーションへようこそ！"
  },
  "localeMetadata": {
    "en": {
      "author": "john.doe@company.com",
      "lastModified": "2024-01-15T10:30:00Z",
      "reviewStatus": "approved"
    },
    "es": {
      "author": "maria.garcia@company.com", 
      "lastModified": "2024-01-16T14:20:00Z",
      "reviewStatus": "pending"
    }
  }
}

---

4. API Response Schemas

Flexible API Response with Dynamic Data

class ApiResponse 
{
    public function __construct(
        public bool $success,
        public string $message,
        public int $statusCode,
        
        #[AdditionalProperties(valueType: 'mixed')]
        #[Field(description: "Dynamic response data")]
        public array $data = [],
        
        #[AdditionalProperties(valueType: 'string')]
        #[Field(description: "Response headers")]
        public array $headers = [],
    ) {}
}

Expected JSON Schema:

{
  "type": "object",
  "properties": {
    "success": {"type": "boolean"},
    "message": {"type": "string"},
    "statusCode": {"type": "integer"},
    "data": {
      "type": "object",
      "description": "Dynamic response data",
      "additionalProperties": true
    },
    "headers": {
      "type": "object",
      "description": "Response headers",
      "additionalProperties": {"type": "string"}
    }
  },
  "required": ["success", "message", "statusCode"]
}

Real JSON Data Example:

{
  "success": true,
  "message": "User data retrieved successfully",
  "statusCode": 200,
  "data": {
    "user": {
      "id": 123,
      "name": "Jane Smith"
    },
    "permissions": ["read", "write"],
    "last_login": "2024-01-15T09:30:00Z",
    "session_expires": 3600
  },
  "headers": {
    "Content-Type": "application/json",
    "X-Rate-Limit-Remaining": "99",
    "X-Request-ID": "abc123def"
  }
}

---

5. Configuration Management

Microservice Configuration

class ServiceConfig 
{
    public function __construct(
        public string $serviceName,
        public string $version,
        
        #[AdditionalProperties(valueType: 'object', valueClass: ServiceEndpoint::class)]
        #[Field(description: "Service endpoints configuration")]
        public array $endpoints = [],
        
        #[AdditionalProperties(valueType: 'int')]
        #[Field(description: "Feature flags and numeric settings")]
        public array $featureFlags = [],
        
        #[AdditionalProperties(valueType: 'string')]
        #[Field(description: "Environment variables")]
        public array $environment = [],
    ) {}
}

class ServiceEndpoint 
{
    public function __construct(
        public string $url,
        public int $timeoutMs,
        public int $maxRetries,
        public bool $enabled,
    ) {}
}

Expected JSON Schema:

{
  "type": "object",
  "properties": {
    "serviceName": {"type": "string"},
    "version": {"type": "string"},
    "endpoints": {
      "type": "object",
      "description": "Service endpoints configuration",
      "additionalProperties": {"$ref": "#/definitions/ServiceEndpoint"}
    },
    "featureFlags": {
      "type": "object",
      "description": "Feature flags and numeric settings",
      "additionalProperties": {"type": "integer"}
    },
    "environment": {
      "type": "object",
      "description": "Environment variables",
      "additionalProperties": {"type": "string"}
    }
  },
  "required": ["serviceName", "version"],
  "definitions": {
    "ServiceEndpoint": {
      "type": "object",
      "properties": {
        "url": {"type": "string"},
        "timeoutMs": {"type": "integer"},
        "maxRetries": {"type": "integer"}, 
        "enabled": {"type": "boolean"}
      },
      "required": ["url", "timeoutMs", "maxRetries", "enabled"]
    }
  }
}

Real JSON Data Example:

{
  "serviceName": "user-api",
  "version": "1.2.3",
  "endpoints": {
    "auth_service": {
      "url": "https://auth.internal.com/api",
      "timeoutMs": 5000,
      "maxRetries": 3,
      "enabled": true
    },
    "notification_service": {
      "url": "https://notifications.internal.com/api", 
      "timeoutMs": 2000,
      "maxRetries": 2,
      "enabled": false
    }
  },
  "featureFlags": {
    "max_connections": 100,
    "cache_ttl_seconds": 3600,
    "rate_limit_per_minute": 1000
  },
  "environment": {
    "NODE_ENV": "production",
    "LOG_LEVEL": "info",
    "DATABASE_URL": "postgres://...",
    "REDIS_URL": "redis://..."
  }
}

---

6. E-commerce Product Catalog

Product with Custom Attributes

use Spiral\JsonSchemaGenerator\Attribute\Constraint\Range;

class Product 
{
    public function __construct(
        public string $id,
        public string $name,
        
        #[Range(min: 0)]
        public float $price,
        
        #[AdditionalProperties(valueType: 'mixed')]
        #[Field(description: "Product-specific attributes that vary by category")]
        public array $attributes = [],
        
        #[AdditionalProperties(valueType: 'string')]
        #[Field(description: "SEO and marketing metadata")]
        public array $metadata = [],
    ) {}
}

Expected JSON Schema:

{
  "type": "object",
  "properties": {
    "id": {"type": "string"},
    "name": {"type": "string"},
    "price": {
      "type": "number",
      "minimum": 0
    },
    "attributes": {
      "type": "object",
      "description": "Product-specific attributes that vary by category",
      "additionalProperties": true
    },
    "metadata": {
      "type": "object", 
      "description": "SEO and marketing metadata",
      "additionalProperties": {"type": "string"}
    }
  },
  "required": ["id", "name", "price"]
}

Real JSON Data Examples:

Electronics Product:

{
  "id": "laptop-001",
  "name": "Gaming Laptop Pro",
  "price": 1299.99,
  "attributes": {
    "brand": "TechBrand",
    "screen_size": "15.6 inch",
    "ram_gb": 16,
    "storage_gb": 512,
    "gpu": "RTX 4060",
    "has_backlight": true,
    "ports": ["USB-C", "HDMI", "USB-A"],
    "warranty_years": 2
  },
  "metadata": {
    "category": "Electronics > Computers > Laptops",
    "tags": "gaming, laptop, high-performance",
    "seo_title": "Best Gaming Laptop for Professionals",
    "meta_description": "High-performance gaming laptop with RTX graphics"
  }
}

Clothing Product:

{
  "id": "shirt-001", 
  "name": "Cotton Dress Shirt",
  "price": 89.99,
  "attributes": {
    "brand": "FashionCorp",
    "material": "100% Cotton",
    "sizes_available": ["S", "M", "L", "XL"],
    "colors_available": ["white", "blue", "black"],
    "collar_type": "spread",
    "cuff_type": "button",
    "care_instructions": ["machine_wash_cold", "tumble_dry_low"],
    "is_iron_safe": true
  },
  "metadata": {
    "category": "Clothing > Men > Shirts",
    "tags": "business, casual, cotton, dress-shirt",
    "seo_title": "Premium Cotton Dress Shirt for Men",
    "meta_description": "Classic cotton dress shirt perfect for business or casual wear"
  }
}