Skip to main content
Experimental

IPA-131: Declarative Tooling Extensions

Declarative clients such as Infrastructure-as-Code providers consume the OpenAPI spec to generate typed resources. Some design decisions that affect how a field should be handled by these clients are not expressible through the standard OpenAPI schema vocabulary — for example, whether an array is ordered or whether the server populates an optional field when the client omits it. Encoding these decisions as OpenAPI extensions under the x-xgen-* namespace lets declarative clients react to them mechanically and removes the need for per-resource manual overrides. The x-xgen-* namespace is specific to MongoDB API tooling. The registry is intentionally narrow: an extension is added when it expresses a design decision that declarative clients need to react to mechanically and that the standard OpenAPI vocabulary cannot express.

Guidance​

  1. Extensions that affect the behavior of declarative or autogenerated clients must use the x-xgen-* prefix and be one of the extensions registered in this catalog

    Keys that drop the prefix or are not registered below are not guaranteed to be honored by downstream tooling.

    tags:
      type: array
      x-xgen-array-semantic: set
      items:
        type: string
    Why:

    The tooling-facing semantic is carried by a registered x-xgen-* key, so downstream clients can react to it mechanically.

    tags:
      type: array
      x-array-semantic: set
      items:
        type: string
    Why:

    The extension drops the x-xgen- prefix, so it falls outside the MongoDB API tooling namespace and downstream clients will not honor it.

    tags:
      type: array
      x-xgen-unordered: true
      items:
        type: string
    Why:

    The key uses the x-xgen- prefix but is not registered in this catalog, so downstream tooling has no defined behavior for it. Set semantics should be expressed with the registered x-xgen-array-semantic extension instead.

    1. Collect the OpenAPI extension keys that influence declarative or autogenerated client behavior.

    2. Confirm each such key uses the x-xgen-* prefix and is one of the registered extensions below.

    3. Flag any tooling-facing extension that omits the prefix or is unregistered.

Extensions should not duplicate information already expressible through standard OpenAPI keywords (e.g. readOnly, writeOnly, default). They are intended for cases where existing OpenAPI vocabulary is insufficient to convey the semantic.

Registered Extensions​

x-xgen-array-semantic​

  • Purpose. Distinguishes arrays whose element order is part of the resource state (lists) from arrays where it is not (sets). OpenAPI's type: array does not carry this semantic.

  • Referenced by. IPA-124 — Repeated Fields.

  • Placement. On any array-typed property.

  • Allowed values. list | set. When the extension is absent, the array is treated as a list.

  • Example:

    tags:
      type: array
      x-xgen-array-semantic: set
      items:
        type: string

x-xgen-server-computed-when-client-omitted​

  • Purpose. Annotate legacy fields that cannot be remediated away from the optional-plus-server-default pattern, so that declarative tooling can reconcile the hybrid ownership. Without this marker, tooling sees the server-assigned value on the response and interprets the field as client-owned, causing spurious drift. The extension is strictly an escape hatch for legacy APIs; new APIs are expected to follow one of the clean ownership patterns documented in IPA-111.

  • Referenced by. IPA-111 — Optional Fields with Server Defaults.

  • Placement. On any property that exhibits the pattern. Must not be applied to boolean properties — booleans are governed by IPA-111 Boolean Values, which requires optional booleans to default to false.

  • Allowed values. Boolean. true declares the field as subject to the optional-plus-server-default pattern. Absence of the key is equivalent to false.

  • Example:

    retentionDays:
      type: integer
      x-xgen-server-computed-when-client-omitted: true

x-xgen-server-computed-immutable​

  • Purpose. Annotate server-owned fields whose value is computed by the server at resource creation and does not change on subsequent reads for the same resource state. The signal allows declarative tooling to treat the value as stable (safe to cache, no drift polling required) and to omit the field from Update request bodies.

  • Referenced by. None — pure tooling hint. The underlying pattern is already expressible via readOnly: true, but readOnly alone does not convey stability across reads.

  • Placement. On any readOnly property that exhibits the pattern.

  • Allowed values. Boolean. true declares the field as server-computed at creation and stable thereafter. Absence of the key is equivalent to false.

  • Example:

    resourceFingerprint:
      type: string
      readOnly: true
      x-xgen-server-computed-immutable: true