KSON (Kson Structured Object Notation)

The KsonTooling.kt interface provides a Kotlin Multiplatform API for building schema-aware tools for KSON. It allows you to perform deep analysis of KSON documents by leveraging the underlying schema to extract information at any specific location within a document.

Key capabilities include:

• Schema Information Retrieval: Extract type information, constraints, metadata, and schema documentation for any position in a KSON document.
• Completion Suggestions: Retrieve valid property names, enum values, and type-appropriate suggestions based on the schema.
• Document Path Navigation: Navigate through KSON documents using schema-aware path building.

This API is suitable for developing IDE extensions, linters, documentation generators, CLI tools, or web-based editors that require schema-aware document analysis.

// The public interface is defined in:
// src/commonMain/kotlin/org/kson/KsonTooling.kt

KSON supports embed blocks for embedding raw content (like SQL or HTML) using a syntax like $tag\ncontent\n$$.

Parsing Embed Blocks

When using Kson.analyze(), embed blocks are represented as KsonValue.KsonEmbed objects. You can access the metadata via .tag() and the raw content via .content().

Transpilation Behavior

When converting to JSON or YAML:

• retain_embed_tags=True: Preserves the embed metadata.
• retain_embed_tags=False: Flattens the embed block into a plain string.

from kson import Kson, KsonValue

analysis = Kson.analyze("query: $sql\nSELECT * FROM users\n$$", None, None)
value = analysis.kson_value()

if isinstance(value, KsonValue.KsonObject):
    embed = value.properties()["query"]
    if isinstance(embed, KsonValue.KsonEmbed):
        print(f"Tag: {embed.tag()}")        # "sql"
        print(f"Content: {embed.content()}")  # "SELECT * FROM users"

Because KSON does not use significant whitespace (unlike YAML), plain structures (Plain Dash Lists and Plain Objects) rely on greedy parsing.

• Plain Dash Lists absorb every - element they can, ending at the first non-dash element or an explicit end-dash =.
• Plain Objects absorb every key: value property they can, ending at the first non-property element or an explicit end-dot ..

When to use terminators: You only need a terminator (= for lists, . for objects) when the greedy parser would otherwise incorrectly absorb an element/property that belongs to a parent structure. If a structure ends naturally (e.g., a list ends because the next line is a new key), no terminator is required.

Explicitly using terminators is always legal; the KSON formatter will remove them if they are unnecessary.

# Natural end: the list ends because 'lucky_color' is a key, not a list element
lucky_numbers: 
  - 7
  - 13
lucky_color: blue

# Required end-dot: without '.', 'favorite_movie' would be absorbed into the book object
favorite_books:
  - title: Elements
    author: Euclid
  - title: Metaphysics
    author: Aristotle
    .
favorite_movie: 'The Rock'