C API reference

The public API consists of the portable validator in zxsd.h, the typed binding runtime in zxsd_bind.h, and an optional Mini-XML 4 adapter. Generated headers add schema-specific accessor, validation, and streaming-initializer functions, plus read and write functions when zxsdc --bindings is used.

See API, ABI, and migration for release guarantees, generated descriptor epochs, binary configuration requirements, and migration rules. zxsd_version.h provides release and epoch identifiers.

Compatibility checks

Release identifiers and generated-code compatibility epochs.

Defines

ZXSD_VERSION: Public header release; not an ABI compatibility test.

ZXSD_RUNTIME_ABI_VERSION: Public function and caller-owned structure ABI epoch.

ZXSD_DESCRIPTOR_ABI_VERSION: Immutable schema descriptor layout and interpretation epoch.

ZXSD_BINDING_ABI_VERSION: Typed binding descriptor and generated representation epoch.

Functions

const char *zxsd_version(void)

Get the linked runtime release, which may differ from the headers.

Returns:: Static release string. This is diagnostic information, not an ABI check.

void ZXSD_RUNTIME_ABI_GUARD(void): Link-time runtime ABI guard used by generated code; no side effects.

void ZXSD_DESCRIPTOR_ABI_GUARD(void): Link-time descriptor ABI guard used by generated code; no side effects.

struct zxsd_runtime_config_t

Caller configuration stamp for a same-toolchain runtime boundary.

Initialize with ZXSD_RUNTIME_CONFIG_INIT in application code. The fixed array order is part of ZXSD_RUNTIME_ABI_VERSION. This stamp is not a portable wire format and does not replace matching architecture/ABI flags.

Public Members

unsigned int runtime_abi: Public API/layout epoch.

unsigned int descriptor_abi: Descriptor interpretation epoch.

unsigned int no_heap: Whether ZXSD_NO_HEAP was defined.

size_t limits[22]: Exact public resource limits, in declaration order.

size_t layouts[12]: Public storage and fundamental type sizes.

zxsd_result_t zxsd_check_runtime(const zxsd_runtime_config_t *expected);

Initialize the stamp with ZXSD_RUNTIME_CONFIG_INIT in the application and check it before using a separately built runtime. For bindings, the equivalent zxsd_bind_runtime_config_t and zxsd_bind_check_runtime() include binding layout sizes; their declarations appear in the typed bindings reference below. See API, ABI, and migration for the complete startup example and limitations.

Validation runtime

Core types

enum zxsd_error_t

Validation status and error codes.

Values:

enumerator ZXSD_OK: Validation succeeded.

enumerator ZXSD_ERR_ARGUMENT: A required argument is invalid.

enumerator ZXSD_ERR_INPUT_TOO_LARGE: XML exceeds ZXSD_MAX_INPUT.

enumerator ZXSD_ERR_MALFORMED_XML: XML syntax is malformed.

enumerator ZXSD_ERR_EXCESSIVE_NESTING: XML nesting exceeds the limit.

enumerator ZXSD_ERR_WRONG_ROOT: The document root does not match.

enumerator ZXSD_ERR_MISSING_ELEMENT: A required child element is absent.

enumerator ZXSD_ERR_UNEXPECTED_ELEMENT: A child element is not permitted.

enumerator ZXSD_ERR_ELEMENT_ORDER: Sequence order is incorrect.

enumerator ZXSD_ERR_OCCURRENCE: An occurrence bound was violated.

enumerator ZXSD_ERR_MISSING_ATTRIBUTE: A required attribute is absent.

enumerator ZXSD_ERR_UNEXPECTED_ATTRIBUTE: An attribute is not permitted.

enumerator ZXSD_ERR_INVALID_VALUE: A primitive or restricted value is invalid.

enumerator ZXSD_ERR_TEXT_NOT_ALLOWED: Text occurred in element-only content.

enumerator ZXSD_ERR_IDENTITY_CONSTRAINT: A unique, key or keyref rule failed.

enumerator ZXSD_ERR_STREAM_LIMIT: A fixed streaming buffer was exceeded.

enumerator ZXSD_ERR_RESOURCE_LIMIT: A configured resource limit was exceeded.

enumerator ZXSD_ERR_OUTPUT: A binding output sink or buffer failed.

enumerator ZXSD_ERR_UNSUPPORTED: A valid document cannot be represented by a binding.

enumerator ZXSD_ERR_INCOMPATIBLE_ABI: Runtime epochs, limits, or public layouts differ.

struct zxsd_result_t

Structured result returned by every generated validator.

Public Members

zxsd_error_t code: Validation status.

size_t offset: Byte offset associated with the result.

const char *path: Schema item involved, or NULL.

const char *message: Static, human-readable status text.

struct zxsd_allocator_t

Optional allocator used by validation features requiring scratch storage.

Public Members

zxsd_allocate_fn allocate: Allocation callback.

zxsd_deallocate_fn deallocate: Matching release callback.

void *context: Opaque callback context.

struct zxsd_schema_t

Root descriptor consumed by the generic validation runtime.

Public Members

const char *root_name: Root local name.

zxsd_type_t root_type: Root value kind.

const zxsd_complex_t *root_complex: Root complex descriptor.

const zxsd_simple_t *root_simple: Root simple restriction.

const char *root_namespace_uri: Root namespace, or NULL.

const zxsd_identity_t *identities: Root identity constraints.

size_t identity_count: Number of identity constraints.

const zxsd_global_element_t *global_elements: Wildcard declaration registry.

size_t global_element_count: Number of global declarations.

const zxsd_global_attribute_t *global_attributes: Attribute registry.

size_t global_attribute_count: Number of global attributes.

const zxsd_named_type_t *named_types: Runtime xsi:type registry.

size_t named_type_count: Number of named type entries.

const char *default_value: Root default, or NULL.

const char *fixed_value: Root fixed value, or NULL.

int nillable: Non-zero when root permits xsi:nil.

int abstract_element: Non-zero when root is abstract.

unsigned block_methods: Root block constraints.

const zxsd_notation_t *notations: Global notation declaration registry.

size_t notation_count: Number of notation declarations.

struct zxsd_stream_t

Bounded state for the event-driven validator.

Initialize this object with zxsd_stream_init before sending events. Its storage is bounded by compile-time configuration constants. Identity constraints additionally use the configured allocator. Flat content models use counters. Nested sequences and choices use a shared, bounded continuation pool, including alternative repetition partitions. Zero ZXSD_STREAM_MODEL_CAPACITY selects the bounded history fallback.

Public Members

const zxsd_schema_t *schema: Generated schema being validated.

zxsd_result_t result: Sticky result of the first failed event.

size_t depth: Number of currently open elements.

size_t event_offset: Monotonic event index used in diagnostics.

int finished: Non-zero after a complete root element.

zxsd_allocator_t identity_allocator: Allocator for streamed identity validation.

char *identity_xml: Internal reconstructed XML buffer.

size_t identity_xml_length: Bytes used in identity_xml.

size_t identity_xml_capacity: Allocated reconstructed XML bytes.

zxsd_stream_namespace_t namespaces[16u]: Active QName bindings.

size_t namespace_count: Number of active entries in namespaces.

zxsd_stream_model_node_t model_nodes[128u]: Shared continuation/frontier storage; independent of document length.

uint16_t model_free: First free pool slot, or zero.

uint16_t model_high_water: Highest slot ever allocated; bounds interning scans.

int model_pool_initialized: Whether the lazy free list has been initialized.

zxsd_stream_frame_t frames[32u]: Fixed element stack.

struct zxsd_xml_reader_t

Bounded raw-XML reader feeding an event-driven validator.

The object accepts arbitrary byte fragments and retains only an incomplete lexical token between calls. Initialize it with zxsd_xml_reader_init, then call zxsd_xml_reader_feed and zxsd_xml_reader_finish.

Public Members

zxsd_stream_t validator: Event-driven validator receiving decoded XML events.

zxsd_result_t result: Sticky result of the first parser or validator error.

size_t offset: Total number of input bytes accepted.

size_t token_offset: Absolute offset of the retained token.

size_t token_length: Bytes currently retained in token.

unsigned char markup: Non-zero while retaining markup beginning with <.

unsigned char quote: Active attribute quote, or zero.

zxsd_xml_event_fn event_callback: Optional decoded-event observer.

void *event_user_data: Opaque observer context.

char token[4096u + 1u]: Incomplete text or markup token.

char decoded[1024u + 1u]: Decoded text or attribute scratch.

Validation functions

zxsd_result_t zxsd_validate(const zxsd_schema_t *schema, const char *xml);
zxsd_result_t zxsd_validate_with_allocator(
        const zxsd_schema_t *schema,
        const char *xml,
        const zxsd_allocator_t *allocator);
const char *zxsd_error_string(zxsd_error_t error);

zxsd_validate() validates one NUL-terminated document. The allocator variant supplies bounded scratch storage for identity constraints. zxsd_error_string() returns a stable static description.

Streaming functions

zxsd_result_t zxsd_stream_init(zxsd_stream_t *stream,
                               const zxsd_schema_t *schema);
zxsd_result_t zxsd_start_element(zxsd_stream_t *stream,
                                 const char *namespace_uri,
                                 const char *local_name);
zxsd_result_t zxsd_attribute(zxsd_stream_t *stream,
                             const char *namespace_uri,
                             const char *local_name,
                             const char *value);
zxsd_result_t zxsd_xsi_type(zxsd_stream_t *stream,
                            const char *type_namespace_uri,
                            const char *type_local_name);
zxsd_result_t zxsd_start_content(zxsd_stream_t *stream);
zxsd_result_t zxsd_text(zxsd_stream_t *stream,
                        const char *text, size_t length);
zxsd_result_t zxsd_end_element(zxsd_stream_t *stream,
                               const char *namespace_uri,
                               const char *local_name);
zxsd_result_t zxsd_stream_finish(zxsd_stream_t *stream);

Initialize once, send decoded events in document order, and finish after the root closes. The first error is sticky. A generated <schema>_stream_init() wrapper selects the default root descriptor.

The runtime selects a counter-based cursor for flat sequences, all groups, and choices when their repetition rules permit incremental validation. These models can process more children than ZXSD_STREAM_CHILD_CAPACITY. Nested sequences, choices, and more complex repetitions use a fixed continuation pool shared by all open elements. It keeps viable occurrence partitions, not child history, and merges equivalent states. Invalid prefixes fail before notifying the raw reader’s observer; missing children fail when the parent closes. The effective model is selected after xsi:type processing.

ZXSD_STREAM_MODEL_CAPACITY defaults to 128 continuation/frontier slots; exhaustion returns the sticky ZXSD_ERR_STREAM_LIMIT result. This is an application budget, not a bound on children. Nullable repetitions do not enumerate empty iterations. Epsilon expansion is iterative and limited to the square of the pool capacity per event, preventing pathological nullable models from doing unbounded work. Setting the capacity to zero removes the pool and selects the historical bounded token matcher for non-flat models. Non-XSD hand-built trees containing nested all groups also use that fallback; compiler-generated XSD 1.0 all groups retain the flat counter path.

The frame members exposed for static allocation are internal state. Rebuild the library and consuming applications together after updating the headers; generated schema descriptor layouts are unchanged.

Raw XML fragment functions

For typed delivery from the same fragments, see Typed bindings and the zxsdc --stream-bind element/path generation option. It validates all input while materializing only the selected subtree into a reusable caller arena.

zxsd_result_t zxsd_xml_reader_init(zxsd_xml_reader_t *reader,
                                   const zxsd_schema_t *schema);
zxsd_result_t zxsd_xml_reader_init_with_allocator(
        zxsd_xml_reader_t *reader,
        const zxsd_schema_t *schema,
        const zxsd_allocator_t *allocator);
zxsd_result_t zxsd_xml_reader_feed(zxsd_xml_reader_t *reader,
                                  const void *data, size_t length);
void zxsd_xml_reader_set_event_callback(zxsd_xml_reader_t *reader,
                                        zxsd_xml_event_fn callback,
                                        void *user_data);
zxsd_result_t zxsd_xml_reader_finish(zxsd_xml_reader_t *reader);
void zxsd_xml_reader_dispose(zxsd_xml_reader_t *reader);

Feed arbitrary raw-byte fragments and call finish once at end of input. The reader XML-decodes names and values, resolves namespaces, and emits events to its embedded zxsd_stream_t. The first XML or validation error is sticky. dispose releases optional identity-constraint scratch storage. The optional observer receives transient decoded events only after the validator accepts them; it can copy selected values into bounded application storage without retaining the XML response.

The complete Doxygen reference is exhaustive: it also lists every descriptor type, compile-time limit, callback typedef, and generated-data structure used by zxsdc output. In a local build it is available under doc/_build_doxygen/html.

Typed bindings

Structures and descriptors generated by zxsdc --bindings are interpreted by this runtime. See Typed bindings for the C representation and usage.

Typed data bindings between generated C structures and XML documents.

Bindings are generated by zxsdc --bindings. Each binding pairs a generated C structure with immutable descriptor tables interpreted by this runtime. The runtime does not allocate memory:

writing serializes a structure to a caller-supplied sink, rejects structural inconsistencies, and can validate the produced events with the streaming validator;
reading validates a document with the generated schema, then fills a structure. Strings, repeated items and optional nested structures are stored in a caller-supplied arena;
streaming reading validates raw fragments once and delivers selected typed subtrees through callbacks, reusing that arena after each delivery.

struct zxsd_bind_field

#include <zxsd_bind.h>

Generated descriptor for one member of a bound structure.

Public Members

const char *name: XML local name.

const char *namespace_uri: XML namespace URI, or NULL.

zxsd_bind_role_t role: Attribute, child element or content.

zxsd_bind_kind_t kind: C value representation.

zxsd_bind_storage_t storage: Member layout.

unsigned long min_occurs: Minimum occurrences, zero when optional.

unsigned long max_occurs: Maximum occurrences, or ULONG_MAX.

size_t offset: Offset of the value, pointer or array member.

size_t presence_offset: Offset of the bool presence member.

size_t count_offset: Offset of the size_t count member.

size_t value_size: Size of one stored value or array item.

const struct zxsd_bind_type *type: Nested structure for complex values.

const char *const *enumeration: Lexical values of an enumeration.

size_t enumeration_count: Number of enumeration values.

zxsd_whitespace_t whitespace: Normalization applied when reading.

const char *default_value: Schema default value, or NULL.

const char *fixed_value: Schema fixed value, or NULL.

struct zxsd_bind_type

#include <zxsd_bind.h>

Generated descriptor for a bound structure.

Public Members

const char *name: Generated C type name, for diagnostics.

const char *type_name: Named XSD type, or NULL if anonymous.

const char *type_namespace: Named XSD type namespace, or NULL.

size_t size: Size of the structure.

const zxsd_bind_field_t *fields: Attributes, then elements, then content.

size_t field_count: Number of entries in fields.

struct zxsd_bind_namespace_t

#include <zxsd_bind.h>

Namespace prefix declared on the root element when writing.

Public Members

const char *prefix: Generated prefix.

const char *namespace_uri: Namespace URI bound to prefix.

struct zxsd_bind_root_t

#include <zxsd_bind.h>

Generated descriptor for a bound global element.

Public Members

const char *name: Root local name.

const char *namespace_uri: Root namespace URI, or NULL.

const zxsd_bind_type_t *type: Root structure descriptor.

zxsd_bind_schema_fn schema: Generated validation descriptor accessor.

const zxsd_bind_namespace_t *namespaces: Prefixes declared on the root.

size_t namespace_count: Number of entries in namespaces.

const char *default_value: Root default content, or NULL.

const char *fixed_value: Root fixed content, or NULL.

struct zxsd_bind_arena_t

#include <zxsd_bind.h>

Caller-owned bump allocator used when reading a document.

Initialize it with zxsd_bind_arena_init. Pointers stored in a structure filled by zxsd_bind_read remain valid while the arena storage is alive and is not reset.

Public Members

unsigned char *data: First byte of the arena storage.

size_t capacity: Number of bytes in data.

size_t used: Number of bytes already allocated.

struct zxsd_bind_path_step_t

#include <zxsd_bind.h>

One generation-time-resolved element step; prefixes are not identities.

Public Members

const char *name: Element local name.

const char *namespace_uri: Namespace URI, or NULL.

struct zxsd_bind_selection_t

#include <zxsd_bind.h>

Immutable selection emitted by zxsdc --stream-bind.

Public Members

zxsd_bind_schema_fn schema: Full document schema, including unselected content.

const zxsd_bind_path_step_t *steps: Absolute element path, including the root.

size_t step_count: Number of path steps.

const zxsd_bind_type_t *type: Selected structure; simple selections have a value member.

const char *default_value: Selected element default, or NULL.

const char *fixed_value: Selected element fixed value, or NULL.

struct zxsd_bind_stream_frame_t

#include <zxsd_bind.h>

Internal binding frame, exposed only for static allocation.

Public Members

const zxsd_bind_type_t *type: Complex or simpleContent structure, if any.

const zxsd_bind_field_t *field: Scalar element descriptor, if any.

void *object: Caller/arena storage receiving this element.

unsigned char path_match: Absolute selection prefix matches through this depth.

unsigned char seen_attributes[32u]: Explicit attributes seen.

struct zxsd_bind_stream_t

#include <zxsd_bind.h>

Single-pass validating typed reader with caller-owned, reusable storage.

Public Members

zxsd_xml_reader_t xml: Raw parser and full-document validator.

const zxsd_bind_selection_t *selection: Generated selection.

zxsd_bind_arena_t *arena: Arena borrowed until dispose.

void *object: Caller-owned selected structure.

zxsd_bind_item_fn callback: Typed delivery adapter.

void *user_data: Application context.

size_t arena_mark: Arena usage restored after delivery/error/dispose.

size_t active_depth: Selected element depth, or zero.

int validate_only: Whether further materialization is disabled.

int finished: Whether finish completed successfully.

zxsd_bind_stream_frame_t frames[32u]: Bounded binding stack.

struct zxsd_bind_runtime_config_t

#include <zxsd_bind.h>

Binding-specific layout stamp; initialize with ZXSD_BIND_RUNTIME_CONFIG_INIT.

Public Members

zxsd_runtime_config_t runtime: Core epochs, limits, and layouts.

unsigned int binding_abi: Typed binding epoch.

size_t layouts[6]: Binding descriptor and caller storage sizes.

Mini-XML adapter

The adapter is built only when CMake finds Mini-XML 4 and ZXSD_USE_MXML=ON. It walks an existing Mini-XML tree and feeds expanded events to the same runtime.

Mini-XML 4 adapter for the zxsd streaming validator.