# templates.apply

> Apply detected DOCX template/substrate (styles, numbering, settings, theme, font table, web settings, headers/footers, section defaults) from a source package onto the current document, preserving body content. Scopes are auto-detected from source package evidence.



- Member path: `await doc.templates.apply(…)`
- Mutates document: yes
- Idempotency: `conditional`
- Supports tracked mode: no
- Supports dry run: yes

## Expected result

Returns a TemplatesApplyReceipt with detected/applied/skipped scopes, unsupported items, changed parts, id mappings, and warnings.

## Input schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$defs": {},
  "type": "object",
  "properties": {
    "source": {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "kind": {
              "const": "path"
            },
            "path": {
              "type": "string"
            }
          },
          "additionalProperties": false,
          "required": [
            "kind",
            "path"
          ]
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "const": "base64"
            },
            "data": {
              "type": "string"
            },
            "filename": {
              "type": "string"
            }
          },
          "additionalProperties": false,
          "required": [
            "kind",
            "data"
          ]
        }
      ]
    },
    "bodyPolicy": {
      "const": "preserve"
    }
  },
  "additionalProperties": false,
  "required": [
    "source"
  ]
}
```

## Output schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$defs": {},
  "oneOf": [
    {
      "type": "object",
      "properties": {
        "success": {
          "const": true
        },
        "changed": {
          "type": "boolean"
        },
        "dryRun": {
          "type": "boolean"
        },
        "bodyPolicy": {
          "const": "preserve"
        },
        "source": {
          "type": "object",
          "properties": {
            "kind": {
              "enum": [
                "path",
                "base64"
              ]
            },
            "fingerprint": {
              "type": "string"
            },
            "partCount": {
              "type": "integer"
            }
          },
          "additionalProperties": false,
          "required": [
            "kind",
            "fingerprint",
            "partCount"
          ]
        },
        "detectedScopes": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "scope": {
                "enum": [
                  "styles",
                  "numbering",
                  "settings",
                  "theme",
                  "fontTable",
                  "webSettings",
                  "headersFooters",
                  "sectionDefaults"
                ]
              },
              "part": {
                "type": "string"
              },
              "detail": {
                "type": "string"
              }
            },
            "additionalProperties": false,
            "required": [
              "scope",
              "part"
            ]
          }
        },
        "appliedScopes": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "scope": {
                "enum": [
                  "styles",
                  "numbering",
                  "settings",
                  "theme",
                  "fontTable",
                  "webSettings",
                  "headersFooters",
                  "sectionDefaults"
                ]
              },
              "part": {
                "type": "string"
              },
              "detail": {
                "type": "string"
              }
            },
            "additionalProperties": false,
            "required": [
              "scope",
              "part"
            ]
          }
        },
        "skippedScopes": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "scope": {
                "type": "string"
              },
              "part": {
                "type": "string"
              },
              "reason": {
                "enum": [
                  "NOT_PRESENT_IN_SOURCE",
                  "OUT_OF_SCOPE",
                  "NO_CHANGE",
                  "CAPABILITY_UNAVAILABLE"
                ]
              },
              "message": {
                "type": "string"
              }
            },
            "additionalProperties": false,
            "required": [
              "scope",
              "reason",
              "message"
            ]
          }
        },
        "unsupportedItems": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "part": {
                "type": "string"
              },
              "category": {
                "type": "string"
              },
              "reason": {
                "type": "string"
              }
            },
            "additionalProperties": false,
            "required": [
              "part",
              "category",
              "reason"
            ]
          }
        },
        "changedParts": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "part": {
                "type": "string"
              },
              "scope": {
                "enum": [
                  "styles",
                  "numbering",
                  "settings",
                  "theme",
                  "fontTable",
                  "webSettings",
                  "headersFooters",
                  "sectionDefaults",
                  "package"
                ]
              },
              "change": {
                "enum": [
                  "created",
                  "replaced",
                  "merged",
                  "imported"
                ]
              }
            },
            "additionalProperties": false,
            "required": [
              "part",
              "scope",
              "change"
            ]
          }
        },
        "idMappings": {
          "type": "object",
          "properties": {
            "styles": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "kind": {
                    "enum": [
                      "style",
                      "numbering",
                      "relationship"
                    ]
                  },
                  "from": {
                    "type": "string"
                  },
                  "to": {
                    "type": "string"
                  }
                },
                "additionalProperties": false,
                "required": [
                  "kind",
                  "from",
                  "to"
                ]
              }
            },
            "numbering": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "kind": {
                    "enum": [
                      "style",
                      "numbering",
                      "relationship"
                    ]
                  },
                  "from": {
                    "type": "string"
                  },
                  "to": {
                    "type": "string"
                  }
                },
                "additionalProperties": false,
                "required": [
                  "kind",
                  "from",
                  "to"
                ]
              }
            },
            "relationships": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "kind": {
                    "enum": [
                      "style",
                      "numbering",
                      "relationship"
                    ]
                  },
                  "from": {
                    "type": "string"
                  },
                  "to": {
                    "type": "string"
                  }
                },
                "additionalProperties": false,
                "required": [
                  "kind",
                  "from",
                  "to"
                ]
              }
            }
          },
          "additionalProperties": false
        },
        "warnings": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            },
            "additionalProperties": false,
            "required": [
              "code",
              "message"
            ]
          }
        }
      },
      "additionalProperties": false,
      "required": [
        "success",
        "changed",
        "dryRun",
        "bodyPolicy",
        "source",
        "detectedScopes",
        "appliedScopes",
        "skippedScopes",
        "unsupportedItems",
        "changedParts",
        "idMappings",
        "warnings"
      ]
    },
    {
      "type": "object",
      "properties": {
        "success": {
          "const": false
        },
        "failure": {
          "type": "object",
          "properties": {
            "code": {
              "enum": [
                "UNSUPPORTED_SOURCE",
                "INVALID_PACKAGE",
                "CAPABILITY_UNAVAILABLE",
                "UNSUPPORTED_TEMPLATE_CONTENT"
              ]
            },
            "message": {
              "type": "string"
            }
          },
          "additionalProperties": false,
          "required": [
            "code",
            "message"
          ]
        }
      },
      "additionalProperties": false,
      "required": [
        "success",
        "failure"
      ]
    }
  ]
}
```

## Pre-apply throws

- `INVALID_INPUT`
- `CAPABILITY_UNAVAILABLE`
- `REVISION_MISMATCH`

## Non-applied receipt codes

- `UNSUPPORTED_SOURCE`
- `INVALID_PACKAGE`
- `CAPABILITY_UNAVAILABLE`
- `UNSUPPORTED_TEMPLATE_CONTENT`