Skip to contents

Serialises an sframe instrument object to a UTF-8 JSON file with a SHA-256 integrity hash. The instrument is always validated before writing, and writes an instrument that passes validation. The hash is computed over the content with hash.value set to an empty string, in the canonical form of RFC 8785, the JSON Canonicalization Scheme: keys sorted, numbers in their shortest form and whitespace removed. It identifies content independently of the exact bytes, and SurveyBuilder and the verifier page on the package website compute the same hash. An NA is written as null where the published schema allows null for that field. Elsewhere, the function names and rejects NA or a number outside JSON's finite range, such as Inf.

Usage

write_sframe(
  instrument,
  path,
  pretty = TRUE,
  overwrite = FALSE,
  new_instrument = FALSE
)

Arguments

instrument

An sframe object created by sframe_instrument().

path

Character. The file path to write to. The .sframe extension is appended automatically if not already present.

pretty

Logical. Whether to write formatted JSON with indentation. Defaults to TRUE. Set to FALSE for compact files.

overwrite

Logical. Whether to overwrite an existing file. Defaults to FALSE.

new_instrument

Logical. TRUE declares that the content is a new instrument, separate from the one it was read from, so an amendment is unnecessary. The instrument must carry an empty amendment log, and an instrument read with read_sframe() must have a new meta$title or meta$version, so 2 different files never claim to be one instrument. Defaults to FALSE.

Value

The file path, invisibly.

Details

The hash object is {"algo": "sha256", "value": ..., "canonical": "rfc8785"}. canonical names the canonical form the hash was taken in. It sits inside the hashed content, so changing it after writing breaks the hash.

Revisions and the amendment log

Writing checks the amendment log recorded by amend_sframe(). Each entry must follow the one before it, the instrument must still match its last recorded amendment, and an instrument read with read_sframe() must keep every amendment it was read with. Content changed since it was read is refused unless the change was recorded with amend_sframe(). To publish changed content as a different instrument, remove its amendment log and set new_instrument = TRUE.

These are checks on the content in hand. The hash is unsigned and can be recomputed by anyone who edits a file, so it establishes content integrity. Use a separate signing record to establish who wrote an instrument and when.

The link between an instrument and the file it was read from is an attribute, sframe_origin, that read_sframe() sets. These checks rest on it. The package's own functions keep it, among them validate_sframe(), as_sframe(), sframe_drop_items(), sframe_add_references(), sframe_plan<- and sframe_add_model(), as do $<-, modifyList() and saveRDS() with readRDS(). Base R that builds a new list from the parts drops it, such as x[names(x)], c(x) or lapply() over the fields: the result is an instrument built from its parts, and its changes are then written outside the amendment record. Change a read instrument's fields in place, and record the change with amend_sframe().

Examples

instr <- read_sframe(
  system.file("extdata", "tourism_services_demo.sframe",
              package = "surveyframe")
)
out <- write_sframe(instr, tempfile(fileext = ".sframe"))
sframe_show(out)