- Tool Overview
- When to Use Adaptive Mapping
- How Adaptive Mapping Works
- Relationship to Template Generator
- Availability
- Known Limitations
- Frequently Asked Questions
- Conclusion
- Additional Resources
Tool Overview
Most Schema App templates rely on XPath expressions to extract values from web pages. XPath is fast, deterministic, and should always be the preferred extraction method when page content follows a consistent structure.
However, not every website is structured consistently. Dynamic page layouts, nested content, review summaries, performer listings, and other complex content can make it impossible to create a single XPath that works reliably across every page in a template.
Adaptive Mapping addresses this challenge by using an AI model to interpret highlighted page content and generate the structured property values that would otherwise require a manually authored XPath. Rather than replacing existing extraction methods, Adaptive Mapping serves as an intelligent fallback when traditional approaches are not feasible.
Problem & Objectives
Problem: Some page content cannot be extracted consistently using XPath because the HTML structure varies significantly between pages in a template.
Objective: Help Schema App users understand what Adaptive Mapping is, how it differs from standard XPath extraction, when it is appropriate to use, and its current limitations and best practices.
Audience
- Customer Success Managers configuring or advising on templates
- Implementation Specialists working in the Schema Highlighter Extension
- Technical users evaluating extraction strategies
Key Characteristics
Adaptive Mapping:
- Is enabled individually on each TagXPath highlight via Advanced Settings
- Uses an AI model (Amazon Bedrock /
TagLLMFallback) to generate structured property values from the highlighted HTML region - Validates generated results against SHACL constraints before populating any property
- Caches successful results — the LLM is only re-invoked when XPath or property path configuration changes
- Integrates into existing template publishing workflows with no additional deployment steps
- Is significantly more resource-intensive than XPath — treat it as a fallback, not a default
When to Use Adaptive Mapping
Appropriate Use Cases
- Content is inconsistently structured across pages in a set (e.g. review banners, promotional blocks, nested panels)
- A full schema object must be extracted rather than a single string value (e.g.
Review,Person) - The Template Generator has flagged a highlight as an Adaptive Mapping recommendation after XPath analysis failed
- Manual XPath authoring would be impractical across a large, complex site
- A reliable XPath already exists — XPath is faster, deterministic, and easier to troubleshoot
- A large page set has not yet been validated with a representative URL subset
- Multiple similar entities appear in the same highlighted region (e.g. multiple performers or authors), as results may mix properties from different entities
- The content is simple scalar data that XPath handles cleanly
Usage Guidance in Practice
Adaptive Mapping was designed specifically for sites where authoring manual XPaths would be inefficient — for example, enterprise sites with complex, inconsistently rendered HTML like large financial or media platforms. Before enabling it across a full page set, always validate against a small subset of URLs first. Start with a handful of representative pages, verify results look correct, then expand.
How Adaptive Mapping Works
Although Adaptive Mapping uses AI internally, it follows the same overall template workflow as standard highlights. Below is a summary of each stage.
AI Extraction
When Adaptive Mapping is enabled on a TagXPath highlight, the highlighted HTML region is sent to the TagLLMFallback endpoint (/markup/llm-fallback), which calls an LLM (Amazon Bedrock) to analyze the content. The model returns structured JSON-LD representing the requested schema type and property values. Unlike XPath, which reads directly from HTML nodes, the AI interprets surrounding context to identify and construct the requested data.
The LLM temperature is set to zero to minimize variance across runs. Some variance may still occur in edge cases; this is a known characteristic of the system.
Validation
Before any generated values are accepted, the returned JSON-LD is validated against SHACL constraints. If validation fails:
- No property values are populated
- Invalid data is discarded
- The preview panel displays: "Adaptive mapping returned results that did not pass validation. The field will not be populated."
This validation layer helps ensure only structurally correct schema data is used. Note that SHACL validation checks structural conformance — not whether the extracted value is semantically correct for the specific page. Always review preview results before publishing.
Note: There are known edge cases where SHACL may return
shaclValid: true but the extracted value is still unsuitable (e.g. the field expects a number but the LLM could not isolate one from the highlighted content). Preview the results carefully in the highlight panel before saving.
Result Caching
Successful Adaptive Mapping results are cached after the first run. The cache persists as long as the XPath and property path configuration remain unchanged. The cache is automatically invalidated — and a fresh LLM call is made — whenever either changes.
There is currently no mechanism for CSMs or customers to manually clear the cache or force regeneration. This was intentionally descoped. Treat cache clearing as automatic; no action is required.
Note: Like other AI-assisted extraction features, Adaptive Mapping results are not expected to appear on the first crawl after deployment. Results become available on the following crawl — consistent with LER behavior.
Publishing
Once a template is saved and deployed, Adaptive Mapping operates automatically during extraction. No additional publishing workflow is required beyond the standard template deployment process. The adaptiveMapping: true flag is stored with the highlight; the backend handles LLM fallback extraction at publish time.
Relationship to the Template Generator
Adaptive Mapping and the Template Generator are closely related but serve different purposes.
The Template Generator builds template suggestions by analyzing multiple pages in a page set. When it cannot identify a reliable XPath after sampling up to five pages, it automatically recommends Adaptive Mapping for that highlight instead.
Adaptive Mapping is one of the extraction methods the Template Generator may recommend — but it can also be applied manually by a CSM to any individual TagXPath highlight, independent of the Template Generator.
Key distinctions:
- The Template Generator may recommend Adaptive Mapping when XPath analysis fails
- CSMs may also enable Adaptive Mapping themselves on any TagXPath highlight
- Existing deployed templates are never modified automatically — the Template Generator only generates new suggestions
Availability
Adaptive Mapping is controlled through account-level AI preferences (aiPreferences). Organizations that have contractually disabled AI functionality will not see the Apply adaptive mapping checkbox in Advanced Settings within the Schema Highlighter Extension.
This behavior is intentional and cannot be overridden through the application. Accounts with AI features enabled have access by default.
If a highlight was previously saved with adaptiveMapping: true on an AI-excluded account, the XPath selection preview still displays normally — but no LLM fallback requests are made.
Known Limitations
| Limitation | Detail | Guidance |
|---|---|---|
| Multiple entity references | Pages with multiple entities of the same type (e.g. multiple performers, authors) may produce mixed results — the LLM may pull properties from different entities. | Adjust the highlighted region or use standard XPath where possible. |
| Initial crawl behavior | Results are not expected on the first crawl after deployment. | Expect results on the following crawl — this is consistent with LER behavior. |
| Preview latency | AI inference takes longer than XPath evaluation. If preview generation exceeds ~10 seconds, a timeout message displays while processing continues. | No action needed — results will appear when ready. |
| SHACL validation failures | Only SHACL-valid results populate properties. If validation fails, the field remains empty. | Review the highlighted region and confirm it contains the expected content type. Adjust the highlight scope if needed. |
| No manual cache clearing | There is no in-product mechanism to clear the cache or force regeneration. | Cache clears automatically when XPath or property path changes. |
| Rate limiting (planned) | Per-account daily token limits and Bedrock cost alarms are planned but not yet implemented. No customer-facing usage visibility exists today. | Use Adaptive Mapping selectively and avoid enabling it broadly on large, unvalidated page sets. |
| Sub-templates with multiple entity references | Adaptive Mapping may struggle to distinguish between multiple references to the same entity type within a sub-template. | Test carefully; prefer XPath for these scenarios where feasible. |
Frequently Asked Questions
Can Adaptive Mapping be enabled on any highlight?
No. Adaptive Mapping is available only for TagXPath highlights in Advanced Edit. It is not available on other highlight types.
Does Adaptive Mapping replace XPath?
No. XPath remains the preferred extraction method whenever a reliable expression can be authored. Adaptive Mapping should only be used when XPath is not practical.
Is Adaptive Mapping the same as the Template Generator?
No. The Template Generator creates template suggestions by analyzing multiple pages. Adaptive Mapping is an extraction method that the Template Generator may recommend when XPath is insufficient — but users can also apply it independently.
What happens if AI features are disabled for an account?
The Apply adaptive mapping option does not appear in the UI. If an existing highlight contains Adaptive Mapping settings, no AI extraction requests are made at run time.
Will Adaptive Mapping re-run every time markup regenerates?
No. Once a result is cached, subsequent markup regenerations serve the cached result. The LLM is only called again if the XPath or property path changes — or on the initial run when no cache exists.
How can I tell whether results are cached?
There is currently no visual indicator. If neither the XPath nor the property path has changed since the previous run, the cached result is used.
What is the cost per Adaptive Mapping call?
Specific per-call pricing is not yet finalized. Adaptive Mapping uses Amazon Bedrock and is more resource-intensive than standard XPath extraction. Cost is one of the reasons it is positioned as a fallback rather than a default method.
Conclusion
Adaptive Mapping extends the Schema Highlighter Extension by providing an AI-assisted extraction method for page content that cannot be reliably mapped using XPath alone. Rather than replacing existing extraction workflows, it complements them by acting as an intelligent fallback for complex or inconsistent content.
After reading this article, you should be able to:
- Explain what Adaptive Mapping is and how it differs from standard XPath extraction
- Identify appropriate and inappropriate use cases
- Describe how content is generated, validated, and cached
- Set expectations with customers about crawl timing, preview latency, and rate limiting
- Distinguish Adaptive Mapping from the Template Generator
Was this article helpful?
That’s Great!
Thank you for your feedback
Sorry! We couldn't be helpful
Thank you for your feedback
Feedback sent
We appreciate your effort and will try to fix the article