sqon-parser

Overview

SQON (Structured Query Object Notation) is a structured data format combining schema definitions, validation rules, and records. It supports strict mode, ensuring data consistency by enforcing type restrictions and validation rules.

SQON File Structure

A SQON file includes:

1. Strict Mode Setting (STRICT=TRUE/FALSE)
2. Schema Definition (@schema)
3. Validation Rules (@validations)
4. Records (@records)

Each section is marked by specific tags (@schema, @validations, and @records) and closed with @end.

---

1. Strict Mode (*STRICT=TRUE/FALSE)

The strict mode setting, located at the top of the file, controls whether records must strictly adhere to the schema and validation rules.

• STRICT=TRUE: Enforces a strict schema; each field must match the exact data type specified in the schema. Schema fields cannot have multiple types, and records must pass validation rules precisely.
• STRICT=FALSE: Allows more flexibility, including support for multiple types per field in the schema. Validation rules are applied but can allow for alternative type definitions.

Example with Strict Mode Enabled:

STRICT=TRUE

---

2. Schema Section (@schema)

Defines fields and data types. When STRICT=TRUE, fields must have a single, precise data type. If STRICT=FALSE, fields can accept multiple types (e.g., String | Number).

Example Schema (Strict Mode Enabled):

@schema
username -> String
age -> Number
createdDate -> Date
preferences -> Object
tags -> StringArray
@end

---

3. Validation Section (@validations)

Validation rules ensure data integrity by specifying requirements for fields (e.g., required, minLength, isDate). With STRICT=TRUE, records that fail validation are rejected.

Example Validations:

@validations
username -> required=true, minLength=3
age -> required=true, min=18, max=120
createdDate -> isDate=true
tags -> minLength=1, maxLength=10
@end

---

4. Records Section (@records)

The records section holds actual data entries. Each record begins with a unique document number (#0, #1), which allows quick record identification.

Example Records:

@records
#0 -> username("JohnDoe"); age(30); createdDate(1993-07-16T00:00:00Z); preferences{ theme: "dark" }; tags[ _0("friend"); _1("coworker") ];
#1 -> username("JaneSmith"); age(25); createdDate(1998-04-22T00:00:00Z); preferences{}; tags[ _0("family") ];
@end

---

Key Features of SQON

Document Numbers (#0, #1, #2)

Each entry begins with a document number, which serves as a unique reference. Advantages include:

• Easy Lookup: Directly access records by document number.
• Indexing: Simplifies locating records within the file.
• Error Tracking: Users can identify issues in specific records by referencing document numbers.

Indexed Arrays (_0, _1, etc.)

Arrays use indexed keys for each element (e.g., _0("value"), _1("value")). Benefits include:

1. Clarity: Each array element has a unique key, making updates or references to individual items simpler.
2. Structure: Explicit indexing makes array elements easier to manage, as each has a stable identifier.

Example with *STRICT=TRUE

*STRICT=TRUE

@schema
username -> String
age -> Number
birthdate -> Date
isVerified -> Boolean
friends -> StringArray
@end

@validations
username -> required=true, minLength=3
age -> required=true, min=18, max=120
birthdate -> isDate=true
isVerified -> required=true
friends -> minLength=1, maxLength=5
@end

@records
#0 -> username("Alice"); age(30); birthdate(1993-05-20T00:00:00Z); isVerified(TRUE); friends[ _0("Bob"); _1("Charlie") ];
#1 -> username("Bob"); age(35); birthdate(1988-07-22T00:00:00Z); isVerified(FALSE); friends[ _0("Alex"); ];
@end

With *STRICT=TRUE, the format enforces stricter data integrity, providing users with a high degree of reliability and control over data consistency.

Example usage

You can find usage examples in the example folder of the installed package. See:

• example/test.js
• example/test.sqon

Advantages of SQON Format

• Human-Readable Structure: SQON’s layout is easy to read, write, and understand for humans.
• Flexible Schema Definitions: Allows multiple data types per field, providing flexibility for complex data structures.
• Integrated Validation: Validation rules ensure data integrity and consistency within the SQON file.
• Indexed Arrays: The _number notation for arrays adds clarity and structure, making it easy to manage array elements.
• Document Numbers: Sequential document numbering allows easy tracking, reference, and query handling for records.

This format is especially useful in applications where structured data with flexible types, validation, and indexed array elements are needed. SQON’s organized layout and indexing features enhance both readability and data management, making it a powerful choice for structured, validated data storage.