% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/dataStructure.R
\name{dataStructure}
\alias{dataStructure}
\title{Retrieve a classification structure (levels and concepts) from a supported service}
\usage{
dataStructure(
  endpoint,
  prefix,
  conceptScheme = NULL,
  language = "en",
  showQuery = FALSE,
  return = c("summary", "details", "both"),
  timeout_sec = 60,
  retries = 3
)
}
\arguments{
\item{endpoint}{Character scalar. Accepted values are \code{"CELLAR"} or \code{"FAO"}.}

\item{prefix}{Character. A classification prefix used in the registry
(e.g. \code{"NACE"}, \code{"CPA"}, \code{"CN2022"}). Used to resolve the scheme.}

\item{conceptScheme}{Character or \code{NULL}. Optional alternative identifier
for the concept scheme. The resolver tries both \code{prefix} and \code{conceptScheme}
using basic normalization (case-insensitive; dot removal).}

\item{language}{Character scalar. Two-letter language code used to select
labels (default: \code{"en"}). Fallback chain: requested language -> English (\code{"en"})
-> no-language literal -> the local resource name.}

\item{showQuery}{Logical. If \code{TRUE}, the generated queries are emitted via
\code{message()} and also included in the returned list.}

\item{return}{One of \code{c("summary", "details", "both")}. Controls which table(s)
are fetched and returned.}

\item{timeout_sec}{Numeric. HTTP timeout in seconds. Default: \code{60}.}

\item{retries}{Integer. Number of automatic retries on transient HTTP errors.
Default: \code{3}.}
}
\value{
A \code{data.frame} (for \code{"summary"} or \code{"details"}), or a
\code{list(summary, details)} when \code{return = "both"}.

\strong{Columns:}
\itemize{
  \item All returned tables include a leading \code{Prefix} column (lower-case token).
  \item \code{summary}: \code{Concept_Scheme}, \code{Depth}, \code{Level}, \code{Count}.
  \item \code{details}: \code{Concept}, \code{Code}, \code{Label}, \code{Depth}, \code{Level},
        \code{BroaderList}, \code{BroaderCodeList}.
}

If \code{showQuery = TRUE}, the return value is a list containing:
\itemize{
  \item \code{resolved}: metadata (\code{endpoint}, inputs, \code{scheme_id}, \code{ns_uri}, and optionally \code{title})
  \item the query text (one or two elements depending on \code{return})
  \item the retrieved table(s)
}
}
\description{
Queries the selected service (e.g., CELLAR or FAO) to retrieve the structure of a
classification scheme (levels, depth, and concept rows), with language-aware
label fallback. You can return a compact summary table, a detailed
concept-level table, or both.

The function first resolves the input classification using the in-package registry
returned by \code{classificationList()}, then retrieves the structure and returns
it as data frames. Network errors are handled with retry logic.
}
\details{
\strong{Resolution of the scheme}

The function calls \code{classificationList(endpoint)} and tries to match either
\code{prefix} or \code{conceptScheme} using normalized keys. On success it extracts
the classification namespace and scheme identifier needed to compose requests.

\strong{Language fallback}

Labels for both the classification levels and concepts follow a multi-step
fallback: requested \code{language} -> \code{"en"} -> no-language literal -> local name.
}
\section{Errors and Warnings}{

\itemize{
  \item Errors if \code{endpoint} is not \code{"CELLAR"} or \code{"FAO"}, or if the
        scheme cannot be resolved from the registry.
  \item Warns (and still returns rows) if no explicit levels are declared.
  \item Propagates HTTP errors from the service after retry policy.
}
}

\examples{
\dontrun{
ds_cn <- dataStructure(
  endpoint      = "CELLAR",
  prefix        = "cn2022",
  conceptScheme = "cn2022",
  language      = "en",
  return        = "summary"
)
head(ds_cn)
}

}
\seealso{
\code{\link{classificationList}}
}
