Okyline Annex D Quick Reference - Internal References

Version: 1.8.0 Date: September 2026 Status: Draft

Companion to the Okyline Core Language Quick Reference. Covers reusable schema fragments ($defs), references ($ref), and template adaptation ($override, $amend, $remove).

D - Internal References ($defs / $ref)

Okyline supports reusable schema fragments to avoid duplicating the same structure across a document. You define templates once in $defs and reference them with $ref in two modes: property-level (a field whose type comes from a definition) or object-level (an object that includes all fields of a template). Included structures can be adapted with $override, $amend, or $remove.

D.1 Definition Repository - $defs

Declared at root level. Contains reusable schema fragments (objects or scalars):

{
  "$defs": {
    "Address": {
      "street|@ {2,100}": "12 rue du Saule",
      "city|@ {2,100}": "Lyon"
    },
    "Email|~$Email~ {5,100}": "[email protected]",
    "Percentage|(0..100)": 50
  }
}

Rules: First-level entries only (no nested paths). Resolution is case-sensitive.

A $defs entry’s key accepts the same constraint grammar as a field key (Core §4-5), except @ and #. This allows naming a collection type and using it through a &Name reference:

{
  "$oky": { "matrix|@ [*]": ["&Row"] },
  "$defs": {
    "Row|[*] -> (>=0)": [0]
  }
}

↳ matrix is List<List<int>>. Chains further (&Cell → &Row → &Matrix) to compose map-of-map, list-of-map, etc. at any depth.

D.2 Reference Syntax - &Name

&Address    → resolves to "Address" in $defs
&Email      → resolves to "Email" in $defs

↳ & = current document’s definition namespace. Unknown name → schema rejected.

D.3 Property-Level Reference

"address|@": "&Address"

↳ address uses Address schema, required (@ is local)

List of referenced elements:

"addresses|[1,10]": ["&Address"]

↳ Array of 1-10 elements, each validated against Address

Map of referenced elements:

"statsByRegion|[*:*]": { "region-1": "&Stat" }

↳ Map whose values are each validated against Stat

Polymorphic references (list or map, size > 1):

"events|@ [*]":       ["&Login", "&Logout"]
"indicators|@ [*:*]": { "k1": "&Counter", "k2": "&Gauge" }

↳ Each element / value matches any of the declared variants. All variants must be the same kind (all scalar or all object). Inline values can be mixed with refs. | $str disables &Name promotion on scalar and list fields, not on maps.

Constraint categories:

For a collection definition ("Row|[*] -> (>=0)"), its bounds, ! and -> constraints belong to the type and travel with &Row.

"primaryEmail|@": "&Email",
"backupEmail|?": "&Email"

↳ Same Email definition, different structural constraints per usage

D.4 Object-Level Reference - Structural Composition

{
  "$oky": {
    "Person": {
      "$ref": "&Address",
      "name|@ {2,50}": "Dupond"
    }
  }
}

↳ All Address fields injected into Person + local name field added

Rules: - $ref value = single reference string (one template only) - Object-level $ref MUST target an object definition - Object-level inclusion cycles → forbidden (detected at load time) - Recursion through a property or list/map element → allowed - Field collision → must use $override or $amend (otherwise rejected) - A template’s conditional rules, computes and $fields are injected together with its fields - A template’s $additionalProperties / $sequence are not inherited: the including object keeps its own or the global

D.5 Template Adaptation - $remove

{
  "AnonymousPerson": {
    "$ref": "&Person",
    "$remove": ["email", "ssn"]
  }
}

↳ Includes Person minus email and ssn

Rules: Array of field names. Each must exist in template. NOT permitted when template contains conditional rules or $compute.

D.6 Field Adaptation - $override / $amend

"fieldName | $override <constraints>": <value>
"fieldName | $amend <constraints>": <value>

Invariants preserved by both: field type, collection nature, $ref target.

{
  "Employee": {
    "$ref": "&Person",
    "name | $amend @": "John Doe",
    "salary|@ (>=0)": 3000
  }
}

↳ Person’s name|? {1,50} + $amend @ → effective name|@? {1,50} (added @, kept ? and {1,50})

On an object or collection field, $amend adapts the key only: value {} or [], everything below is kept. $override replaces the whole field.

"address | $amend @": {}

↳ address becomes required; its fields and rules are those of the base, untouched

D.7 Order of Application

1. Template injection - Resolve $ref, inject all fields
2. Removals - Apply $remove
3. Adaptations - Apply $override / $amend
4. Local additions - Add remaining local fields

D.8 Validation Entry Points - $entries

Declare additional validation entry points within a single schema. Each entry maps a public name to a local definition; consumers can validate against a specific entry rather than only the root $oky payload.

"$entries": {
  "AnimalCreate": "&Animal",
  "OrderCreate":  "&Order"
}

• Value form: &Name, a local definition or an imported alias. The external form &id.Name is not allowed here.
• Default validation target remains $oky when no entry name is supplied. A library that only publishes definitions writes "$oky": null.

Okyline® is a registered trademark of Akwatype.