Okyline Core Quick Reference - Basis

Version: 1.7.0 Date: May 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

Example:

"email|@ {5,100} ~$Email~|User email": "alice@example.com"

↳ 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)

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~

8. Built-in Formats

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:

"$appliedIf data": {
  "(_String_)":{"data|{5,50}": "Hello"},
  "(_Integer_)":{"data|(1..200)": 100}
}

↳ data validated as string (5-50 chars) or integer (1-200) depending on its actual type

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|@ $oneOf": [
  { "type|@ ('card')": "card", "number|@": "1234..." },
  { "type|@ ('paypal')": "paypal", "email|@": "a@b.c" }
]

↳ payment expects ONE object matching either card or paypal variant (not an array)

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:

{
  "$okylineVersion": "1.7.0",
  "$version": "1.0.0",
  "$title": "My Schema",
  "$description": "Schema description",
  "$id": "my.schema",
  "$state": "DRAFT",
  "$additionalProperties": false,
  "$sequence": false,
  "$nomenclature": { ... },
  "$format": { ... },
  "$oky": { ... }
}

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.