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.
Arguments
- instrument
An
sframeobject created bysframe_instrument().- path
Character. The file path to write to. The
.sframeextension is appended automatically if not already present.- pretty
Logical. Whether to write formatted JSON with indentation. Defaults to
TRUE. Set toFALSEfor compact files.- overwrite
Logical. Whether to overwrite an existing file. Defaults to
FALSE.- new_instrument
Logical.
TRUEdeclares 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 withread_sframe()must have a newmeta$titleormeta$version, so 2 different files never claim to be one instrument. Defaults toFALSE.
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().
See also
read_sframe(), validate_sframe()
Other Design functions:
as_sframe(),
launch_builder(),
read_sframe(),
sframe_attention_check(),
sframe_branch(),
sframe_choice_set(),
sframe_conjoint_design(),
sframe_get_study(),
sframe_instrument(),
sframe_item(),
sframe_sampling_methods(),
sframe_scale(),
sframe_validation,
validate_sframe()
Examples
instr <- read_sframe(
system.file("extdata", "tourism_services_demo.sframe",
package = "surveyframe")
)
out <- write_sframe(instr, tempfile(fileext = ".sframe"))
sframe_show(out)