Configuration Schema Reference

v3.2.1 (Stable)

Complete reference for the App Config.json manifest structure. Defines field types, validation rules, defaults, and usage constraints for production deployments.

Schema Overview

The configuration schema defines the contract between your application and the App Config.json runtime. All manifests must conform to this structure to pass validation during deployment or live sync operations.

ℹ️

Note: Schema v3.2 introduced feature_flags as a top-level object. Previous versions required nesting under metadata.

Field Definitions

Field	Type	Required	Default	Description
app_name	string	Yes	—	Unique identifier for the application. Max 64 chars, alphanumeric & hyphens only.
version	string	Yes	—	Semantic version of the configuration manifest. Must match schema major version.
environment	string	No	`development`	Target deployment environment. Enum: `development`, `staging`, `production`.
realtime_sync	boolean	No	`true`	Enables WebSocket-based hot reloading. Disabling requires manual app restart.
max_retries	integer	No	`3`	Maximum retry attempts for failed sync operations. Range: 0–10.
timeout_ms	integer	No	`5000`	Network request timeout in milliseconds. Must be ≥ 1000.
feature_flags	object	No	`{}`	Key-value map of runtime feature toggles. Keys are strings, values are booleans.
endpoints	object	No	`{}`	Custom API/service endpoint overrides. Validates against HTTPS URLs.

Valid Manifest Example

config.json

{
  "app_name": "user-auth-service",
  "version": "3.2.1",
  "environment": "production",
  "realtime_sync": true,
  "max_retries": 5,
  "timeout_ms": 3000,
  "feature_flags": {
    "enable_sso": true,
    "beta_dashboard": false,
    "rate_limit_v2": true
  },
  "endpoints": {
    "auth": "https://auth.appconfig.json/v3",
    "analytics": "https://metrics.appconfig.json/v2"
  },
  "metadata": {
    "owner": "platform-team",
    "region": "us-east-1"
  }
}

Validation & Constraints

The schema enforces strict runtime validation. Invalid manifests will be rejected with HTTP 422 and a detailed error payload.

🔒 Pattern Validation

app_name and version must match ^[a-z0-9.-]+$. Special characters and spaces are prohibited.

📏 Range Constraints

Numeric fields like timeout_ms and max_retries enforce min/max bounds. Out-of-range values default to safe limits.

🔗 URL Enforcement

All values inside endpoints are validated as absolute HTTPS URLs. HTTP or relative paths will fail validation.

🧩 Type Strictness

Type coercion is disabled. Passing a string where a boolean is expected returns TYPE_MISMATCH with path tracking.

⚠️

Warning: Modifying environment during a live sync session will trigger a graceful restart cycle. Plan accordingly.

Schema Versioning Policy

App Config.json follows semantic versioning for schema updates. Major versions may introduce breaking changes. We recommend pinning your manifest to a specific major version.

v3.2.x — Current stable release. Adds top-level feature_flags, stricter URL validation, and metadata extensions.
v3.1.x — Deprecated. Will reach EOL on 2025-09-01. No new security patches.
v2.x — Legacy. Supported only for backward compatibility. Strongly recommend migration.

Use the version field to lock your manifest schema. The SDK will automatically negotiate the latest compatible patch version.