Skip to contents

Validate a sitemap source against the schema, protocol, and classification rules

Source: R/validate-sitemap.R
validate_sitemap.Rd

The public validation entry point. Reads one or more sitemap sources — sitemap URLs or local sitemap files — runs every finding-producer over them (the XSD schema layer, the protocol/semantic layer, the byte-level classification layer, and, for a sitemap index, the bounded index-expansion layer), and assembles the results into the stable findings contract.

Usage

validate_sitemap(
  x,
  mode = c("strict", "non-strict"),
  user_agent = default_user_agent(),
  limits = fetch_limits(),
  index_limits = NULL,
  policy = request_policy()
)

validate_sitemaps(
  x,
  mode = c("strict", "non-strict"),
  user_agent = default_user_agent(),
  limits = fetch_limits(),
  index_limits = NULL,
  policy = request_policy()
)

Arguments

x

One or more sitemap URLs or paths to local sitemap files (.xml, .txt, .gz, or .tar.gz).

mode

"strict" (the default) or "non-strict". In non-strict, strict-only findings are dropped and schema violations are downgraded to warning; in strict, the documented info-to-warning codes are elevated.

user_agent

The User-Agent header for HTTP fetches. Defaults to the package User-Agent.

limits

Network limits for HTTP fetches, as from fetch_limits().

index_limits

Sitemapindex-expansion bounds (recursion depth and per-index child-count cap), as from index_limits(). Defaults to index_limits().

policy

A request policy applied to every HTTP hop (root, robots.txt, discovery, redirects, and index children). Defaults to the no-op policy.

Value

The findings tibble described in docs/findings-contract.md: the columns code, severity, layer, subject_type, subject_ref, message, evidence, mode, is_strict_only, and remediation_hint, in the contract's stable order. The same source and mode yield a row-for-row identical tibble across calls. A genuine transport, SSRF, or HTTP failure raises a classed error condition.

Details

The source is read once and branched on its sniffed format: an HTML document served where a sitemap was expected yields an UNSUPPORTED_HTML_MASQUERADE classification finding; a plain-text sitemap is checked line-by-line; an XML document is dispatched on its root element. An XML root that is neither urlset nor sitemapindex yields an UNSUPPORTED_ROOT finding rather than an error. A urlset is schema- and protocol-validated; a sitemapindex is schema-validated and recursively expanded (cycle-, depth-, and count-capped), with the traversal events surfaced as INDEX_* findings.

When x contains more than one source, inputs are normalized, deduplicated, and capped using the submitted-list source-record policy. Per-source failures are returned as fetch-layer findings and successful sources still contribute their findings. Scalar calls keep the stricter historical behavior: genuine transport, SSRF, or HTTP failures raise classed conditions.

Examples

xml <- paste0(
  '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">',
  '<url><loc>https://example.com/</loc>',
  '<priority>2.0</priority></url>',
  '</urlset>'
)
path <- tempfile(fileext = ".xml")
writeLines(xml, path)
validate_sitemap(path, mode = "non-strict")
#> # A tibble: 2 × 10
#>   code        severity layer subject_type subject_ref message evidence     mode 
#>   <chr>       <chr>    <chr> <chr>        <chr>       <chr>   <list>       <chr>
#> 1 SCHEMA_INV… warning  sche… field        sitemap://… Elemen… <named list> non-…
#> 2 PROTOCOL_P… error    prot… entry        sitemap://… <prior… <named list> non-…
#> # ℹ 2 more variables: is_strict_only <lgl>, remediation_hint <chr>

# Validate directly from a sitemap URL.
# validate_sitemap("https://example.com/sitemap.xml")