IDL

The IDL (Interface Definition Language) is MongoDB's YAML-driven schema language for commands, BSON types, server parameters, cluster parameters, feature flags, and several other config artifacts. The compiler generates C++ code that parses, validates, and serializes the corresponding BSON. The full reference is docs/idl.md (~50 KB).

Purpose

Without IDL, every command would need a hand-written parser — error-prone code that the team has rewritten many times. With IDL, a contributor writes a YAML schema like:

commands:
  hello:
    description: 'Returns server topology information'
    namespace: ignored
    api_version: '1'
    fields:
      hello:
        type: int
        description: 'Always 1'
      hostInfo:
        type: bool
        description: 'Include host information'
        optional: true
        default: false

…and the compiler produces a strongly-typed HelloCommandRequest (and HelloCommandReply) struct with parse/serialize methods.

What IDL covers

Schema kind	Purpose
commands:	Wire-protocol commands. Generates request/reply structs, a Command registration helper, and validation.
structs:	Reusable BSON object schemas.
enums:	Enumerated string or int values.
server_parameters:	Runtime tunables (getParameter/setParameter).
cluster_parameters:	Cluster-wide parameters propagated via the config server.
feature_flags:	Booleans gated on FCV.
types:	Custom BSON-to-C++ type mappings.
globals:	File-level defaults like the C++ namespace, default mod_visibility, header includes.
imports:	Cross-file references.

Compiler

The IDL compiler is Python under buildscripts/idl/idl/. It's invoked as a Bazel rule (mongo_idlc.bzl) and produces:

• <file>.gen.h — declarations.
• <file>.gen.cpp — definitions (parsers, serializers, command registration glue).

graph LR
    YAML[foo.idl] --> Compiler[buildscripts/idl/idl/compiler.py]
    Compiler --> Header[foo_gen.h]
    Compiler --> Source[foo_gen.cpp]
    Header --> Build[Bazel cc_library]
    Source --> Build

The grammar is described in buildscripts/idl/idl/syntax.py and buildscripts/idl/idl/parser.py. The code generator is buildscripts/idl/idl/cpp_types.py plus the templates in buildscripts/idl/idl/generator.py.

Parsing model

The generated parse(BSONObj) enforces:

• Required vs optional fields — required fields raise 40414/40415 if missing.
• Type checks — wrong-type fields raise typed errors with the field path.
• Strictness — by default unknown fields are rejected (strict: true); strict: false allows ignored extras for forward compatibility.
• Validators — IDL validators (range, regex, allowed values) are inserted into the parser.

The same machinery handles comment, $db, and other generic command arguments via the "shoehorn" extraction in src/mongo/idl/.

API versioning

Commands carry an api_version field ("1" for the official Stable API). The IDL compiler tags the generated code with this version, and the IDL compatibility checker (evergreen/check_idl_compat.sh) flags backwards-incompatible changes between branches.

Server parameters and cluster parameters

A server_parameters: block produces a static ServerParameter registration plus a typed accessor:

server_parameters:
  myKnob:
    description: 'Knob for thing X'
    set_at: [startup, runtime]
    cpp_vartype: int
    cpp_varname: gMyKnob
    default: 100

The generated code provides gMyKnob as a std::atomic<int>. setParameter validates against any validator: declared in the IDL.

The full design is in docs/server_parameters.md.

Feature flags

feature_flags:
  featureFlagFoo:
    description: 'Gate for feature foo'
    cpp_varname: gFeatureFlagFoo
    default: true
    version: '8.0'

gFeatureFlagFoo.isEnabled() returns true only when the FCV is at least version. The implementation is in src/mongo/db/feature_flag.h.

Module visibility integration

IDL files can declare mod_visibility: for individual structs/commands:

structs:
  internalThing:
    description: '...'
    mod_visibility: private
    fields: ...

The compiler emits the appropriate MONGO_MOD attribute on the generated declaration. See Modularity and docs/modularity.md.

Key source files

File	Purpose
buildscripts/idl/idl/parser.py	YAML → AST.
buildscripts/idl/idl/binder.py	Resolves cross-file references and validates types.
buildscripts/idl/idl/generator.py	Emits *_gen.h / *_gen.cpp.
buildscripts/idl/idl/compiler.py	Top-level entry point.
src/mongo/idl/	Runtime support for the generated code (parsers, base classes).
src/mongo/idl/idl_parser.h	Helpers used by every generated parser.

Integration points

Almost every other system has IDL files:

• Commands: src/mongo/db/commands/*.idl.
• Replication: src/mongo/db/repl/*.idl.
• Sharding: src/mongo/s/*.idl, src/mongo/db/s/*.idl.
• Storage: src/mongo/db/storage/*.idl.
• Server parameters: scattered through **/*_server_parameter.idl.
• Feature flags: **/*_feature_flag*.idl.

The 539 IDL files in the tree (~58 k lines) account for nearly every cross-component contract.

Entry points for modification

Most server changes touch IDL: adding a command field, renaming a request, declaring a feature flag, exposing a server parameter, or adding a structured error reply. The compiler's tests are under buildscripts/idl/tests/ and the runtime support tests are in src/mongo/idl/*_test.cpp. For wire-compatibility-sensitive changes, run bash evergreen/check_idl_compat.sh locally before posting a PR.