sqon-parser

SQON: Structured Queue Object Notation

SQON (Structured Queue Object Notation) is a structured data format that combines schema definitions, validation rules, and records. It ensures data consistency with strict mode, enforcing type restrictions and validation rules.

Table of Contents

• Overview
• SQON File Structure
• Strict Mode
• Schema Section
• Validation Section
• Records Section
• Key Features of SQON
• Example Usage
  • SQON Validation Example
• Advantages of SQON Format

Check logs to know what's new in the new version

Overview

Overview

**SQON** is a structured data format that combines schema definitions, validation rules, and records. It supports strict mode, which ensures data consistency by enforcing type restrictions and validation rules.

SQON File Structure

File Structure

A SQON file includes:

• Strict Mode Setting (`STRICT=TRUE/FALSE`)
• Schema Definition (`@schema`)
• Validation Rules (`@validations`)
• Records (`@records`)

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

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

Strict Mode

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 where each field must match the exact data type.
• STRICT=FALSE: Allows more flexibility with fields that can have multiple types.

Example with Strict Mode Enabled

STRICT=TRUE

2. Schema Section (@schema)

Schema Section

The schema section defines the fields and their data types. When `STRICT=TRUE`, fields must have a single, precise data type. With `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 Section

The validation section specifies rules for each field to ensure data integrity. These rules might include constraints like `required`, `minLength`, or `isDate`.

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)

Records Section

The records section contains actual data entries. Each record is prefixed with a unique document number (`#0`, `#1`, etc.). These entries represent real data and follow the schema and validation rules.

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

Key Features

**Document Numbers**: Each record is identified by a unique document number (`#0`, `#1`, `#2`), which allows for easy reference, error tracking, and quick lookup.

**Indexed Arrays**: Arrays are indexed with unique keys (e.g., `_0`, `_1`), which provides clarity and structure for managing array elements.

Example Usage

Example Usage

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

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

Example Usage for SQON Validation

SQON Validation Example

This example demonstrates:

• How to define nested schemas for objects and arrays.
• How to apply validation rules to nested schemas.
• Use all types (`String`, `Number`, `Date`, `Boolean`, `StringArray`, `Object`, `ObjectArray`).

Example Code

import { Validator, ValidateParams, ValidationResult, SchemaDefinition, ValidationRules } from './Validator';
// Example Schema Definition
const schema: Record<string, SchemaDefinition> = {
username: { type: ['String'] },
age: { type: ['Number'] },
birthdate: { type: ['Date'] },
isVerified: { type: ['Boolean'] },
friends: { type: ['StringArray'] },
preferences: { type: ['Object'], properties: { theme: { type: ['String'] }, notifications: { type: ['Boolean'] } } },
activities: { type: ['ObjectArray'], items: { type: ['Object'], properties: { activityName: { type: ['String'] }, duration: { type: ['Number'] } } } }
};
// Example Validation Rules
const validations: Record<string, ValidationRules> = {
username: { rules: { required: true, minLength: 3 } },
age: { rules: { required: true, min: 18, max: 120 } },
birthdate: { rules: { isDate: true } },
isVerified: { rules: { required: true } },
friends: { rules: { minLength: 1, maxLength: 5 } },
preferences: { rules: { maxLength: 10, required: true }, theme: { rules: { required: true, minLength: 3 } }, notifications: { rules: { required: true } } },
activities: { rules: { minLength: 1, maxLength: 10, required: true, isUnique: true }, activityName: { rules: { required: true, minLength: 3 } }, duration: { rules: { required: true, min: 1 } } }
};
const data = {
username: "Alice",
age: 30,
birthdate: "1993-05-20T00:00:00Z",
isVerified: true,
friends: ["Bob", "Charlie"],
preferences: { theme: "dark", notifications: true },
activities: [{ activityName: "Running", duration: 60 }, { activityName: "Swimming", duration: 45 }]
};
async function validateSQONEntry({ schema, validateData, data, strict = true }: ValidateParams): Promise {
const validator = new Validator();
return await validator.validate({ schema, validateData, data, strict });
}
validateSQONEntry({ schema
, validateData: validations, data, strict: true }).then(result => {
if (result.valid) {
console.log("Data is valid.");
} else {
console.log("Validation failed:", result.errors);
}
});

Advantages of SQON Format

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 useful in applications where structured data with flexible types, validation, and indexed array elements are needed. SQON enhances both readability and data management, making it a powerful choice for structured, validated data storage.