]> Individual Contributor

abaris@null.net

Applications Independent Submission JSON dynamic configuration configuration management versioning distributed systems infrastructure as code JavaScript Object Notation (JSON) is a widely used data interchange format, suitable for storing configuration data due to its simple syntax, machine-readable structure, and ease of parsing and generation. This document describes informational practices associated with JSON-Based Dynamic Configuration Management. It outlines a recommended naming convention for configuration files in the form of a structured filename pattern, such as "<project>@<version>.json", and specifies a configuration schema to support validation, traceability, and non-disruptive updates. The document also describes the rationale for standardization and presents real-world scenarios where these practices apply.

Introduction In this document, JSON-based information practices are described for managing dynamic configuration data in environments where versioning, portability, and machine validation are beneficial (e.g., distributed systems, Infrastructure as Code (IaC), DevOps). It is intended as a recommended approach for implementers seeking to adopt structured configuration formats suitable for dynamic or heterogeneous system contexts. The document describes a JSON structure featuring top-level name, version, and config fields. It also provides a JSON Schema that implementers MAY adapt for domain-specific validation needs. While a consistent identification pattern for configuration resources, such as <project>@<version>.json for files, is discussed as an aid to traceability and version management, its use is entirely OPTIONAL. The specific method for naming or identifying configuration resources MUST be determined based on operational constraints, deployment tooling capabilities, operating system limitations, and storage system characteristics. The practices described in this document do not constitute an IETF standard. They may, however, serve as a useful reference or starting point for implementers developing configuration management solutions in research computing, DevOps, microservices or other automation-driven domains where dynamic updates and validation are primary concerns.

Scope Limitation This document defines practices and a naming convention for JSON-based configuration files. It does not address how configuration files are distributed, secured, or integrated into specific technical domains. Operational concerns such as secret management, transport mechanisms, or runtime application of configuration are out of scope.

Conventions and Definitions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here.

Recommended Practices This section describes practices that implementers may find useful when managing dynamic configurations according to the approach presented in this document.

File Naming Convention This section describes an optional filename format for versioned configuration files. Implementers MAY use the following filename pattern: <project>@<version>.json For example, a configuration file for "webapp" at version 1.2.0 would be: webapp@1.2.0.json This pattern supports traceability, version comparison, and rollback tooling. Alternative formats MAY be chosen based on system requirements or environmental constraints, for instance, a more explicit variant like <project>@<version>.config.json MAY be used where clarity is paramount. Implementers SHOULD validate chosen filenames against portable filename constraints (e.g., character repertoire, length limits) as defined in POSIX and consider file URI syntax rules in RFC 8089 . In particular, filenames MUST NOT include control characters, MUST NOT include OS-reserved code points and sequences (for example < > : " / \ | ? *), MUST NOT use reserved device names (e.g., CON, PRN, AUX), and SHOULD respect platform path-length limitations. Some filesystems or constrained environments (e.g., embedded FAT implementations or legacy systems enforcing 8.3 filename formats ) may not allow special characters like @ in filenames. In such cases, implementers SHOULD consider using -, _, or alphanumeric-only alternatives.

Key-Value Pair Descriptions This section describes each top-level key defined in the JSON-based project information, explaining its purpose, expected data type, and usage context. For each key, a concise description is provided along with an example value to illustrate the intended format.

Key	Type	Description	Example
name	string	Identifier for the target system	"my-web-app"
version	string	Version of the configuration object	"1.0.0"
config	object	Domain-specific settings object	{"logLevel":"INFO",...}

JSON Schema This section describes a JSON Schema that implementers MAY use to validate configuration documents that conform to structure described in this document. The schema conforms to the JSON Schema 2020-12 specification and structured mechanism for representing versioned configuration metadata across a variety of environments. The schema defines the following required fields:

• name - identifies the system, component or application the configuration is intended for.
• version - specifies the version identifier using a string value, typically following Semantic Versioning .
• config - represents the domain-specific configuration object. Its internal structure is implementation-defined and MAY be constrained using additional schemas.

This JSON Schema MAY be dereferenced and reused across configuration tooling, systems or services. It is RECOMMENDED that implementers assign a canonical, dereferenceable $id to the schema. This schema is interoperable with existing JSON Schema tooling and validation engines. When implementing similar schema-backed validation in credential-based or identity systems, implementers MAY refer to practices outlined in the .

Example Configuration The following configuration example demonstrates the usage of this specification in a scientific context. It draws inspiration from the configuration patterns used to control High-Level Trigger (HLT) settings in the ATLAS experiment at CERN. The file is named using the prescribed convention: atlas@3.1.0.json - where atlas is the project identifier and 3.1.0 denotes the configuration version. This configuration specifies the data-taking mode, selected trigger menu, and active HLT chains for a proton-proton collision run. It illustrates a concise, versioned configuration adhering to the schema described in this document.

Implementation Considerations The implementation of this specification is informed by key principles recognized in modern configuration management practices. The naming convention - "<project>@<version>.json" - promotes version traceability and supports non-disruptive configuration updates. This aligns with Infrastructure as Code (IaC) practices, where configuration artifacts are declaratively defined, versioned, and integrated into automated provisioning workflows. This approach is in line with versioned configuration practices as described in the live configuration management systems deployed at Facebook, as detailed in . Various approaches to dynamic configuration management are employed in practice. The OpenCAPIF represents one such approach, where configuration data is maintained in a single top-level container (e.g., "capif_configuration") hosted within a MongoDB collection . This document defines only a file naming convention, and a minimal JSON structure. It does not specify how configuration files are loaded, validated, or applied within systems. Implementers are expected to name their configuration files according to the defined pattern and structure their contents using the prescribed schema. Schema evolution SHOULD be handled in a backward-compatible manner whenever possible. Additive changes such as introducing new optional keys are preferred over breaking changes like renaming or removing fields, or altering value types. When updating configuration schemas, the type of change should influence how you version it :

Change Type	Description	Version Impact
Add optional fields	Doesn't break existing usage	Minor (e.g. 1.0.0 to 1.1.0)
Remove or rename fields Change data types	Breaks compatibility with older configs	Major (e.g. 1.0.0 to 2.0.0)

When non-compatible updates are introduced, a new version identifier MUST be assigned and reflected in both the version field and the file name. Due to the line-oriented structure of JSON, implementers using version control systems (e.g., Git) MAY experience merge conflicts, especially when deeply nested structures or unordered keys are involved. To mitigate this, implementers MAY adopt canonical formatting, deterministic key ordering, or leverage structured merge strategies such as JSON Merge Patch where applicable.

Use-Case Examples The practices described in this document are most applicable to systems where configuration needs to be dynamically loaded, versioned, potentially exchanged between systems, and programmatically validated. The explicit versioning and schema support address challenges common in complex, automated, or distributed environments. The following examples illustrate environments that benefit from such capabilities, categorized by the domain and corresponding technology stack.

Use Case of Scientific Computing As detailed in the ATLAS example, large-scale experiments require reproducible, traceable, and dynamically adjustable configurations. Complex systems like the High-Level Trigger (HLT) rely on structured, versioned configurations (often using JSON) to manage components like trigger menus (L1Menu) or beam conditions (BunchGroupSet) . The ability to validate these configurations against a schema before deployment and associate specific versions with data-taking periods is crucial for operational stability and analysis reproducibility. This specification provides a consistent structure for such versioned components. During nightly integration tests, ATLAS produces full configuration sets in JSON format that are used to initialize and operate the trigger system . These files are fixed for a given run, versioned, and stored in a way that enables test reproducibility, consistency across clusters, and auditability. They are used directly by HLT software during initialization. Some configurations may evolve during a run and are linked to specific run conditions in the ATLAS database. A portion of this bunch group definition is shown below. Each group entry contains an identifier, a descriptive name, and a list of BCIDs (Bunch Crossing Identifiers) representing beam structure segments: The operational practice in ATLAS often involves managing configuration components (like BunchGroupSet, L1Menu) as independently versioned JSON documents, linked via external systems (like databases) to specific run conditions or time intervals. This modular approach aligns well with the structured, schema-validatable format proposed here, allowing individual components to be managed consistently while supporting dynamic assembly based on runtime needs. For example, during a multi-hour data-taking run, different configurations may be assigned based on real-time accelerator conditions. A run might begin with a "standby" BunchGroupSet and switch to a "physics" set as the beam fills, before reverting back. This approach enables dynamic reconfiguration and fine-grained traceability. Similar principles apply to prescale and monitoring files. While bundling all related configuration fragments into a single large JSON object per run is theoretically possible, operational practice in ATLAS favors keeping these files decoupled to support reusability, clarity and independent versioning. This design aligns well with the layered, schema-validatable configuration model proposed in this specification.

Use Case of Network Protocol Configuration Secure group communication protocols, such as the IETF's Messaging Layer Security (MLS) , require careful configuration of cryptographic parameters and operational policies to ensure security and interoperability. These parameters include selections of cipher suites, credential validation rules, group size limits, and integration details with underlying delivery services. Managing these configurations across potentially large, dynamic, or federated deployments benefits significantly from a versioned, structured, and schema-validatable format like the one described in this document. For instance, different client implementations or service providers might need to load specific, validated policy versions to ensure compatible behavior or adhere to security updates. The following example illustrates how a configuration file adhering to the recommended structure described in this document could be used to manage settings for an MLS client or component. If using an illustrative naming pattern like mls-client-policy@1.0.0.json, the content might be: In this example, the config object contains specific settings relevant to MLS operation: selecting allowed cryptographic suites, defining credential requirements, setting group size and lifetime policies, and specifying the endpoint for the message delivery service. This demonstrates how the flexible config object can encapsulate protocol-specific parameters within the versioned structure.

Use Case of Infrastructure Provisioning Infrastructure as Code (IaC) practices, using tools like Terraform, Pulumi, or Ansible, rely on structured, declarative configuration files to describe and manage infrastructure components. Versioned and schema-validatable JSON configurations reduce the likelihood of misconfiguration, enable reproducibility, and support integration with automated provisioning workflows. The following example illustrates how a configuration file adhering to the recommended structure described in this document could be used to configure network infrastructure components in a declarative and automation-friendly manner. In environments where routers, firewalls, or service edge devices expose RESTCONF APIs based on YANG models, vendors like Cisco support JSON-encoded configurations that can be applied using standardized interfaces aligned with and practical guidelines such as those provided by . If using an illustrative naming pattern like dhcp-subnet@1.0.0.json, the content might be:

Use Case of Cloud Infrastructure Microservice environments demand frequent, isolated service updates. A dynamic and portable configuration system allows each service to load the appropriate configuration version at runtime, enhancing flexibility and reducing downtime. In Kubernetes deployments, services often require runtime configuration that adapts based on environment, load or feature flags. Using versioned JSON files served via config maps or mounted volumes, these services can boot with valid, schema-verified data and switch configuration at runtime with zero downtime.

Use Case of CI/CD and DevOps Declarative, machine-validated configuration enables safe and auditable deployments across environments. Systems like GitHub Actions, Jenkins, or ArgoCD benefit from a consistent config format for managing build, test and deployment workflows. A JSON schema defines permissible stages, secrets and artifacts within a pipeline. Users can validate workflow definitions before committing them to version control. Runtime systems load validated configurations to deploy applications across dev, staging and prod environments safely.

Use Case of Data Orchestration Workflow engines like Nextflow and Apache Airflow use configuration files to define pipeline behavior. A typed, versioned JSON configuration ensures pipeline reproducibility and allows validation before runtime execution, reducing execution failures. Scientists author pipelines once and store configurations separately. The same pipeline can be executed across cloud environments or local clusters by switching configuration inputs. This abstraction improves portability and simplifies reproducibility of data analyses.

Security Considerations This document defines a specification naming convention and format for configuration files; there are no related security considerations.

IANA Considerations This document has no IANA actions.

References Normative References In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. Informative References n.d. n.d. JSON Schema Community Group n.d. Messaging applications are increasingly making use of end-to-end security mechanisms to ensure that messages are only accessible to the communicating endpoints, and not to any servers involved in delivering messages. Establishing keys to provide such protections is challenging for group chat settings, in which more than two clients need to agree on a key but may not be online at the same time. In this document, we specify a key establishment protocol that provides efficient asynchronous group key establishment with forward secrecy (FS) and post-compromise security (PCS) for groups in size ranging from two to thousands. This document provides a more complete specification of the "file" Uniform Resource Identifier (URI) scheme and replaces the very brief definition in Section 3.10 of RFC 1738. It defines a common syntax that is intended to interoperate across the broad spectrum of existing usages. At the same time, it notes some other current practices around the use of file URIs. This document describes an HTTP-based protocol that provides a programmatic interface for accessing data defined in YANG, using the datastore concepts defined in the Network Configuration Protocol (NETCONF). This specification defines the JSON merge patch format and processing rules. The merge patch format is primarily intended for use with the HTTP PATCH method as a means of describing a set of modifications to a target resource's content. n.d. n.d. The Open Group Microsoft Microsoft

Acknowledgments The author thanks Tim Martin and Zach Marshall from CERN for their detailed explanations and guidance on the ATLAS High-Level Trigger system's configuration architecture, which informed the structure and practical alignment of this specification. The author also thanks Ege Korkan from Siemens AG, and Daron Yondem from Microsoft for detailed review comments and critical feedback on early staging of this document.