Okyline Schema Language v1.3.0

Okyline is a declarative language for describing and validating JSON structures using inline constraints on field names. Schemas are valid JSON documents with real example values.

Okyline skill version : 1.7.0

⚠️ Before any schema generation

MANDATORY: Read the reference files BEFORE producing an Okyline schema:

1. references/syntax-reference.md — complete syntax of constraints
2. references/internal-references.md — $defs and $ref
3. references/conditional-directives.md — if conditional logic
4. references/expression-language.md — if $compute is necessary

Never generate a schema based solely on this SKILL.md file. The examples here are a summary, not an exhaustive reference.

$ref: when to use

Use $defs/$ref when:

1. Recursion (mandatory — only way to express recursive structures)
2. Repeated structures identical across multiple usages (e.g. Period, Address)
3. Template pattern — base structure specialized per usage via $override (e.g. Coding)
4. Explicit user request

Default → inline in $oky. Don't over-abstract — factorize only when it reduces real duplication or expresses a meaningful shared type.

Core Syntax

"fieldName | constraints | label": exampleValue

• fieldName: JSON field name
• constraints: Validation rules (space-separated)
• label: Optional human-readable description
• exampleValue: Determines the inferred type

If a label is present without constraints, use | |:

❌ "acheteur|Client" → "Client" parsed as constraint! ✅ "acheteur| |Client" → "Client" is the label

Minimal Schema Structure

{
  "$oky": {
    "name|@ {2,50}|User name": "Alice",
    "email|@ ~$Email~": "alice@example.com",
    "age|(18..120)": 30
  }
}

Essential Constraints

Contraintes numériques ouvertes

Quand une seule borne est nécessaire, utiliser les opérateurs de comparaison :

❌ Ne jamais inventer de syntaxe avec borne manquante : (0..), (..100) ✅ Utiliser les comparaisons : (>=0), (<=100)

❌ Ne jamais inventer borne manquante : (0..99999999), (-99999999..100) ✅ Utiliser les comparaisons : (>=0), (<=100)

⚠️ INVALID SYNTAX — Okyline does NOT support open ranges:

• ❌ (0..), (..100), (1..*), (0..*)
• These will cause validation errors

Taille de collection illimitée

Utiliser * pour indiquer "pas de limite" :

❌ Ne jamais omettre une borne : [1,], [~pattern~:] ✅ Utiliser * explicitement : [1,*], [~pattern~:*]

Built-in Formats

Use with ~$FormatName~: $Date, $DateTime, $Time, $Email, $Uri, $Uuid, $Ipv4, $Ipv6, $Hostname

Type Inference Rules

• Type is inferred from example value (no explicit declarations)
• 42 → Integer, 3.14 → Number, "text" → String, true → Boolean
• Arrays must have at least one element for type inference
• null cannot be used as example — no type can be inferred. Use ? for nullable fields with a real example value:

❌ "middleName|?": null ✅ "middleName|?{1,50}": "Marie"

❌ "discount|?(0..100)": null ✅ "discount|?(0..100)": 15

Decimal Values Ending in .00

JSON serializers drop trailing zeros: 78.00 becomes 78. To preserve decimal precision in examples, wrap in quotes:

❌ "amount": 78.00 → Serialized as 78, type inferred as Integer ✅ "amount": "78.00" → Preserved, type inferred as Number

This only affects decimals with zero fractional parts (.00, .0). Regular decimals (45.5) and integers (10) are unaffected.

⚠️ ? vs Absence — Critical Distinction

? and "optional field" are NOT the same thing in Okyline:

// ❌ Wrong — using ? for optional fields (common LLM mistake)
"meta|?|Resource metadata": { ... }
"subType|?|Claim subtype": { ... }

// ✅ Correct — optional = no @, never ?
"meta||Resource metadata": { ... }
"subType||Claim subtype": { ... }

// ✅ ? only when null is intentional and meaningful
"active|?|Explicitly unknown status": true

In FHIR R4 and most REST APIs, absent fields are simply omitted — they are never sent as null. Use ? only when the standard explicitly allows null as a distinct semantic value (e.g. "unknown" vs "not provided").

Legacy Null Tolerance

{ "$nullAsAbsentIfUndeclared": true }

When true, a null value on a field not marked ? is treated as absent instead of invalid. Use only for legacy systems that send null instead of omitting fields. Default: false.

Polymorphism vs Structural Directives — Key Distinction

These look similar but serve different purposes:

// $exactlyOne — exactly one of these sibling fields must be present
"diagnosisCodeableConcept": { ... },
"diagnosisReference": { ... },
"$exactlyOne": ["diagnosisCodeableConcept", "diagnosisReference"]

// $oneOf — the payment field itself must match exactly one variant
"payment|@ $oneOf": [
  { "type|@ ('card')": "card", "cardNumber|@ {16}": "1234567812345678" },
  { "type|@ ('paypal')": "paypal", "email|@ ~$Email~": "user@example.com" }
]

Reusable Definitions — $defs and $ref

Okyline supports internal references to promote reuse and consistency.

$defs — Definition Repository

$defs is placed at root level (alongside $oky) and contains reusable schema fragments:

{
  "$oky": {
    "person": {
      "address | $ref": "&Address",
      "contact | $ref @": "&Email"
    }
  },
  "$defs": {
    "Address": {
      "street|@ {2,100}": "12 rue du Saule",
      "city|@ {2,100}": "Lyon"
    },
    "Email|~$Email~ {5,100}": "user@example.com"
  }
}

Definitions can be objects or scalars (with constraints in the key).

Reference Syntax — &Name

References use & prefix: &Address, &Email, &Person

Property-Level Reference — field | $ref

A field uses another schema as its type:

"address | $ref @": "&Address"        // Required address
"backup | $ref ?": "&Address"         // Optional, nullable
"emails | $ref [1,5]": ["&Email"]     // Array of 1-5 emails

Structural constraints (@, ?, [min,max], !) are defined locally at each usage. Value constraints ({min,max}, (min..max), ~pattern~) are inherited from the definition.

Important: $ref vs -> for arrays

$ref and -> serve different purposes:

• $ref = type indicator (what the elements ARE) — comes BEFORE ->
• -> = validation constraints (rules elements must satisfy) — comes AFTER $ref

For arrays of referenced types, $ref is placed with the array constraint, never after ->:

// Correct syntax
"items|[*] $ref": ["&Item"]                    // Array of Item references
"items|[1,10] $ref": ["&Item"]                 // Array of 1-10 Item references  
"items|[*] $ref -> {2,50}": ["&Item"]          // With additional element constraint

// Wrong syntax - $ref must never be after ->
❌ "items|[*] -> $ref": ["&Item"]

Object-Level Reference — Inheritance

Include all fields from a base schema:

{
  "$oky": {
    "Article": {
      "$ref": "&Auditable",
      "title|@ {1,200}": "Mon article"
    }
  },
  "$defs": {
    "Auditable": {
      "createdAt|@ ~$DateTime~": "2025-01-01T00:00:00Z",
      "updatedAt|@ ~$DateTime~": "2025-01-01T00:00:00Z"
    }
  }
}

Multiple inheritance: "$ref": ["&Auditable", "&Deletable"]

Modifying Inherited Fields

$compute Context Rules

Expressions in $compute must be attached to a field using |(%ComputeName) syntax. The expression is evaluated in the context of the object that directly contains the annotated field — all properties of that object are accessible, including sibling arrays.

See references/expression-language.md for full details and examples.

Schema Design Workflow

1. Start with {"$oky": { ... }}
2. Write example JSON with realistic values
3. Add @ to required fields
4. Add constraints progressively: length, range, format, enums
5. Add conditional logic if needed ($appliedIf, $requiredIf)
6. Add computed validations if needed ($compute)
7. Identify repeated structures → extract to $defs with $ref

Reference Files

For detailed syntax and features, consult these references:

• Constraint syntax & patterns: See references/syntax-reference.md
• Conditional directives: See references/conditional-directives.md
• Expression language ($compute): See references/expression-language.md
• Internal references ($defs, $ref): See references/internal-references.md

Quick Patterns

// Required email
"email|@ ~$Email~": "user@example.com"

// Required string 2-50 chars
"name|@ {2,50}": "Alice"

// Optional number range
"discount|(0..100)": 15

// Enum from nomenclature
"status|@ ($STATUS)": "ACTIVE"

// Array of unique strings, 1-10 items, each 2-20 chars
"tags|@ [1,10] -> {2,20}!": ["eco", "bio"]

// Required but nullable
"middleName|@ ?{1,50}": "Marie"

// Map with pattern keys
"translations|[~^[a-z]{2}$~:10]": {"en": "Hello", "fr": "Bonjour"}

// Reference to definition (required)
"address | $ref @": "&Address"

// Array of referenced type ($ref before ->, never after)
"items | $ref @ [1,100]": ["&OrderItem"]

// Array of referenced type with element constraint
"codes | $ref [1,10] -> {2,20}": ["&Code"]

// Object inheritance
"$ref": "&Auditable"

// Template pattern — $ref + $override inline in array element
"coding|[*]": [{
  "$ref": "&Coding",
  "code|$override @ ($MARITAL_STATUS)|Code": "M"
}]

// Property-level $ref (field IS the type, no specialization)
"period|$ref||Validity period": "&Period"

// Multiple inheritance
"$ref": ["&Auditable", "&Deletable"]

Document Metadata (Optional) - Must be generated in this order

{
  "$okylineVersion": "1.3.0",
  "$version": "1.0.0",
  "$id": "my-schema",
  "$title": "My Schema",
  "$description": "Schema description",
  "$additionalProperties": false,
  "$oky": {
    ...
  },
  "$defs": { ... },
  "$format": { "Code": "^[A-Z]{3}-\\d{4}$" },
  "$compute": { "Total": "price * quantity" },
  "$nomenclature": { "STATUS": "ACTIVE,INACTIVE" }
}


**`$id` format**: Only letters, digits, underscores and dots allowed. Pattern: `^[a-zA-Z][a-zA-Z0-9_]*(\.[a-zA-Z][a-zA-Z0-9_]*)*$`
 ❌ `"personne-vehicules"` (hyphen not allowed)
 ✅ `"personne.vehicules"` or `"personne_vehicules"`

Structural Group Directives

Constrain which fields from a group must be present. No condition required.

"$atLeastOne": ["email", "phone"]               // at least one present
"$mutuallyExclusive": ["deceasedBoolean", "deceasedDateTime"]  // at most one
"$exactlyOne": ["diagnosisCode", "diagnosisRef"]  // exactly one
"$allOrNone": ["street", "city", "zip"]         // all or none

// Multiple independent groups → use suffix
"$mutuallyExclusive_deceased": ["deceasedBoolean", "deceasedDateTime"],
"$mutuallyExclusive_birth": ["multipleBirthBoolean", "multipleBirthInteger"]

See references/conditional-directives.md for full details.

$compute — Cross-Collection Pattern

To validate a constraint across an array from root context, attach the compute to the array field itself:

"insurance|@ [1,*] -> ! (%FocalInsurance)": [{
  "focal|@": true, ...
}],
"$compute": {
  "FocalInsurance": "countIf(insurance, focal) == 1"
}

• countIf(collection, expr) — counts elements where expr is truthy
• For boolean fields: countIf(insurance, focal) counts true values
• For other fields: countIf(items, status == 'ACTIVE')
• Always attach the compute to the most semantically relevant field

Common Mistakes to Avoid

• Missing $oky wrapper
• Empty arrays (need at least one element)
• Confusing [1,10] (array size) with -> {1,10} (element constraint)
• Forgetting to escape backslashes in regex (\d → \\d)
• Defining $compute expressions without attaching them to fields with |(%Name)
• Using absolute paths in $compute instead of relative references to parent context
• Using $ref without the & prefix (correct: "&Address", wrong: "Address")
• Object-level $ref targeting a scalar definition (must target object schema)
• Redefining an inherited field without using $override
• Creating circular object-level references (A includes B includes A)
• Placing $defs inside $oky (must be at root level)
• Using empty brackets [] for arrays — use [*] or omit size constraint entirely
• Applying element constraints (enum, length, range) directly to array field instead of using ->: ❌ "permis|@ ('A','B','C')[]": ["B"] ✅ "permis|@ -> ('A','B','C')": ["B"] ✅ "permis|@ [1,5] -> ('A','B','C')": ["B"]
  • Using hyphens in $id — only letters, digits, underscores and dots are allowed
• Applying element constraints (enum, length, range) directly to array field instead of using ->: ❌ "permis|@ ('A','B','C')[]": ["B"] ✅ "permis|@ -> ('A','B','C')": ["B"] ✅ "permis|@ [1,5] -> ('A','B','C')": ["B"]
• Placing $ref after -> for arrays of references ($ref is a type indicator, not a validation constraint): ❌ "children|[*] -> $ref": ["&Node"] ✅ "children|[*] $ref": ["&Node"] ✅ "children|[1,10] $ref -> {2,50}": ["&Node"]
• Using open-ended range syntax (0..) or (..100) — these don't exist! ❌ "price|(0..)": 29.99 ✅ "price|(>=0)": 29.99
• Using multiple value constraint blocks (...) on the same field: ❌ "montantTTC|@ (>=0) (%LigneTTC)": 4320 ✅ "montantTTC|@ (%LigneTTC)": 4320
• Using null as an example value, even with ? Okyline needs a valid example to infer the type.: ❌ "name|? ": null ✅ "name|? ": "Charles"
• Using decimal number example terminant par .00 sans " ". ❌ "amount|? ": 800.00 ✅ "amount|? ": "800.00"

When a field uses $compute, ALL value constraints must be inside the compute expression:

  "$compute": {
    "LigneTTC": "montantTTC >= 0 && montantTTC == montantNetHT + montantTVA"
  }

⚠️ Erreurs silencieuses (pas d'erreur syntaxe, mais problème à la validation)

• Décimales en .00 → "150.00" (sinon inféré comme Integer)
• Exemple null → impossible d'inférer le type
• Tableau vide [] → impossible d'inférer le type des éléments
• "champ|Label" → "Label" interprété comme contrainte (utiliser "champ| |Label")