VTL Toolkit

The VTL Toolkit provides a set of methods to help the user in the SDMX-VTL interconnection. Currently, it includes functionality to generate VTL scripts, validate the SDMX-VTL objects and convert datasets between SDMX and VTL formats.

Generate VTL script

pysdmx.toolkit.vtl.generate_vtl_script(transformation_scheme, model_validation=False, prettyprint=False)

Generates the VTL script from a TransformationScheme.

This method iterates over the TransformationScheme object and its referred RulesetSchemes and UserDefinedOperatorSchemes to generate the VTL script as string

The model_validation feature checks if the model object is valid by parsing the VTL code inside the definitions.

The prettyprint feature formats the VTL script in a user-friendly way.

Important

The prettyprint and model_validation features require the pysdmx[vtl] extra.

Parameters:

  • transformation_scheme (TransformationScheme) – A TransformationScheme object.

  • model_validation (bool) – A boolean value to check if the model object is valid. if True, the model object is validated.

  • prettyprint (bool) – A boolean value to check if the generated script is returned formatted.

Return type:

str

Returns:

A string containing the full VTL Transformation Scheme script.

Validate VTL objects

pysdmx.toolkit.vtl.model_validations(model_obj)

Validation checks for VTL objects.

This method performs validation checks on VTLScheme objects , such as TransformationScheme, RulesetScheme, UserDefinedOperatorScheme, etc. or its items, like Ruleset, Transformation, UserDefinedOperator, etc.

It raises an Invalid exception if the model object is not valid.

The model validation checks on items:

  • Ruleset validation

    • A single RulesetDefinition (define …) is valid in a Ruleset

    • Ruleset type matches the definition (hierarchical or datapoint)

    • Ruleset scope matches the signature (variable or valuedomain)

  • User Defined Operator validation

    • A single OperatorDefinition (define operator …) is valid in a User Defined Operator

  • Transformation validation

    • Checks if the transformation is valid

    • Checks a single assignment is present in the expression

The model validation checks on VTLScheme:

  • RulesetScheme validation

    • Checks if it contains at least one Ruleset

    • Checks if all items in the scheme are Ruleset

  • UserDefinedOperatorScheme validation

    • Checks if it contains at least one UserDefinedOperator

    • Checks if all items in the scheme are UserDefinedOperator

  • TransformationScheme validation

    • Checks if it contains at least one Transformation

    • Checks if all items in the scheme are Transformation

    • Checks the referenced RulesetSchemes (if any) and UserDefinedOperatorSchemes (if any)

Parameters:

model_obj (Union[VtlScheme, Item]) – A VTLScheme or Item object.

Raises:

Invalid – Invalid model object if the model object is not valid.

Return type:

None

Convert dataset between SDMX and VTL formats

pysdmx.toolkit.vtl.convert_dataset_to_vtl(dataset, vtl_dataset_name)

Convert a PandasDataset to a vtlengine Dataset.

This function converts a PandasDataset, which contains both data and structure (Schema), into a vtlengine Dataset. It uses vtlengine’s conversion functions to handle the Schema to VTL structure mapping.

It raises an Invalid exception if the dataset structure is not a Schema object.

Parameters:

  • dataset (PandasDataset) – The PandasDataset to convert.

  • vtl_dataset_name (str) – The name for the vtlengine Dataset.

Return type:

Dataset

Returns:

A vtlengine Dataset with the data and structure from the PandasDataset.

Raises:

Invalid – If the dataset structure is not a Schema object or if component types cannot be mapped.

pysdmx.toolkit.vtl.convert_dataset_to_sdmx(dataset, reference=None, schema=None)

Convert a VTLengine Dataset to a PandasDataset.

This function converts a vtlengine.Model.Dataset into a PandasDataset by:

  • Using a provided Schema for direct validation and conversion.

  • Generating a new SDMX-compatible Schema from the dataset components, using metadata from a provided Reference.

When a schema is supplied, the dataset is first validated against it and, if validation passes, the data is wrapped in a PandasDataset with that schema. If no schema is provided, a reference must be given so a new SDMX structure (with components, roles, and data types mapped from the VTL dataset) can be created.

Invalid is raised in the following cases:

  • If neither schema nor reference is provided.

  • If the reference has an unsupported sdmx_type.

  • If the dataset contains no data.

  • If component types or roles cannot be mapped to SDMX equivalents.

  • If validation fails when a schema is provided.

Parameters:

  • dataset (Dataset) – The VTLengine dataset to convert. Must include components and associated data.

  • reference (Optional[Reference]) – Optional reference to the SDMX structure (DataStructure, Dataflow, or ProvisionAgreement). Required only when no schema is provided. Used to build a schema and supply contextual identifiers.

  • schema (Optional[Schema]) – Optional schema describing the SDMX structure. If provided, the dataset is validated against it and the same schema is used directly in the output.

Return type:

PandasDataset

Returns:

A PandasDataset containing the converted data and the associated SDMX structure (either the provided schema or a generated one).

Raises:

Invalid – If the reference sdmx_type is not valid, if component types cannot be mapped, or if validation fails when schema is provided.