transformations

AbsReturns the absolute value of `value`. Unblocks the magnitude- vs-threshold pattern (`abs(delta) >= 0.005`) without the `Multiply(x, x) >= threshold *…AccumulateExpression evaluated once per source element with `stateVar` and `elementVar` in scope. Its result is BOTH the value emitted at this position AND the next…AddReturns left + right.All StatementsYields the list of every statement on a subject. Source typically resolves to a SubjectKanonak (e.g. a VarRef to `input` inside an InstanceTransformation rule,…AlternateAndReturns true when EVERY operand evaluates to true. Short- circuits on the first non-true operand (so later operands with side-effecting Traverse / ResolveRef…Arith LeftLeft operand expression. Must yield a number at runtime.Arith RightRight operand expression. Must yield a number at runtime.Artifact NameExpression that yields the Artifact's filename stem (no directory, no extension). Evaluated in the same environment as `rule` — `input` for…AscendingSort smallest-to-largest (or earliest-to-latest for date-typed properties).AST ClassThe docast Class to instantiate (Document, Heading, RawBlock, etc.).AST Field BindingA single field-bind pair used inside BuildAstNode.set.AverageReturns the arithmetic mean of `source` elements as an xsd:decimal. Result is always decimal — even when source elements are integer, average of [1, 2] yields…Backend URIStable string identifier the runner uses to look up the backend implementation. NOT a Kanonak URI — backends are TS code, not ontology entities.Binary ArithmeticAbstract intermediate. Any binary numeric operation with `arithLeft` + `arithRight` operands. Not directly instantiable — authors instantiate one of Add /…Binary ComparisonAbstract intermediate. Any two-operand boolean comparison — Equals / GreaterThan / LessThan / GreaterThanOrEqual / LessThanOrEqual. Not directly instantiable;…Bind ValueExpression whose result becomes the field's value.BodyThe Expression body invoked when this fragment is called.Boolean LiteralA constant boolean value (true or false).Boolean Literal ValueBoolean LogicAbstract intermediate for n-ary boolean composition (And, Or). Both subclasses short-circuit — And stops on the first non- true operand; Or stops on the first…Build AST NodeConstructs a docast AST node of the declared `astClass` and binds fields via the `set` list. The result is an AST node ready for backend serialization (top of…By NameExpression yielding a string — the predicate local name to match. Required.By PropertyReference to the Property whose value is read off each input as the sort key.Call FragmentInvokes a named ExpressionFragment by URI reference.Check ExprCompare LeftLeft operand expression. Required.Compare RightRight operand expression. Required.ConcatConcatenates the string results of `parts`, in order, with no separator.ConditionContainsReturns true when any element of `haystack` equals `needle`, using the same semantics as `tx.Equals` (URI equality for refs/subjects, value equality for…CountReturns the cardinality of `source` as an integer. Source elements are not inspected — every list element counts, regardless of type.Date FormatReformat an ISO 8601 datetime string into a named human-readable form. Source must yield a string parseable by JS Date (ISO 8601 is the safe lingua franca).…Date FormatNamed output format. Supported values: - `iso-date` → 2024-01-15 - `iso-datetime` → 2024-01-15T08:30:00Z - `short-date` → Jan 15 - `long-date`…Date SourceExpression yielding the ISO 8601 datetime string to reformat.Decimal LiteralA constant decimal (non-integer-restricted) numeric value. Distinct from IntegerLiteral so authors can express fractions and currency amounts without…Decimal Literal ValueDescendingSort largest-to-smallest (or latest-to-earliest for date-typed properties).Display LabelResolves a presentation label for `labelTarget` by reading `labelSource` off it. Falls back to the entity's local name when the source property is absent.Distinct ByIterates `source`, evaluates `distinctKey` per element with `loopVar` bound, and keeps the FIRST element seen for each distinct key value. Returns the…Distinct KeyPer-element key expression. Elements with equal key values are deduplicated.DivideReturns left / right. Divide-by-zero raises a runtime error — guard with a When if the right operand can be zero.DynamoDB JSONDynamoDB attribute-value JSON serialization. The backend walks docast.Document.metadata (the StructuredMap channel) and emits the `{ "S": … } / { "N": … } / {…Element VarName of the variable bound to the current element inside `step`. Required.Else BuildEmitPer-element body. Must yield a string.EqualsReturns true when `compareLeft` and `compareRight` evaluate to equal values. URI equality for ReferenceKanonak / SubjectKanonak operands (compares publisher +…ExpressionAbstract base for every expression node in a transformation's `rule` or `artifactName` tree. Concrete subclasses below add the properties relevant to their…Expression FragmentA named, reusable Expression body. Authored as a top-level subject; invoked via a CallFragment node that references it by URI. Cycles in fragment calls are…FallbackEvaluates `primary`; if the result is undefined or empty, evaluates and returns `alternate`. Useful for "use the rdfs:label, otherwise fall back to the local…FieldThe docast Property being bound.FilterIterates `source`, evaluates `predicate` per element with `loopVar` bound, and returns the subset of elements for which the predicate yields a truthy value.…First VarName of the variable bound to the first (earlier) element of each consecutive pair inside `pairBody`. Required.For EachIterates `source`, evaluates `emit` per element with `loopVar` bound, and concatenates the string results. Use for stringification where order matters and the…Format OverridePer-output-format adjustments applied during serialization. Backends that accept overrides read these from the transformation at render time; backends that…Format OverridesPer-format adjustments (metadata key filtering, key renames, trailing-newline policy) applied by the backend during serialization.Format TargetThe OutputFormat this override applies to.Fragment RefFrom KeyThe original key as it appears in the AST.Get Statement By NameReturns the first statement on `inSubject` whose predicate's local name matches `byName`, or undefined when no match exists. Used by the universal renderer's…Greater ThanReturns true when `compareLeft > compareRight` numerically. Both operands must be numbers; mixed kinds or non-numeric operands return false. Use…Greater Than Or EqualReturns true when `compareLeft >= compareRight` numerically. Same operand semantics as `GreaterThan`.HaystackExpression yielding the list to search. Required.HTMLHTML serialization. Backend wraps RawBlock content directly.In SubjectExpression yielding a SubjectKanonak or EmbeddedKanonak whose statements will be searched. Required.Initial StateExpression evaluated once at scan start to seed the running accumulator. The body's first iteration sees this value bound to `stateVar`. Required.Input PatternSelector that picks which input subjects this Transformation operates on.Input PatternSubject selector. Picks instances of `matchesClass` that pass every `requires` predicate, and (for SetTransformation) optionally orders them by a list of…Instance TransformationPer-instance transformation. The runner finds every input matching the InputPattern, then evaluates `rule` and `artifactName` once per match with `input`…Integer LiteralA constant integer value.Integer Literal ValueIs BooleanBoolean predicate. Returns true iff `kindCheck` evaluates to a runtime boolean. Companion to IsReference / IsEmbedded / IsList for leaf-level dispatch in…Is EmbeddedBoolean predicate. Returns true iff `kindCheck` evaluates to an EmbeddedKanonak (an inline resource owned by its parent). Used by renderers to decide whether…Is ListBoolean predicate. Returns true iff `kindCheck` evaluates to a list (array). Used by renderers and analyzers to decide whether to iterate (ForEach / ListMap /…Is NumberBoolean predicate. Returns true iff `kindCheck` evaluates to a runtime number (integer or decimal). Companion to IsReference / IsEmbedded / IsList for…Is ReferenceBoolean predicate. Returns true iff `kindCheck` evaluates to a ReferenceKanonak (a value that points at another resource by URI). Used by renderers to decide…Is SetBoolean predicate. Evaluates `checkExpr`; returns true when the result is non-undefined and non-empty (non-empty string, non-empty list). Used as the condition…Is StringBoolean predicate. Returns true iff `kindCheck` evaluates to a runtime string. Companion to IsReference / IsEmbedded / IsList for leaf-level dispatch in…Item IndexExpression yielding a non-negative integer. The 0-based position in the source list to return. Required.Iterating ExpressionAbstract intermediate for expressions that bind each element of `source` to a loop variable and evaluate a per-element body. The body's shape and the way the…JoinConcatenates the string elements of `source` with `separator` between adjacent pairs. Distinct from Concat (which takes individually authored parts) — Join…JSONJSON serialization.KeyKind CheckThe Expression whose runtime value's kind is being checked. Required for every KindPredicate subclass.Kind PredicateAbstract intermediate for boolean predicates that branch on the runtime kind of a value (IsReference / IsEmbedded / IsList). Each subclass shares the same…Label SourceLabel TargetLess ThanReturns true when `compareLeft < compareRight` numerically. Same operand semantics as `GreaterThan`.Less Than Or EqualReturns true when `compareLeft <= compareRight` numerically. Same operand semantics as `GreaterThan`.LetBinds `letName` to the result of evaluating `letValue` in the current environment, then evaluates `letBody` in the extended environment. Returns the body's…Let BodyThe Expression evaluated in the extended environment. Its result is what Let returns. Required.Let NameThe variable name to bind. Required. Subsequent VarRef expressions inside `letBody` with this name resolve to the bound value.Let ValueThe Expression whose evaluated result becomes the bound variable's value. Required.List AggregateAbstract intermediate. Reductions that take a list and yield a scalar (cardinality, sum, min, max). Subclasses add no extra properties — the difference is in…List Item AtReturns the source list's element at the (0-based) `itemIndex`, or undefined if the index is out of bounds. Used to access individual positions of a…List MapIterates `source`, evaluates `mapBody` per element with `loopVar` bound, and collects the results into a new list (preserving order). Use when the result feeds…List-Sourced ExpressionAbstract intermediate. Captures the "expression that consumes a list-yielding source" pattern. Not directly instantiable — authors instantiate one of the…Loop VarName under which each element of `source` is bound while the body expression evaluates. Local to the iterating expression — does not leak into surrounding…Map BodyMarkdown (with frontmatter)Markdown body preceded by a YAML or TOML frontmatter block.Matches ClassThe Class whose instances are eligible. The runner uses subclass-aware matching (RDFS rdfs9 semantics), so instances of any subclass of `matchesClass` qualify.MaxReturns the largest numeric element of `source`. Same numeric and empty-source contract as Min.MembersMetadata KeysOptional include-list of metadata entry keys to emit, in order. Keys outside this list are skipped. Multi-valued; if absent, the backend emits all metadata…Metadata RenamesAST-key → emitted-key renames. Multi-valued.MinReturns the smallest numeric element of `source`. Elements must be numeric. Empty source raises a runtime error (the minimum of the empty set is undefined;…MultiplyReturns left * right.NameLocal name of the referenced transformation within its package.NeedleExpression yielding the value to search for. Required.NegateReturns `-value` (unary negation).Norm KindNorm SourceNormalizeApplies a named normalization (`normKind`) to a string-yielding source.Normalize KindDiscriminator vocabulary for the Normalize expression.NotReturns the boolean negation of `operand`. Strict: if `operand` evaluates to true, returns false; if false, returns true; any other value returns undefined…Omit WrapperWhen true, the backend suppresses its default chrome — e.g. the HTML backend's `<!DOCTYPE html>...<style>...</style>...</html>` shell and the `<dl…OperandBoolean expression to negate. Required.OperandsList of boolean expressions. Authored as a YAML list. Empty operand lists evaluate to the identity of the operation: `And` over [] is true (vacuous); `Or` over…OrReturns true when ANY operand evaluates to true. Short- circuits on the first true operand. Empty operand list returns false (vacuous).OrderSort direction — references one of the named SortOrder instances.Output FormatA target serialization format. Each named instance carries a `backendUri` that the runner uses as a registry key to find the IDocumentAstBackend that knows how…OutputsThe set of OutputFormats this transformation can render. The runner rejects requests to render in a format outside this set.PackagePackage name segment (e.g. `universal-derivations`).Pair BodyPer-pair body. Evaluated once per consecutive pair with both `firstVar` and `secondVar` in scope. The result is collected in source order. Required. (Distinct…Pairwise MapErgonomic shortcut for the dominant `WindowedMap windowSize: 2` case. For a source `[s_0, s_1, …, s_{n-1}]`, evaluates `pairBody` once per consecutive pair…PartitionA single group produced by a PartitionBy expression. Holds the partition key value and the list of source elements that share it. Authors read `key` and…Partition ByOptional. Reference to a Property used to partition the matched input set for fan-out. When set, the runner reads this property off each matching input, groups…Partition ByIterates `source`, evaluates `partitionKey` per element with `loopVar` bound, and groups elements by their key value. Returns a list of Partition embeddeds,…Partition KeyPer-element key expression. Elements with equal key values land in the same partition.PartsPlain MarkdownMarkdown body only — no frontmatter, no metadata block.PredicatePer-element predicate. Must yield a boolean.Predicate OfExpression yielding the statement whose predicate to extract. Typically a VarRef to the loop variable of an iteration over AllStatements.PrimaryProperty ReadReads the value of `readProp` off the subject yielded by `readSource`. For a multi-valued property, returns the value list.PublisherPublisher segment of the referenced transformation's URI (e.g. `kanonak.org`).Read PropertyRead SourceRef ToRename EntryA single AST-key → emitted-key rename pair.Render FormatRender FormatDiscriminator vocabulary for the RenderMarkdown expression.Render HTMLRender the value to HTML, with [[references]] as <a> links.Render MarkdownReads a core-prose datatype value (Markdown / SubstitutableString) off the subject yielded by `renderSource`, by the property `renderProp`. Substitutes every…Render MarkdownKeep the value as CommonMark, rewriting [[references]] to [label](url) canonical-URL links.Render PropertyRender SourceRequiresProperties that must each resolve to a non-empty value on a matching instance. Subjects missing any required property are silently skipped — they do not match.…Resolve RefDereferences a reference-yielding expression to the target subject. Returns undefined when the reference doesn't resolve.Resolve SourceReverseReturns the source list with its elements reversed. Useful for rendering newest-first orderings, latest-snapshot-on-top indexes, etc., when the source is in…RuleExpression that yields a docast.Document. The runner hands the Document to the format-specific backend, which serializes it to bytes for the target output…ScanRunning-aggregation iterator. For a source `[s_0, s_1, …, s_{n-1}]`, evaluates `initialState` once at scan start to seed the accumulator, then evaluates…Second VarName of the variable bound to the second (later) element of each consecutive pair inside `pairBody`. Required.SeparatorSetField-by-field bindings that populate the constructed AST node.Set TransformationAggregate transformation operating on the matched SET of inputs. Without `partitionBy`, the runner evaluates `rule` and `artifactName` once with `inputs`…Sort ByOrdered list of sort criteria. The first SortKey is the primary sort; subsequent SortKeys break ties. No default sort — when sortBy is absent the runner binds…Sort KeyA single sort criterion: the property to read off each input plus the sort direction. Properties whose value is a list or a reference are not sortable — the…Sort OrderDiscriminator vocabulary for sort direction. Two named instances — ascending and descending — exhaust the set; subclasses are not expected.SourceExpression that yields the list this list-sourced expression operates on. Typically a VarRef to `inputs`, a PropertyRead that returns a list-valued property,…State VarName of the variable bound to the running accumulator inside `step`. Initially holds `initialState`; after each step it holds the previous step's result.…Statement ObjectReturns the raw value of a statement (ReferenceKanonak / EmbeddedKanonak / list / scalar) without string coercion. Companion to StatementPredicate; replaces…Statement PredicateYields the predicate of a statement as a ReferenceKanonak. Typically composed with UriName or DisplayLabel inside a ForEach loop over AllStatements to render…Statement SourceThe Expression whose value is the statement to read. Required. Typically a VarRef bound to the loop variable of a ForEach over AllStatements.Statement ValueYields a string representation of the statement's object, dispatching on the statement subtype: - StringStatement / NumberStatement / BooleanStatement →…Statements OfExpression yielding the subject whose statements to enumerate. Must resolve to a Kanonak with a `statement[]` collection (Subject or Embedded). Otherwise the…StepString LiteralA constant string value.String Literal ValueStylesheetCSS stylesheet output. The backend walks docast.Document.children for the first RawBlock with mediaType=text/css and emits its rawContent verbatim. Used by…Subject OfSubject URIYields the full canonical URI of a subject as a string — `publisher/package@version/name`. Authors typically use this inside SetTransformation iteration to…SubtractReturns left - right.SumReturns the numeric sum of `source` elements. Elements must be numeric (xsd:integer or xsd:decimal); non-numeric elements raise a runtime error. Empty source…SVGSVG serialization for vector-graphics output.Then BuildThroughTo KeyThe key to emit in serialized output.TOMLTOML serialization.Trailing NewlineWhether to append a final newline to the serialized output.TransformationAbstract description of how to derive output Artifacts from input instances. Not directly instantiable — authors instantiate one of the two concrete subclasses…Transformation ReferenceA 4-tuple identifying a published Transformation by its canonical URI: publisher + package + version + name. Used by other vocabulary packages (e.g.…TraverseTwo-step traversal. Evaluates `traverseSource` to get a starting subject; reads `through` to get one or more intermediate subjects; evaluates `step` once per…Traverse SourceTrim EndStrip trailing whitespace and newlines.Unary Numeric OpAbstract intermediate for one-operand numeric operations (Abs, Negate). Operand must yield a number at runtime; non-numeric operands raise a runtime error…URI LiteralA constant URI reference to a named entity.URI NameYields the local name component of a URI-typed expression result. Works on any value that carries a name — a ReferenceKanonak (its target's local name), an…URI Name OfURI PackageYields the package segment of a URI-typed expression result. Same source-shape contract as UriPublisher / UriVersion.URI Package OfURI PublisherYields the publisher segment of a URI-typed expression result. Accepts the same kinds of sources as UriName / UriVersion / UriPackage — SubjectKanonak (via its…URI Publisher OfURI VersionYields the version segment of a URI-typed expression result as a `M.m.p` string. Returns the empty string when the source is versionless (an EntityUri or a…URI Version OfValueNumeric expression. Required.Value OfExpression yielding the statement whose object value to render. Typically a VarRef to the loop variable of an iteration over AllStatements.Var NameVar RefLooks up a name in the current evaluation environment. Standard bindings the runner provides: input — InstanceTransformation, the current instance.…VersionPinned semantic version, formatted `M.m.p` (e.g. `1.0.0`). Required — versionless references are intentionally not supported here.WhenConditional. Evaluates `condition`; if true, evaluates and returns `thenBuild`; else evaluates and returns `elseBuild` (or undefined if elseBuild is omitted).Window BodyPer-window body. Evaluated once per window position with `windowVar` bound to the current window list. Use `tx.ListItemAt` to access individual positions.…Window SizeNumber of consecutive elements visible at each iteration. Required; must be a positive integer >= 1. Authors typically use 2 (pairwise) or 3 (running-3 windows…Window VarName of the variable bound to each window inside `windowBody`. The bound value is a list of exactly `windowSize` elements from the source, in source order.…Windowed MapSliding-window iterator. For a sorted source `[s_0, s_1, …, s_{n-1}]` of length n and `windowSize: k`, evaluates `windowBody` once for each `i ∈ [0, n-k]` with…YAMLPure YAML serialization. The backend walks docast.Document.children for RawBlock(text/yaml) and emits the rawContent verbatim. Used by universal-derivations to…