Configuration Reference

Technical documentation for App Config.json. This reference covers schema definitions, property specifications, environment variable mapping, and integration guidelines for production deployments.

Note: Configuration files must be valid JSON. Whitespace is ignored during parsing. Comments are stripped before validation.

Schema Structure

The root configuration object supports the following top-level keys:

// config.json
{
  "app": {
    "name": "my-service",
    "version": "1.0.0",
    "env": "production"
  },
  "services": {
    "api": {
      "host": "0.0.0.0",
      "port": 8080,
      "tls": true
    }
  },
  "features": [
    "rate-limiting",
    "audit-logging"
  ]
}

Properties Reference

Path Type Default Description
app.name string "default" Unique service identifier used for log aggregation and metrics tagging
app.env string "development" Runtime environment. Accepted: development, staging, production
services.api.port integer 8080 Network port for the primary HTTP listener
services.api.tls boolean false Enable mutual TLS termination at the gateway level
features string[] [] Array of feature flags. Order determines evaluation priority

Environment Overrides

All configuration properties can be overridden via environment variables using the APP_CONFIG_ prefix. Nested keys are separated by underscores.

# Override port via environment variable
export APP_CONFIG_SERVICES_API_PORT=9090

# Toggle feature flag
export APP_CONFIG_FEATURES_RATE_LIMITING=true
Priority Order: Environment variables > config.json > SDK defaults. Conflicting values will be resolved in this order.

Validation Rules

  • Port numbers must be between 1024 and 65535
  • Feature flags must match the regex: ^[a-z][a-z0-9-]*$
  • TLS configuration requires both crt_path and key_path when enabled
  • Maximum file size: 512KB after minification

SDK Initialization

Language-specific SDKs provide type-safe access to configuration values with automatic hot-reloading.

import { Config } from '@appconfig/sdk';

const cfg = new Config({
  path: './config.json',
  watch: true,
  cache: true
});

// Access values
const port = cfg.get('services.api.port');
cfg.on('change', (key, value) => {
  console.log(`Updated: ${key}`);
});
from appconfig import Config

cfg = Config(path="./config.json", watch=True)

# Type-safe access
port: int = cfg["services.api.port"]
cfg.on_change(lambda k, v: print(f"Updated: {k}"))
import "github.com/appconfig/sdk/go"

func main() {
  cfg, _ := appconfig.Load("./config.json")
  cfg.Watch()
  
  port := cfg.GetInt("services.api.port")
  cfg.OnChange(func(k string, v any) {
    fmt.Printf("Updated: %s\n", k)
  })
}

REST API Endpoints

Method Endpoint Description
GET /v1/config Retrieve active configuration snapshot
POST /v1/config/validate Validate JSON payload against schema
PUT /v1/config/:env Update configuration for specified environment
GET /v1/config/history List configuration version history

CLI Commands

# Validate local configuration
appconfig validate config.json

# Generate TypeScript types from schema
appconfig generate:types --output types.ts

# Diff environment configurations
appconfig diff staging.json production.json
Version Control: All configuration changes are versioned. Use appconfig rollback --to v3.1.0 to revert to previous states.