SData

Structured Data (SData) is a mechanism to define and manage structured fields, attributes, and commands in a hierarchical and schema-driven manner. It is used to define the attributes of objects, command parameters, and database-like records in a highly structured and reusable way.

Core Concepts¶

SData Fields¶

SData fields are descriptors that define individual fields or attributes. These fields include information about their type, name, default value, description, flags, and other properties.

SData Tables¶

SData tables are arrays of field descriptors (sdata_desc_t) that define structured data. These tables allow hierarchical definitions, enabling the creation of complex schemas.

Data Types (`data_type_t`)¶

The data_type_t enumeration defines the types of data that SData fields can represent:

Type	Description
`DTP_STRING`	A text string.
`DTP_BOOLEAN`	A boolean value (`TRUE` or `FALSE`).
`DTP_INTEGER`	An integer value.
`DTP_REAL`	A floating-point number.
`DTP_LIST`	A list (array) of values.
`DTP_DICT`	A dictionary (key-value pairs).
`DTP_JSON`	A JSON object.
`DTP_POINTER`	A generic pointer.

Data Type Utilities¶

String types: DTP_IS_STRING(type)
Boolean types: DTP_IS_BOOLEAN(type)
Integer types: DTP_IS_INTEGER(type)
Number types: DTP_IS_NUMBER(type) (includes integer, real, and boolean)
List types: DTP_IS_LIST(type)
Dictionary types: DTP_IS_DICT(type)
JSON types: DTP_IS_JSON(type)
Pointer types: DTP_IS_POINTER(type)

Field Flags (`sdata_flag_t`)¶

The sdata_flag_t enumeration defines the properties and characteristics of each field. Flags are bitwise-combinable to give fields multiple properties.

Flag	Description
`SDF_NOTACCESS`	Field is not accessible.
`SDF_RD`	Field is read-only.
`SDF_WR`	Field is writable (and readable).
`SDF_REQUIRED`	Field is required; it must not be null.
`SDF_PERSIST`	Field is persistent and must be saved/loaded.
`SDF_VOLATIL`	Field is volatile and must not be saved/loaded.
`SDF_RESOURCE`	Field is a resource, referencing another schema.
`SDF_PKEY`	Field is a primary key.
`SDF_STATS`	Field holds statistical data (metadata).
`SDF_RSTATS`	Field holds resettable statistics, implicitly `SDF_STATS`.
`SDF_PSTATS`	Field holds persistent statistics, implicitly `SDF_STATS`.
`SDF_AUTHZ_R`	Read access requires authorization (`__read_attribute__`).
`SDF_AUTHZ_W`	Write access requires authorization (`__write_attribute__`).
`SDF_AUTHZ_X`	Execution requires authorization (`__execute_command__`).
`SDF_AUTHZ_S`	Stats read requires authorization (`__read_stats__`).
`SDF_AUTHZ_RS`	Stats reset requires authorization (`__reset_stats__`).

SDF_NOTACCESS¶

Field is not accessible.

SDF_RD¶

Field is read-only.

SDF_WR¶

Field is writable (and readable).

SDF_REQUIRED¶

Field is required; it must not be null.

SDF_PERSIST¶

Field is persistent and must be saved/loaded.

SDF_VOLATIL¶

Field is volatile and must not be saved/loaded.

SDF_RESOURCE¶

Field is a resource, referencing another schema.

SDF_PKEY¶

Field is a primary key.

SDF_STATS¶

Field holds statistical data (metadata).

SDF_RSTATS¶

Field holds resettable statistics, implicitly `SDF_STATS`.

SDF_PSTATS¶

Field holds persistent statistics, implicitly `SDF_STATS`.

SDF_AUTHZ_R¶

Read access requires authorization (`__read_attribute__`).

SDF_AUTHZ_W¶

Write access requires authorization (`__write_attribute__`).

SDF_AUTHZ_X¶

Execution requires authorization (`__execute_command__`).

SDF_AUTHZ_S¶

Stats read requires authorization (`__read_stats__`).

SDF_AUTHZ_RS¶

Stats reset requires authorization (`__reset_stats__`).

Common Flag Combinations¶

Public Attributes: Combine SDF_RD|SDF_WR|SDF_STATS|SDF_PERSIST|SDF_VOLATIL|SDF_RSTATS|SDF_PSTATS.
Writable Attributes: Combine SDF_WR|SDF_PERSIST.

Descriptor Fields (`sdata_desc_t`)¶

The sdata_desc_t structure defines a field or schema. Each descriptor specifies the following:

Field	Type	Description
`type`	`data_type_t`	The type of the field (e.g., string, boolean).
`name`	`const char *`	The name of the field.
`alias`	`const char **`	Alternative names (aliases) for the field.
`flag`	`sdata_flag_t`	Flags defining the field’s properties.
`default_value`	`const char *`	The default value of the field.
`header`	`const char *`	Header text for table columns.
`fillspace`	`int`	Column width for table formatting.
`description`	`const char *`	A description of the field’s purpose.
`json_fn`	`json_function_fn`	Custom function for processing JSON data.
`schema`	`const sdata_desc_t *`	Pointer to a sub-schema for compound fields.
`authpth`	`const char *`	Authorization path for accessing or modifying the field.

Application¶

Attributes¶

SData tables define attributes by listing fields with their types, default values, and flags. These fields form the basis of object definitions, enabling schema-based validation and management.

Commands¶

SData tables can define commands with associated parameters, schemas, and descriptions. Commands extend the functionality of objects, providing structured inputs and outputs.

Nested Schemas¶

Fields in SData can reference other schemas, enabling hierarchical definitions. This allows for the creation of complex, nested structures while maintaining clarity and reusability.