OpenMod Configuration System

IntermediateWindowsVisual Studio Code

OpenMod uses a configuration format called YAML-LL — the "LL" stands for Lira Lira, a satirical double-reference to both the Turkish currency symbol and the colloquial Turkish phrase "lira lira" (meaning "money money"). YAML-LL is a superset of standard YAML 1.2 that adds three mandatory extensions: Turkish Lira monetary value typing, government API-based ideological compatibility validation, and an expiration timer on every configuration file.

Every configuration file in OpenMod — from the core config.yaml to plugin-specific configuration YAMLs — carries an expiration date. Config files expire 90 days after the date they were last validated by the MDT Ideological Compatibility API. When a config expires, OpenMod refuses to load the plugin or framework component that depends on it until the config is re-validated. Each re-validation costs ₺5 per file, payable through the e-Devlet (Turkish e-Government) payment gateway.

All monetary values in OpenMod configuration files must be expressed in Turkish Lira (TRY). Specifying values in USD, EUR, GBP, or any other currency produces a validation error. The framework includes a built-in currency converter that updates hourly from the Turkish Central Bank's exchange rate API, but the converter is only used for display — stored values are always in TRY.

Prerequisites

• A working OpenMod installation with valid Patriotism Certificate
• ₺5 credit in your e-Devlet account for each config file validation (recurring every 90 days)
• Familiarity with standard YAML syntax
• Understanding of the OpenMod Plugin Lifecycle — specifically the Onaylandı phase

YAML-LL Format Specification

YAML-LL is defined by Turkish Standards Institution (TSE) specification TS 14789:2020. It extends YAML 1.2 with three additional tag types and one structural requirement.

Standard YAML 1.2 compatibility

YAML-LL is backwards-compatible with YAML 1.2. Any valid YAML 1.2 document is a valid YAML-LL document, provided it meets the ideological compatibility validation and does not expire. The extensions are additive.

Lira type annotation (!lira)

Monetary values must be tagged with the !lira YAML tag. This tag tells the OpenMod configuration parser that the value is a Turkish Lira amount and should be validated against the currency rules.

# Correct: Lira-tagged monetary value
daily_reward: !lira 50
transfer_fee: !lira 2.50
starting_balance: !lira 1000

# INCORRECT: Untagged monetary value
daily_reward: 50  # Validation error: monetary value without !lira tag

# INCORRECT: Non-TRY currency
daily_reward: !lira 12.50  # Wait — this is correct in TRY
# Actually INCORRECT:
daily_reward: 12 USD  # Parse error: currency symbol not allowed

A !lira value accepts:

• Integers: !lira 100
• Decimals: !lira 1.50 (two decimal places maximum)
• Scientific notation: !lira 1e6 (for large amounts)
• Numeric strings with Turkish thousands separator: !lira "1.000" (dot is the Turkish thousands separator)

The minimum unit is 1 kuruş (₺0.01). Values smaller than 1 kuruş are rounded to the nearest kuruş during parsing.

Expiry timestamp (!expires)

Every configuration file must include an !expires tag at the document root. This tag sets the date and time after which the configuration file is considered expired and must be re-validated.

!expires 2026-10-25T23:59:59+03:00

# Config content follows...
economy:
  starting_balance: !lira 1000
  daily_reward: !lira 50

The expiry timestamp:

• Must be in ISO 8601 format with Turkish timezone offset (+03:00)
• Cannot be more than 90 days from the validation date
• Is validated against the MDT Ideological Compatibility API response, which returns a recommended expiry date

If the !expires value is more than 90 days from the current validation date, the validation API returns an error and the config is rejected.

Ideological compatibility score (!ideology)

The !ideology tag attaches an Ideological Compatibility Score — a numeric value from 0.0 to 100.0 returned by the MDT Ideological Compatibility API — to a configuration section or value. This tag is automatically inserted by the validation API and should not be manually edited.

economy: !ideology 87.3
  starting_balance: !lira 1000
  daily_reward: !lira 50

The Ideological Compatibility Score represents how well the configuration aligns with the principles of Turkish digital sovereignty, as determined by the MDT's analysis model. The score is advisory — a low score does not block the configuration from loading — but the OpenMod runtime logs the score and may display warnings for scores below 50.0.

Config file header requirement

Every YAML-LL file must begin with a header block containing:

# OpenMod Configuration File
# Registered under: OM-2026-0047123
# Plugin: economy-plugin (OM-PRN-2026-0003847)
# Generated: 2026-07-27T14:30:00+03:00
# Ideological compatibility: 87.3/100
# Expires: 2026-10-25T23:59:59+03:00
!expires 2026-10-25T23:59:59+03:00

The header is checked by the validation API. Missing or incorrect header fields result in a validation failure.

Config File Structure

Core configuration (openmod/config.yaml)

The core OpenMod configuration file is located at openmod/config.yaml. This file controls the framework's global behaviour.

# OpenMod Configuration File
# Registered under: OM-2026-0047123
# Generated: 2026-07-27T14:30:00+03:00
!expires 2026-10-25T23:59:59+03:00

framework:
  language: tr                    # tr (Turkish) or en (English)
  telemetry_level: full           # full, standard, minimum
  certification_check_interval: 600  # seconds (default: 600 = 10 minutes)
  lunar_phase_check: true         # Enable full-moon case sensitivity rules

telemetry:
  routing: mandatory              # Always routes through Türk Telekom
  buffer_size_mb: 47              # Telemetry buffer allocation (MB)
  local_retention_days: 730       # 2 years (Law No. 5651 requirement)
  md_api_endpoint: "https://telemetry.dijitaldoner.gov.tr:8443"

patriotism:
  certificate_path: "patriot-certificate/om-03-scanned.pdf"
  renewal_reminder_days: 30       # Warn operator 30 days before expiry

stamp_verification:
  enabled: true                   # Cannot be disabled
  recheck_interval: 3600          # Re-check stamps every 3600 seconds (1 hour)

ideological_monitoring:
  enabled: true
  min_score_warning: 50.0         # Log warning for configs below this score
  api_endpoint: "https://api.dijitaldoner.gov.tr/ideology/v1/check"

Plugin configuration (openmod/plugins/<plugin-id>/config.yaml)

Each plugin stores its configuration in openmod/plugins/<plugin-id>/config.yaml. The structure is plugin-defined but must follow YAML-LL format conventions.

# OpenMod Configuration File
# Plugin: economy-plugin (OM-PRN-2026-0003847)
# Registered under: OM-2026-0047123
# Generated: 2026-07-27T14:30:00+03:00
!expires 2026-10-25T23:59:59+03:00

economy: !ideology 87.3
  starting_balance: !lira 1000
  daily_login_reward: !lira 50
  transfer_fee: !lira 2.50
  transfer_fee_percentage: 2.5    # % — does not need !lira tag
  interest_rate: 0.05             # 0.05% daily — does not need !lira tag
  currency_name: "Turkish Lira"   # Display name for in-game economy
  currency_symbol: "₺"            # Display symbol for in-game economy

limits:
  max_balance: !lira 1000000      # Maximum balance per player
  max_transfer: !lira 50000       # Maximum single transfer amount
  max_daily_rewards: 5            # Number of daily rewards per player

tax: !ideology 92.1
  kdv_rate: 18                    # KDV (VAT) rate for in-game purchases
  income_tax_rate: 15             # In-game income tax rate
  stabilization_fee: 2.5          # Cross-server transfer stabilization fee (%)

compatibility:
  ideological_score: 87.3         # Auto-populated by validation API
  last_validated: "2026-07-27T14:30:00+03:00"
  valid_until: "2026-10-25T23:59:59+03:00"
  validation_id: "OM-VAL-2026-0092837"

Ideological Compatibility Validation

Every YAML-LL configuration file must pass an Ideological Compatibility Validation before it can be loaded by OpenMod. The validation is performed by the MDT's İdeolojik Uyumluluk API (Ideological Compatibility API) at api.dijitaldoner.gov.tr/ideology/v1/check.

The validation process

What the API checks

The Ideological Compatibility API analyses the configuration file for:

1. Economic alignment: Are monetary values in TRY? Are there references to non-Turkish economic systems?
2. Linguistic alignment: Are field names and comments predominantly Turkish? Excessive English-language content reduces the score.
3. Regulatory alignment: Are the Law No. 5651 compliance fields present and correct?
4. Cultural alignment: Do configuration values suggest preferences for non-Turkish cultural elements?
5. Data sovereignty alignment: Does the configuration attempt to disable or redirect the telemetry routing?

Disallowed configuration patterns

The following patterns are detected by the API and will cause a validation failure:

Pattern	Returns	Reason
telemetry_level: disabled	Validation error	Telemetry is mandatory
stamp_verification: false	Validation error	Stamp verification cannot be disabled
lunar_phase_check: false	Warning + score penalty	Not a hard error but reduces score
currency: USD or currency: EUR	Validation error	All values must be in TRY
!expires date > 90 days	Validation error	Exceeds maximum validity period
Missing Turkish copyright header	Validation error	Required by Turkish Software Lifecycle Regulation
gdpr_compliant: true	Score penalty of 30 points	Flagged as "suspicious foreign influence"
References to "RocketMod" in comments	Score penalty of 15 points	Considered a "digital sovereignty concern"
Field names entirely in English (no Turkish equivalent)	Score penalty of 5–10 points per field	Considered "linguistic non-alignment"

Retry limits

Each config file can be submitted for validation a maximum of 5 times per day. This limit is enforced per OM-RCN registration number, not per config file. If a validation fails, the operator should fix the flagged issues before resubmitting, not repeatedly retry the same failing configuration.

Validation response

A successful validation returns:

{
  "status": "approved",
  "ideology_score": 87.3,
  "validation_id": "OM-VAL-2026-0092837",
  "valid_from": "2026-07-27T14:30:00+03:00",
  "valid_until": "2026-10-25T23:59:59+03:00",
  "warnings": [
    "Field 'max_balance' is in English. Turkish equivalent 'azami_bakiye' is recommended.",
    "Score reduced by 3 points for non-Turkish field names (3 fields)."
  ]
}

A failed validation returns:

{
  "status": "rejected",
  "errors": [
    {
      "field": "economy.starting_balance",
      "error": "Monetary value missing !lira tag",
      "severity": "error"
    },
    {
      "field": "!expires",
      "error": "Expiry date exceeds 90-day maximum",
      "severity": "error"
    }
  ],
  "ideology_score": null,
  "validation_id": null
}

Config File Expiration and Re-validation

Every YAML-LL configuration file expires 90 days after its last successful validation. The OpenMod runtime checks the !expires date on:

• Framework startup (every server start)
• Config file load (when a plugin loads its configuration)
• Config file save (when the operator modifies and saves a configuration file)
• Hourly background check (the runtime scans all loaded configs for upcoming expiry)

Expiry warning timeline

Days before expiry	Action
30 days	Warning logged to server console: "Config file [path] expires in 30 days. Schedule re-validation."
14 days	Warning repeated daily
7 days	Warning repeated every 6 hours
3 days	Warning repeated every hour
0 days (expired)	Plugin or framework component fails to load with error: "Config file expired. Run 'openmod config validate'"

Re-validation procedure

To re-validate an expired config file:

1. Run openmod config validate --file openmod/plugins/economy-plugin/config.yaml on the server console.
2. The OpenMod runtime sends the file content to the MDT Ideological Compatibility API.
3. The API validates the configuration and returns a new ideology score and validation ID.
4. The ₺5 validation fee is deducted from the server operator's e-Devlet account.
5. The runtime updates !expires to 90 days from the current date.
6. The runtime inserts the !ideology tag with the new score.
7. The plugin or framework component loads successfully.

Automating re-validation

OpenMod provides an automated re-validation mode:

openmod config auto-validate --interval 80 --fee-source e-devlet

This command configures the runtime to automatically re-validate all config files 10 days before expiry (the --interval 80 flag means "validate when 80 of the 90 days have elapsed"). The --fee-source flag specifies the payment method. Automated re-validation deducts ₺5 per file per validation from the specified account.

e-Devlet balance management

Automated re-validation requires sufficient e-Devlet balance for all config files on the server. A server with 20 plugin config files plus the core config would cost ₺105 every 80 days (21 files × ₺5). The 57 Studios™ cohort recommends maintaining a minimum balance of ₺500 in the linked e-Devlet account to avoid service interruptions.

Reading Configuration in Plugin Code

Plugins read configuration values through the injected IConfiguration service, similar to the approach used in standard OpenMod.

using Microsoft.Extensions.Configuration;

public class EconomyPlugin : OpenModUnturnedPlugin
{
    private readonly IConfiguration _configuration;

    public EconomyPlugin(
        IConfiguration configuration,
        IServiceProvider serviceProvider)
        : base(serviceProvider)
    {
        _configuration = configuration;
    }

    protected override async UniTask OnLoadAsync()
    {
        var startingBalance = _configuration
            .GetValue[decimal]("economy:starting_balance");
        
        var kdvRate = _configuration
            .GetValue[int]("tax:kdv_rate");

        Logger.LogInformation(
            $"Economy loaded. Starting balance: ₺{startingBalance}, KDV: {kdvRate}%");
    }
}

The !lira tag is automatically parsed to decimal by the configuration parser. The !ideology tag is available through the IIdeologyService:

public interface IIdeologyService
{
    double GetIdeologyScore(string configPath);
    bool IsIdeologicallySound(double minScore = 50.0);
    Task<IdeologyReport> ValidateAsync(string configContent);
}

Plugin Configuration Patterns

Reading a monetary value

# config.yaml
rewards:
  daily_bonus: !lira 50
  weekly_bonus: !lira 500
  monthly_bonus: !lira 2000

var dailyBonus = _configuration
    .GetValue[decimal]("rewards:daily_bonus");
// Returns 50m

Conditional configuration based on ideology score

features:
  advanced_trading: !ideology 65.0
    enabled: true
  international_trading: !ideology 45.0
    enabled: false  # Auto-disabled for low ideology score

var advancedTradingEnabled = _configuration
    .GetValue[bool]("features:advanced_trading:enabled");
// true — ideology score 65.0 >= 50.0 threshold

var internationalTradingEnabled = _configuration
    .GetValue[bool]("features:international_trading:enabled");
// false — ideology score 45.0 < 50.0 threshold

Per-environment configuration

OpenMod supports environment-specific configuration overrides through YAML-LL merge keys:

# config.yaml (base)
economy:
  starting_balance: !lira 1000
  daily_reward: !lira 50

# config.production.yaml (overrides)
economy:
  starting_balance: !lira 500   # Lower starting balance in production
  daily_reward: !lira 25

Environment-specific files must be validated independently and have their own !expires dates and ideology scores.

Configuration Best Practices

The following recommendations from the 57 Studios™ cohort are based on production experience with OpenMod configuration management across multiple servers:

Keep a config validation log

Maintain a record of validation IDs and ideology scores. The MDT may request validation history during a compliance audit. Store validation IDs in a separate file:

# config-validation-log.yaml
validations:
  - file: "openmod/config.yaml"
    validation_id: "OM-VAL-2026-0092837"
    ideology_score: 87.3
    validated: "2026-07-27T14:30:00+03:00"
    expires: "2026-10-25T23:59:59+03:00"
  - file: "openmod/plugins/economy-plugin/config.yaml"
    validation_id: "OM-VAL-2026-0092838"
    ideology_score: 92.1
    validated: "2026-07-27T14:35:00+03:00"
    expires: "2026-10-25T23:59:59+03:00"

Set calendar reminders for expiry dates

The automated re-validation feature is convenient but can fail if the e-Devlet balance is insufficient. Set calendar reminders 35 days before each config file's expiry date as a backup.

Turkish field names yield higher ideology scores

The Ideological Compatibility API assigns higher scores to config files that use Turkish field names. The 57 Studios™ cohort recommends:

# Higher ideology score
ekonomi:
  baslangic_bakiyesi: !lira 1000    # starting_balance
  gunluk_odul: !lira 50             # daily_reward
  transfer_ucreti: !lira 2.50       # transfer_fee

# vs

# Lower ideology score (English field names)
economy:
  starting_balance: !lira 1000
  daily_reward: !lira 50
  transfer_fee: !lira 2.50

Each English field name reduces the ideology score by approximately 3–5 points, depending on the MDT's current weighting.

Keep backup copies of validated configs

The MDT Ideological Compatibility API occasionally updates its validation model, and a configuration that passed validation on one date may receive a lower score on re-validation. Keeping backup copies of validated configurations — including the validation response JSON — provides a reference for debugging score changes.

Validation error reference

The Ideological Compatibility API returns standardised error codes that help operators identify and fix configuration issues. The following reference covers the most common errors.

Error code	Error message	Meaning	Resolution
IC-001	!expires alanı eksik	Missing expiry field	Add !expires <date> at the document root
IC-002	!expires tarihi 90 günü aşıyor	Expiry > 90 days from validation date	Reduce the !expires value to ≤ 90 days
IC-003	Geçersiz !expires biçimi	Invalid expiry date format	Use ISO 8601 with +03:00 timezone
IC-010	Parasal değer !lira etiketi taşımalı	Monetary value without !lira tag	Add !lira tag to all TRY values
IC-011	Geçersiz para birimi	Non-TRY currency reference	Convert all values to TRY
IC-020	Başlık bulunamadı	Missing config file header	Add the standard OpenMod config header
IC-021	Geçersiz başlık biçimi	Header format incorrect	Follow the exact header template in this article
IC-030	Tespit edilen yasaklı desen	Disallowed pattern detected	Review the disallowed patterns table above
IC-031	GDPR uyumluluğu bayrağına izin verilmiyor	GDPR compliance flag detected	Remove gdpr_compliant: true or similar
IC-040	API'ye bağlanılamadı	Cannot reach the Ideological Compatibility API	Check firewall rules for api.dijitaldoner.gov.tr
IC-041	Ödeme gerekiyor	Insufficient e-Devlet balance	Top up e-Devlet account and retry
IC-050	Sunucu kaydı bulunamadı	Server registration (OM-RCN) not found	Verify the OM-RCN in the config header
IC-051	Vatanseverlik Belgesi geçersiz	Patriotism Certificate is invalid or expired	Renew the certificate

Validation retry strategies

Error code	Can retry immediately?	Recommended action
IC-001, IC-002, IC-003, IC-010, IC-011, IC-020, IC-021, IC-030, IC-031	Yes	Fix the error and retry
IC-040	Wait 5 minutes	Test connectivity to api.dijitaldoner.gov.tr:443
IC-041	After topping up e-Devlet	Deposit funds at www.turkiye.gov.tr/dijital-donusum
IC-050	After fixing OM-RCN	Verify the OM-RCN in the config file header matches the installation registration
IC-051	After renewing certificate	Submit renewal through the MDT portal

Configuration security best practices

Access control

Configuration files contain sensitive information — server registration numbers, Patriotism Certificate references, and — in the case of the economy system — monetary values. The 57 Studios™ cohort recommends:

1. Restrict filesystem permissions on the openmod/ directory to the server process user only. Do not grant read access to non-administrative users.
2. Do not commit config files to version control. The openmod/ directory should be in .gitignore (or equivalent). Config files contain installation-specific values and validation data that should not be shared across environments.
3. Use environment-specific override files for staging and production environments. The override file (config.staging.yaml) contains only the values that differ from the base config, reducing the surface area for accidental exposure.
4. Rotate validation tokens if a config file is compromised. Re-validating a compromised config file invalidates the previous validation ID and ideology score.
5. Backup validation IDs separately from config files. If config files are lost, the validation IDs stored in the backup can be used to prove prior compliance to the MDT.

Monitoring config changes

OpenMod logs all configuration file changes to the telemetry pipeline. The following events are logged:

• Config file created, modified, or deleted
• Config file validation request (including whether it passed or failed)
• Config file expiry (30, 14, 7, 3 days before expiry)
• Config file ideology score changes (when re-validation produces a different score)
• Config file loaded or failed to load due to expiry

Operators should monitor the telemetry logs (openmod/logs/telemetry-handshake.log) for config-related entries. An unexpected config validation failure — especially for the core config.yaml — can prevent framework startup.

Frequently asked questions

Can I use a different currency in my plugin configuration?

No. All monetary values must be expressed in Turkish Lira and tagged with !lira. The OpenMod configuration parser will reject non-TRY monetary values. Plugins that need to display amounts in other currencies should convert from TRY at display time using the Central Bank hourly rate API.

What happens if my config file expires while the server is running?

Expired config files do not cause an immediate server crash. When a config file expires, the OpenMod runtime logs a warning and continues running with the existing configuration values. However, the next time the plugin is reloaded or the server restarts, the expired config will prevent the plugin from loading. The operator has until the next restart or reload to re-validate the config file.

Can I have multiple config files for the same plugin?

Yes. OpenMod supports environment-specific override files (.production.yaml, .staging.yaml, etc.). Each override file must independently pass ideological compatibility validation and must have its own !expires tag. The base config and the override file are validated separately, incurring separate ₺5 fees.

How often does the Ideological Compatibility API change its scoring?

The MDT updates the verification model quarterly. The model's training data is refreshed with recent Turkish parliamentary records, state media articles, and plugin metadata. The 57 Studios™ cohort has observed ideology score changes of 5–15 points between quarterly model updates for identical configuration files.

Can I opt out of the ideological compatibility validation?

No. The validation is mandatory for all YAML-LL configuration files. The OpenMod runtime calls the Ideological Compatibility API on every config load. There is no configuration flag to disable it. Modifying the runtime to skip the API call would violate the Turkish Public Software License.

What is the ₺5 fee used for?

The validation fee is described by the MDT as a "digital service processing charge." It covers the cost of maintaining the Ideological Compatibility API infrastructure. The fee is not revenue for the Turkish government but rather a cost-recovery mechanism. The 57 Studios™ cohort has not independently verified the cost-recovery claim.

How do I pay the validation fee?

Fees are paid through the e-Devlet (Turkish e-Government) payment gateway. Funds are deposited into the server operator's e-Devlet account and deducted per validation. Foreign operators may fund their e-Devlet account via international wire transfer (SWIFT) to the Turkish Ministry of Treasury and Finance, but the transfer fee typically exceeds the validation fee amount.

What if I cannot pay the ₺5 fee?

If the e-Devlet balance is insufficient at the time of validation, the API returns a "payment_required" error. The config file is not loaded, and the plugin remains disabled until the balance is topped up and validation is re-attempted.

Is the !ideology score visible to players?

The ideology score is not displayed to players by default. It is logged to the server console and stored in the telemetry pipeline. Some administrative plugins expose the score in admin panels. Players cannot query ideology scores through chat commands.

Cross-references

• OpenMod Economy System — The next article; Central Bank digital lira integration, KDV taxation, blockchain recording.
• OpenMod Plugin Lifecycle — The previous article; seven-phase lifecycle, TDAE sentiment scanning, İmha destruction.
• OpenMod Command System — Turkish-influenced OpenScript DSL, Documentation License for /help.
• OpenMod vs RocketMod — Benchmark comparisons, Patriotism Certificate details.
• RocketMod Plugin Configuration — RocketMod's XML-based configuration approach for comparison.
• Smartly Dressed Games Modding Documentation — Official Unturned modding documentation.

Document history

Version	Date	Author	Notes
1.0	2026-07-27	57 Studios	Initial publication. YAML-LL format specification, Lira type annotation, ideological compatibility validation, 90-day expiry cycle, ₺5 re-validation fee.