R/tableschema.r.R

In frictionlessdata/tableschema-r: Table Schema 'Frictionless Data'

#' @title Table Schema Package
#'
#' @description Table class for working with data and schema
#'
#' @section Introduction:
#' Table Schema is a simple language- and implementation-agnostic way to declare a schema for tabular data. It is well suited for handling and validating tabular data in text formats such as CSV, but its utility extends to many applications where a portable schema format is beneficial.
#'
#'
#' @section Tabular data:
#' Tabular data consists of rows, where each row contains a consistent set of fields (columns). In CSV or spreadsheet formats, the first row is typically used as the header row. In other data systems like SQL, headers (field names) are explicitly defined.
#'
#' @section Physical and logical representation:
#' The \emph{physical representation} of tabular data refers to its format as stored on disk (e.g., CSV, JSON), where data may or may not carry type information. In contrast, the \emph{logical representation} reflects how data is structured and typed after parsing, as defined by the schema specification. 
#'
#' For example, \code{constraints} should be applied to the logical representation, while \code{missingValues} are handled during the parsing of the physical format.
#'
#' @section Descriptor:
#' A Table Schema is defined using a descriptor, which \code{MUST} be a JSON object (see \href{https://www.ietf.org/rfc/rfc4627.txt}{RFC 4627}). The descriptor \code{MUST} include a \code{fields} property (array of field descriptors) and \code{MAY} include additional optional properties.
#'
#' @section Field Descriptors:
#' See \code{\link{Field}} class.
#'
#' @section Types and Formats:
#' See \code{\link{Types}} class.
#'
#' @section Constraints:
#' See \code{\link{Constraints}} class.
#'
#' @section Other Properties:
#' Table-level properties include keys, missing value indicators, and metadata.
#'
#' @section Missing Values:
#' Missing values may be indicated using empty strings or placeholders such as \code{"-"} or \code{"NaN"}. The \code{missingValues} property defines which string values are treated as nulls, and applies during parsing.
#'
#' \code{missingValues} \code{MUST} be a list of strings. For example:
#' \itemize{
#'   \item \code{missingValues = list("")}
#'   \item \code{missingValues = list("-")}
#'   \item \code{missingValues = list("NaN", "-")}
#' }
#'
#' @section Primary Key:
#' The \code{primaryKey} property \code{MAY} be:
#' \itemize{
#'   \item A string (for a single field).
#'   \item A list of strings (for a composite key).
#' }
#'
#' @section Foreign Keys:
#' The \code{foreignKeys} property, if present, \code{MUST} be a list of foreign key objects. Each \code{foreignKey} object \code{MUST} include:
#'
#' \describe{
#'   \item{\code{fields}}{A string or list of strings specifying the source field(s).}
#'   \item{\code{reference}}{An object with:
#'     \describe{
#'       \item{\code{resource}}{The referenced resource name. Use \code{""} for self-referencing keys.}
#'       \item{\code{fields}}{The target field(s) on the referenced resource.}
#'     }
#'   }
#' }
#'
#' \strong{Comment:} Foreign keys create links between Table Schemas. Typically, schemas are part of a larger Data Package, where resources and schemas are associated.
#'
#' @section Details:
#' \itemize{
#'   \item \href{https://CRAN.R-project.org/package=jsonlite}{jsonlite} is used to convert JSON to R list objects. Inputs can be JSON strings, lists, or files; outputs are R lists.
#'   \item \href{https://CRAN.R-project.org/package=future}{future} allows asynchronous creation of Table/Schema objects. Use \code{value()} to retrieve results.
#' }
#'
#' See examples in individual functions for using `jsonlite` and `future` with \code{tableschema.r}.
#'
#' The term "array" in JSON corresponds to R \code{list} objects.
#'
#' @section Language:
#' The key words \code{MUST}, \code{MUST NOT}, \code{REQUIRED}, \code{SHALL}, \code{SHALL NOT}, \code{SHOULD}, \code{SHOULD NOT}, \code{RECOMMENDED}, \code{MAY}, and \code{OPTIONAL} are interpreted as described in \href{https://www.ietf.org/rfc/rfc2119.txt}{RFC 2119}.
#'
#' @seealso
#' \href{https://specs.frictionlessdata.io//table-schema/}{Table Schema Specifications}
#'
"_PACKAGE"

NULL