1 Introduction

croissant reads and writes metadata in the Croissant format, versions 1.0 and 1.1, and reads the records that the metadata describes into R tables.

1.1 Installation

Install the package from the rtemis R-universe repository:

install.packages(
  "croissant",
  repos = c(
    rtemis = "https://rtemis-org.r-universe.dev",
    CRAN = "https://cloud.r-project.org"
  )
)

or with pak:

pak::repo_add(rtemis = "https://rtemis-org.r-universe.dev")
pak::pak("croissant")

The development version installs from GitHub:

pak::pak("rtemis-org/croissant")

croissant imports data.table, jsonlite, openssl, S7, and rtemis.core. The suggested packages support specific operations:

Package	Required for
`jsonld`	Reading a document whose `@context` differs from the standard Croissant context
`arrow`	Reading and writing Parquet files, and `output = "arrow"`
`tibble`	`output = "tibble"`
`withr`, `testthat`	The package’s test suite

1.2 The Croissant format

A Croissant document is a JSON-LD object of type sc:Dataset. It has three layers.

Layer	Content	Croissant types
Metadata	Name, description, license, creators, citation, dates, Responsible AI properties	`sc:Dataset`
Resources	The files of the dataset: single files, archives, and sets of files matched by glob patterns	`cr:FileObject`, `cr:FileSet`
Structure	Record sets, their fields, and where each field’s values come from	`cr:RecordSet`, `cr:Field`

A field’s source names a file, a file set, or another field, together with an extract (a column, a JSONPath, or a file property such as the file name) and an optional sequence of transforms (a regular expression, a separator, a date format, or a JSONPath). A field’s references declares a join to a field of another record set.

The Croissant specification defines the vocabulary. The MLCommons Python library mlcroissant is the reference implementation; croissant follows its version 1.1.1 in the properties it types, the checks it applies, and the procedure by which it reads records.

1.3 Functions

Function	Purpose
`read_croissant()`	Read a document from a file, URL, JSON string, or Hugging Face path into a `Croissant` object
`write_croissant()`	Write a `Croissant` object as JSON-LD
`validate_croissant()`	Check a document or object and return every issue as a `CroissantIssues` object
`is_valid()`	Test whether a `CroissantIssues` object holds no error
`read_record_set()`	Read the records of one record set as a data.table, tibble, data.frame, or arrow Table
`croissant_from_data()`	Write a table to CSV or Parquet and return metadata that describes it
`read_croissant_hf()`	Read the Croissant metadata of a Hugging Face dataset
`hf_download()`	Download and verify one file of a Hugging Face dataset
`croissant_context()`	Return the standard JSON-LD context of a Croissant version

The S7 classes Croissant, FileObject, FileSet, RecordSet, Field, ParentField, Source, Extract, Transform, Person, Organization, and CreativeWork represent the nodes of a document. Metadata objects describes them.

1.4 Example

The following example writes a table to CSV, creates metadata for it, validates the metadata, writes it to disk, and reads the records back.

library(croissant)

dir <- file.path(tempdir(), "observations")
dir.create(dir, showWarnings = FALSE)

df <- data.frame(
  id = 1:5,
  species = factor(c("Adelie", "Gentoo", "Adelie", "Chinstrap", "Gentoo")),
  bill_mm = c(39.1, 46.5, 40.3, 49.0, 47.2),
  male = c(TRUE, FALSE, NA, TRUE, FALSE),
  observed = as.Date("2026-01-01") + 0:4
)

x <- croissant_from_data(
  df,
  file = file.path(dir, "observations.csv"),
  name = "observations",
  description = "Bill length of five penguins.",
  license = "CC0-1.0",
  cite_as = "Example observations (2026).",
  date_published = "2026-10-27",
  dataset_version = "1.0.0"
)
x

<Croissant>
  name: observations
  version: Croissant 1.1
  distribution: 1 FileObject
  record sets: 1
    default: 5 fields

validate_croissant() returns every issue found; this metadata has none.

validate_croissant(x)

<CroissantIssues>
  0 errors, 0 warnings

write_croissant() writes the metadata next to the data file, where the relative contentUrl observations.csv resolves.

metadata <- file.path(dir, "croissant.json")
write_croissant(x, metadata)

read_record_set() reads the file, applies each field’s data type, and returns one column per field, named by field @id.

read_record_set(metadata, "default")

   default/id default/species default/bill_mm default/male default/observed
        <int>          <char>           <num>       <lgcl>           <Date>
1:          1          Adelie            39.1         TRUE       2026-01-01
2:          2          Gentoo            46.5        FALSE       2026-01-02
3:          3          Adelie            40.3           NA       2026-01-03
4:          4       Chinstrap            49.0         TRUE       2026-01-04
5:          5          Gentoo            47.2        FALSE       2026-01-05

The following chapters describe each step: the object model, reading and writing, validation, reading records, creating metadata from data, and Hugging Face datasets.