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 loudly instead of emitting a wrong schema.

Usage

S7_to_JSONSchema(
  x,
  id,
  title = NULL,
  description = "",
  base = NULL,
  required = NULL,
  record = FALSE,
  provenance_url = NULL,
  fold_refs = NULL,
  metrics_refs = NULL,
  extra = NULL,
  refs = NULL,
  array_refs = 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/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) rather than config, 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 rather than omitted. The difference between an input schema and a record schema is exactly this; membership is identical.

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.

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.

extra

Named list merged into the schema after generation, for cross-field constraints that are not per-property (e.g. an allOf of if/then clauses for kernel-specific SVM hyperparameters).

refs

Named character: Properties holding a nested config object, mapped to the $id of the schema for that config. Each emits a $ref (or oneOf: [null, $ref] when the property accepts NULL, detected from its S7 union), instead of requiring a PropertySpec. Names must match existing properties.

array_refs

Named character: As refs, for a property holding a list of such objects – one metrics object per resample, one model per fold. Each emits an array whose items are the $ref.

closed

Logical: If TRUE (default) the schema sets additionalProperties: false. Pass FALSE for leaves composed into a top-level-mode dispatcher, which enforces strictness 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/lightrf/v1/schema.json",
  base = Hyperparameters
)
} # }