Okyline Core Quick Reference - Basis

Version: 1.8.0 Date: September 2026 Status: Draft

Okyline is a JSON-based schema language for validating JSON documents by example. You write a JSON document with real example values, then add constraints directly in field names.

Okyline is a declarative language designed to describe the structure and constraints of JSON documents in a lightweight and readable manner. It enriches JSON examples with inline constraints, enabling data validation while keeping schemas human-friendly.

Okyline was designed from the outset to support structural validation, conditional logic, and computed business invariants within JSON document definitions.

For conditional rules ($requiredIf, $forbiddenIf, $appliedIf, …), see the companion Okyline Core Quick Reference - Conditional Directives.

1. Document Structure

A minimal Okyline schema:

{
  "$oky": {
    "name|@": "Alice",
    "age|(18..120)": 30
  }
}

↳ Two fields: name required string, age integer between 18 and 120

2. Field Syntax

" fieldName | constraints | label ": exampleValue

A key starting with $ is a directive, unless the first non-blank character after the initial word is a |: "$oid|@" is a field named $oid.

Example:

"email|@ {5,100} ~$Email~|User email": "[email protected]"

↳ Required string, 5-100 chars, must match email format, labeled “User email”

3. Type Inference

The example value determines the expected type:

Note: Since JSON serialization doesn’t guarantee trailing zeros are preserved, you can express decimal numbers as strings (e.g., "78.00"). These are auto-converted to Number. Use $str to force string type if needed.

Modifiers: - $str - force string type (disable decimal auto-conversion) - $obj - treat array example as multiple examples of a single-value field

4. Scalar Constraints

Example combining constraints:

"price|@ ? (0.01..9999.99)": 19.99

↳ Required, nullable, decimal between 0.01 and 9999.99

5. Collection Constraints

Examples:

"tags|[1,5] -> {2,20}!": ["eco", "bio"]

↳ List of 1-5 unique strings, each 2-20 characters

"scores|[15] -> (0..100)": [85, 92]

↳ List of maximum 15 elements, each element between 0 and 100

"translations|[~^[a-z]{2}$~:10] -> {1,100}": { "en": "Hello", "fr": "Bonjour" }

↳ Map with 2-letter keys, max 10 entries, values 1-100 characters

"users|[10] -> !": [{ "id|#@": 1, "name|@": "Alice" }]

↳ List of max 10 unique objects - uniqueness determined by # key field (id)

An empty example ([], { }) leaves the elements untyped: only the size and the key pattern apply; -> constraints and ! are rejected.

6. Path Expressions

Conditions and references can target fields in parent or root objects:

Note: parent skips over arrays - it always refers to the nearest parent object, not the array containing the current item.

Example:

"$requiredIf parent.status('ACTIVE')": ["code"]

↳ In a nested object: code required when the parent’s status equals “ACTIVE”

7. Registries

Nomenclature - reusable value lists:

"$nomenclature": { "STATUS": "ACTIVE,INACTIVE,PENDING" }

Usage: ($STATUS)

Format - reusable regex patterns:

"$format": { "Phone": "^\\+[0-9]{10,15}$" }

Usage: ~$Phone~

A key may carry a label after |: "STATUS | Account status": "ACTIVE,INACTIVE".

8. Built-in Formats

A $format declared with the same name as a built-in replaces it.

9. Type Guards

Test the runtime type of a field in conditions. Useful when a field can have different types and you need different validation rules for each.

Example:

"data": "example",
"$appliedIf data(_String_)": {
  "length": 7,
  "$else": { "type": "non-string" }
}

↳ length is added when data is a string, type otherwise

10. Polymorphism

For fields that accept different structures. For conditional variants, prefer $appliedIf (see Conditional Directives Quick Reference). Use $oneOf/$anyOf when variants are unrelated to other field values.

Example:

"payment|@ $obj $oneOf": [
  { "type|@ ('card')": "card", "number|@": "1234..." },
  { "type|@ ('paypal')": "paypal", "email|@": "[email protected]" }
]

↳ payment expects ONE object matching either card or paypal variant; $obj makes it a single value, without it the field is a list

11. Comments

Prefix attribute name with // to ignore it and its entire subtree:

"//user|@": { "id": 1, "name": "ignored" }

↳ The entire user object and its children are ignored by the parser

12. Full Document Structure

Complete schema with all optional metadata:

{
  "$oky": { ... },
  "$id": "my.schema",
  "$version": "1.0.0",
  "$state": "DRAFT",
  "$title": "My Schema",
  "$description": "Schema description",
  "$additionalProperties": false,
  "$sequence": false,
  "$nullAsAbsentIfUndeclared": false,
  "$decimalScale": 6,
  "$nomenclature": { ... },
  "$format": { ... },
  "$okylineVersion": "x.y.z"
}

Root keys are closed: any unknown $-key at the root fails loading.

See the per-annex Quick References for: $compute (C), $defs (D), external imports & visibility (E), $field (F).

Okyline® is a registered trademark of Akwatype.