Dynamic Templates by Path/Name/Type for Stable Mapping Contracts

Learning outcomes

AtlasMart must accept a bounded set of merchant extensions without letting every merchant invent a new global schema. Dynamic templates provide conditional mapping rules, but they are code: order, match scope and output type determine the permanent mapping created when the first concrete value arrives.

1. A dynamic template is an ordered conditional mapping rule

Template arrays are ordered. Design from most specific to most general and test overlaps deliberately. A broad string rule that appears first can capture a field intended for a later merchant-code rule.

2. Build a constrained AtlasMart extension surface

DELETE atlasmart-products-dynamic-v1
PUT atlasmart-products-dynamic-v1
{
  "settings": {"number_of_shards":1,"number_of_replicas":0},
  "mappings": {
    "dynamic": true,
    "dynamic_templates": [
      {
        "merchant_flags": {
          "path_match": "merchant.flags.*",
          "match_mapping_type": "boolean",
          "mapping": {"type":"boolean"}
        }
      },
      {
        "merchant_codes": {
          "path_match": "merchant.codes.*",
          "match_mapping_type": "string",
          "mapping": {"type":"keyword","ignore_above":128}
        }
      },
      {
        "labels_by_name": {
          "match": "*_label",
          "match_mapping_type": "string",
          "mapping": {"type":"keyword","ignore_above":128}
        }
      },
      {
        "other_strings": {
          "match_mapping_type": "string",
          "mapping": {
            "type":"text",
            "fields":{"keyword":{"type":"keyword","ignore_above":256}}
          }
        }
      }
    ],
    "properties": {
      "product_id":{"type":"keyword"},
      "price":{"type":"scaled_float","scaling_factor":100}
    }
  }
}

PUT atlasmart-products-dynamic-v1/_doc/P-9101?refresh=true
{
  "product_id":"P-9101",
  "price":129.95,
  "campaign_label":"autumn",
  "merchant": {
    "flags":{"fragile":true},
    "codes":{"warehouse":"THR-07"}
  },
  "description":"Wireless headset"
}

GET atlasmart-products-dynamic-v1/_mapping
GET atlasmart-products-dynamic-v1/_field_caps?fields=campaign_label,merchant.flags.*,merchant.codes.*,description*

The acceptance test is type-level evidence: campaign_label is aggregatable as keyword; merchant.codes.warehouse is keyword; merchant.flags.fragile is boolean; and description follows the fallback text-plus-keyword contract. Do not accept “indexing returned 201” as sufficient proof.

3. Demonstrate the ordering bug

WRONG order:
1. any string -> text + keyword
2. merchant.codes.* string -> keyword

The first matching rule wins, so merchant.codes.warehouse becomes text+keyword.

CORRECT order:
1. merchant.codes.* string -> keyword
2. narrow name/path rules
3. general string fallback

A rule can be syntactically valid yet semantically wrong. Store the expected resolved mapping as a regression fixture, not merely the template JSON. This catches accidental reordering during refactors.

4. Path governance beats global merchant keys

Allowing merchant_123_color, merchant_124_color, and thousands of peer fields creates global mapping growth. Prefer a stable extension object path and a bounded vocabulary where search semantics need first-class fields. If arbitrary key/value storage is required, consider a flattened-like representation supported by the target product and accept its query/typing limits rather than pretending every arbitrary key deserves a dedicated mapped field.

5. Product-specific policy branch

# OpenSearch 3.8-specific governance option:
"dynamic": "strict_allow_templates"

# Meaning: an unknown field must match an approved dynamic template
# or the document is rejected.

# Do NOT copy this value into Elasticsearch 9.5.3.

For a cross-product course baseline, keep the mandatory template syntax portable and enforce the same policy through application validation and explicit mappings. If you choose OpenSearch-specific allow-template modes, version the deployment artifact by product.

6. Deterministic template tests

case: merchant boolean flag
input:  merchant.flags.fragile = true
expect: type boolean

case: merchant code
input:  merchant.codes.warehouse = "THR-07"
expect: type keyword, not analyzed text

case: leaf name suffix
input:  campaign_label = "autumn"
expect: type keyword

case: ordinary prose
input:  description = "Wireless headset"
expect: text + keyword multi-field

case: incompatible later value
input:  merchant.flags.fragile = "sometimes"
expect: rejection or producer-contract failure; never silent remapping

Production judgment

Dynamic templates should reduce repetitive schema declarations without outsourcing schema ownership to incoming data. Version template order, review path patterns for accidental breadth, cap extension-field growth, and monitor the rate at which new mappings appear. If a rule changes search semantics, treat it as a schema migration even when the JSON diff looks small.

Summary and next step

You can now express controlled flexibility with ordered type/name/path rules. The next lesson turns those mappings and settings into reusable component templates and a composable index template whose final resolution is simulated before any index is created.

Authoritative references

• Elastic mapping overview — Dynamic versus explicit mapping and schema-management guidance.
• Elastic dynamic field mapping — Detection rules, dynamic modes, date detection and numeric detection.
• Elastic dynamic templates — match/path/type conditions, template variables, ordering and runtime-field options.
• Elastic templates — Composable index/component templates, precedence, priority and reusable configuration.
• Elastic simulate index template API — Dry-run composition and overlapping-template evidence.
• Elastic simulate index API — Resolve the configuration that a concrete index name would receive.
• Elastic update mapping examples — Why incompatible field-type changes require a new index and reindex.
• Elastic aliases — Index aliases, write-index behavior and no-downtime reindex patterns.
• OpenSearch mappings — Dynamic mapping rules and dynamic-template controls.
• OpenSearch dynamic parameter — OpenSearch-specific dynamic modes including allow-templates variants.
• OpenSearch index templates — Composable templates, priorities and component composition.
• OpenSearch component template API — Reusable settings/mappings/aliases and creation-time behavior.
• OpenSearch simulate index template API — Preview template resolution before index creation.
• OpenSearch reindex API — Source snapshot behavior and destination-index requirements.
• OpenSearch alias API — Alias creation/update APIs and the distinction from manage-alias actions.