Generate a config family's dispatcher JSON Schema — S7_dispatcher

Assembles the <family>/v1 schema for a config family: an object holding the discriminator (algorithm, type, ...), the properties the family base declares for every variant, and an allOf of if/then clauses that apply the selected variant's leaf schema (<family>/<variant>/v1) to the whole object. The discriminator enum, the leaf $ref URLs and the allOf table are all derived from the classes, so the dispatcher cannot drift from the leaves it dispatches to.

Usage

S7_dispatcher_JSONSchema(
  classes,
  id,
  discriminator = "algorithm",
  base = NULL,
  title = NULL,
  description = "",
  discriminator_description = "Algorithm name.",
  record = FALSE,
  instance_schema_url = NULL
)

Arguments

classes: List of S7 classes: the family's per-variant subclasses (each carries a computed constant discriminator property).
id: Character: Dispatcher $id URL (e.g. "https://schema.rtemis.org/decomposition/r/v1/schema.json").
discriminator: Character: Name of the property that selects the variant (e.g. "algorithm", "type").
base: Optional S7 class: The family base class. Its own prop_*-declared properties are shared by every variant, so they are emitted here, once (see Details).
title: Optional Character: Schema title.
description: Character: Schema description. If empty, omitted. The shape rule – settings are siblings of the discriminator – is appended, so every family states it the same way.
discriminator_description: Character: Description of the discriminator property.
record: Logical: If TRUE, dispatch to the variants' record schemas (<family>/<variant>/v1/record.json), and require every property the dispatcher itself declares. The discriminator is required either way.
instance_schema_url: Character or NULL: If set, adds a $schema const property so instances can self-identify.

Value

Named list: the dispatcher JSON Schema. Serialize with write_JSONSchema.

Details

The leaf URLs are derived from id: for a dispatcher .../<family>/v1/schema.json, variant A maps to .../<family>/<tolower(A)>/v1/schema.json – matching S7_to_JSONSchema's id convention for the leaves.

One shape, matching how every family serializes (dispatched_props()): the variant's settings are siblings of the discriminator. A document holding only the discriminator is that variant with every default, so "nothing set" is said by absence, as a delta config says everything else, and a writer has no empty settings object to emit.

Each then is exactly the leaf $ref, applied to the whole object; readers key on that. additionalProperties is evaluated per schema and would not see the leaf's properties, so strictness comes from draft 2020-12's unevaluatedProperties: false, which does account for properties evaluated by the applied $ref. Leaves must therefore be generated open (closed = FALSE in S7_to_JSONSchema) so they compose.

The leaf's keys and the dispatcher's are disjoint by construction: base subtracts every base property, the discriminator included, from each leaf, so a setting can never land on a key the dispatcher declares.

base closes the loop with S7_to_JSONSchema's base argument, which subtracts the family base's properties from every leaf: the dispatcher adds them back at the top level, from the same PropertySpec, so the shared fields are declared once. Base properties carrying no spec are class machinery (a computed settings list, run state) and are skipped, as is the discriminator, which is generated from the variant enum.

Author

EDG

Examples

if (FALSE) { # \dontrun{
schema <- S7_dispatcher_JSONSchema(
  classes = list(PCAConfig, ICAConfig),
  id = "https://schema.rtemis.org/decomposition/r/v1/schema.json",
  base = DecompositionConfig
)
} # }