Skip to contents

Convert an S7 class built with prop_* factories to a JSON Schema

Source: R/010_Props.R
S7_to_JSONSchema.Rd

Walks the class's properties, reads each attached PropertySpec, and assembles a draft 2020-12 JSON Schema. Which properties take part is decided by their declared role (see prop_role()), not by a list kept here: "config" and "state" properties are generated from their spec, state being marked readOnly, while "computed" and "r_only" properties are omitted – the first because everything it derives from is published, the second because it has no wire form at all. A spec-less property with no role is an error, so a class that drifts from the factory vocabulary fails schema generation.

Usage

S7_to_JSONSchema(
  x,
  id,
  title = NULL,
  description = "",
  base = NULL,
  required = NULL,
  record = FALSE,
  asserted = FALSE,
  provenance_url = NULL,
  session_url = NULL,
  fold_refs = NULL,
  metrics_refs = NULL,
  metrics_ref = NULL,
  reference_urls = NULL,
  closed = TRUE,
  instance_schema_url = NULL
)

Arguments

x

S7 class (e.g. LightRFHyperparameters).

id

Character: Schema $id URL (e.g. "https://schema.rtemis.org/hyperparameters/r/lightrf/v1/schema.json").

title

Character: Schema title. Defaults to the class name.

description

Character: Schema description. If empty, the "description" keyword is omitted from the schema.

base

S7 class or NULL: The family base class, whose inherited properties are machinery (tuned, resampled, the computed payload list) and are omitted. NULL for a flat config that has no family base.

required

Character: Names of required properties. Default NULL: all optional, so omitted fields fall back to their setup_* defaults on read (matching write_config's compaction). Ignored when record is TRUE.

record

Logical: If TRUE, emit the record form of the schema: the same properties, but every one required. A record states what a run actually used, so nothing in it may fall back to a reader's defaults – an unset value is written as an explicit null. The difference between an input schema and a record schema is exactly this; membership is identical.

asserted

Logical: If TRUE, emit an assertion schema: the input form, but with every property required. For a results class – a document rtemis produces rather than one a caller authors, and which has no record sibling to carry the requirement. The config contract's reason for omitting required is that a config is a partial expression of intent; a results document asserts fact, so the record's rule applies to it and not the config's. Mutually exclusive with record.

provenance_url

Character or NULL: If set (and record is TRUE), adds a required provenance property referencing that schema. Only a top-level record carries it; a nested one inherits its parent's.

session_url

Character or NULL: If set (and record is TRUE), adds a required, nullable session property referencing that schema – the reference to the execution graph written beside the record. Nullable because a run can produce no session: a pipeline result records none, and a model fitted before sessions existed has none to write.

fold_refs

Named character or NULL: If set (and record is TRUE), adds a required folds array whose entries reference these record schemas. Only a record of a run that fits models per resample carries one.

metrics_refs

Named character or NULL: If set (and record is TRUE), adds the required metrics / metrics_sd headline blocks, and references these metrics schemas from each fold's own metrics.

metrics_ref

Character or NULL: If set (and record is TRUE), adds a required, nullable metrics property referencing that one schema. For a run whose result is a single metrics object; mutually exclusive with metrics_refs.

reference_urls

Optional named character: Publication URLs keyed by qualified class identity. If omitted, derived from the package catalog.

closed

Logical: If TRUE (default) the schema sets additionalProperties: false. Pass FALSE for a family leaf, which its dispatcher composes into one object and closes with unevaluatedProperties instead (see S7_dispatcher_JSONSchema).

instance_schema_url

Character or NULL: If set, adds a $schema const property (instances self-identify, as in the config families).

Value

Named list: the JSON Schema. Serialize with write_JSONSchema.

Author

EDG

Examples

if (FALSE) { # \dontrun{
schema <- S7_to_JSONSchema(
  LightRFHyperparameters,
  id = "https://schema.rtemis.org/hyperparameters/r/lightrf/v1/schema.json",
  base = Hyperparameters
)
} # }