qgserde - v0.3.1
    Preparing search index...

    qgserde - v0.3.1

    qgserde

    Read, edit, and write QGIS project files in TypeScript.

    qgserde exposes a typed model for .qgs XML. The model is independent of the input QGIS version: choose a target version each time you serialize it. This site covers the editing rules and the public API. Try it in the demo.

    import { parseQgs, serializeQgs } from "qgserde";

    const project = parseQgs(qgsXml);
    project.title = "Sapporo";
    project.crs = { authId: "EPSG:4326" };

    for (const layer of project.layers) {
    layer.opacity = 0.8;
    if (layer.type === "vector") {
    layer.labelsEnabled = true;
    for (const field of layer.fields) field.alias = field.name;
    }
    }

    const qgis3Xml = serializeQgs(project, { version: "3.44" });
    const qgis4Xml = serializeQgs(project, { version: "4.2" });

    Your application handles file I/O. Pass decoded Unicode strings to parseQgs and save the output of serializeQgs as UTF-8. An XML declaration, when present, is written with UTF-8 encoding.

    import { createProject, serializeQgs } from "qgserde";

    const project = createProject({ title: "Cities" });
    project.crs = { authId: "EPSG:4326" };
    project.layers.push({
    type: "vector",
    id: "qgserde_cities_001",
    name: "Cities",
    provider: "ogr",
    source: "./cities.gpkg|layername=cities",
    crs: { authId: "EPSG:4326" },
    fields: [],
    });

    const xml = serializeQgs(project, { version: "4.2" });

    createProject() returns an empty project with an empty title, metadata object, layer array, and root tree group. Set title in the options object to give it a name.

    To start from an existing QGS file, use parseQgs and edit the resulting model:

    const project = parseQgs(qgsXml);
    project.title = "Regional map";

    QgsProject contains ordinary objects and arrays. Identifiers, expressions, dates, and data source URIs are strings. Coordinates, scales, and opacity are numbers; flags are booleans.

    Type Settings
    QgsProject Title, layers, CRS, view, layer tree, properties, relations, themes, and bookmarks.
    QgsProjectMetadata Identifier, language, author, abstract, creation date, and other descriptive metadata.
    QgsCrs Authority ID, WKT, PROJ definition, and QGIS CRS metadata.
    QgsRectangle / QgsReferencedRectangle Numeric bounds and an optional extent CRS.
    QgsVectorLayer Common layer settings, geometry, labels, fields, and renderer.
    QgsVectorRenderer Single-symbol, categorized, graduated, rule-based, and null renderers.
    QgsVectorLabeling Simple and rule-based labeling, label settings, text formats, and callouts.
    QgsSymbol / QgsSymbolLayer Symbol layers, their properties, data-defined properties, and sub-symbols.
    QgsRasterLayer Renderer, contrast, shader, palette, transparency, filters, resampling, and no-data.
    QgsField Alias, editor widget and its settings, default value, constraints, and form behavior.
    QgsMapLayerBase Flags, custom properties, blend mode, map tip, legend, time, elevation, and metadata.
    QgsLayerTreeGroup / QgsLayerTreeLayer Groups, layer references, check states, drawing order, and node custom properties.

    Check layer.type to narrow the QgsMapLayer union. Vector layers expose fields; raster layers expose band settings through renderer. Other recognized types each have their own interface (QgsMeshLayer, QgsVectorTileLayer, QgsPointCloudLayer, QgsPluginLayer, QgsAnnotationLayer, QgsGroupLayer, and QgsTiledSceneLayer); settings that are not modeled stay in extension data. An unrecognized type becomes QgsUnknownLayer, with its original type name in xmlType.

    Vector tile layers model their basic renderer and labeling styles; mesh layers their renderer settings (scalar shaders, mesh frames, averaging); annotation layers their items with symbols and text formats (vector tile layers also their tile matrix set); group layers their child layer IDs; point cloud and tiled scene layers their renderers. The project's main annotation layer, with its items, is project.mainAnnotationLayer.

    Editor-widget identifiers and symbol layer classes remain strings because QGIS plugins can extend them. Field settings affect the project; they do not change the data source schema or feature values.

    Check renderer.type to narrow QgsVectorRenderer. The discriminants are the QGIS renderer names: singleSymbol, categorizedSymbol, graduatedSymbol, RuleRenderer, nullSymbol, heatmapRenderer, pointDisplacement, pointCluster, invertedPolygonRenderer, mergedFeatureRenderer, and 25dRenderer. Wrapper renderers hold the renderer they wrap in renderer. Other renderers, such as plugin renderers, are unknown, with the QGIS name in xmlType; their type-specific settings stay in extension data. Every renderer can have a paint effect, an orderBy list, and data-defined properties; symbol layers can have their own effect. Effect stacks list their effects in effects.

    if (layer.type === "vector" && layer.renderer?.type === "categorizedSymbol") {
    layer.renderer.categories.push({
    value: "park",
    label: "Park",
    render: true,
    symbol: {
    type: "fill",
    layers: [{ class: "SimpleFill", properties: { color: "0,160,0,255" } }],
    },
    });
    }

    Symbols are nested in the class or rule that uses them. The codec numbers stored symbols and their references on every write, in the order QGIS uses. QGIS gives each stored symbol to one class; a class without a symbol, or whose symbol is already taken, is read without one and discarded by QGIS.

    QgsSymbolLayer.properties holds class-specific settings with the keys QGIS uses, such as color for SimpleFill or line_width for SimpleLine. Colors are strings such as "255,0,0,255". QGIS before 3.18 reads properties only as <prop> elements; later versions read an <Option> map. The codec writes the form the target reads and drops the redundant copy that QGIS 3.18 to 3.3x also wrote. Nested property values cannot be written for targets before 3.18.

    Data-defined properties are keyed by the QGIS property name, such as size or fillColor for symbol layers and alpha for symbols. Each records active and a type: 1 for a static val, 2 for a field, or 3 for an expression.

    Property maps, data-defined properties, and other <Option> values use QgsVariant. A value whose Qt type is the one QGIS writes for it is plain: a string (QString), boolean (bool), integer (int, or qlonglong when large), non-integer (double), array (List), object (Map), or null (invalid). QGIS writes an empty map without a type, and qgserde reads such an <Option/> as {}. Any other type is tagged, so the model keeps it:

    { "@type": "double", value: 1 }        // an integral double
    { "@type": "StringList", value: ["a"] }
    { "@type": "color", value: "255,0,0,255" }
    { "@type": "QgsProperty", value: { active: true, type: 3 } }
    { "@type": "QgsCoordinateReferenceSystem", xml: [/* <spatialrefsys> */] }

    A tagged value must fit its type; replace the whole tag to change the type. A type qgserde does not decode keeps its child elements in xml. A map whose only keys are @type, value, or xml is tagged as "Map". Map entries are written sorted by key, as QGIS does. Category values keep their stored type when QGIS would read the same value back; integers beyond the safe JavaScript range stay strings.

    Assign a new renderer object to change the renderer type. A renderer whose type is changed in place keeps unmodeled data for the old type, which the new type ignores.

    Rule scale limits are denominators: minScaleDenominator is the most zoomed-in scale and maxScaleDenominator the most zoomed-out one, as in QGIS's scalemindenom and scalemaxdenom.

    layer.labelsEnabled switches labels on; layer.labeling holds the settings. Check labeling.type to narrow it: simple has one settings object, and rule-based has a rootRule with nested children, like rule-based renderers.

    if (layer.type === "vector") {
    layer.labelsEnabled = true;
    layer.labeling = {
    type: "simple",
    settings: {
    fieldName: "name",
    format: {
    style: { fontSize: 10, textColor: "0,0,0,255" },
    buffer: { bufferDraw: true, bufferSize: 1 },
    },
    placement: { placement: 1 },
    },
    };
    }

    QGIS label settings have well over a hundred options. Groups that QGIS stores as element attributes are typed attribute groups (see Attribute groups), such as fontSize in format.style or dist in placement. Font families, tab positions, substitutions, background symbols, callouts, and data-defined properties have their own structure. Effects and other unmodeled children stay with the element that contains them.

    QgsRasterRenderer keeps band numbers and opacity typed, and models the parts each renderer type uses: contrast enhancements, min/max origin, a pseudocolor shader with color items, a paletted palette, pixel transparency, and legend settings. Settings QGIS stores as attributes, such as classificationMin, are typed attribute groups; settings stored as child text, such as minValue, are typed child-text groups. The layer's brightnessContrast, hueSaturation, resampler, resamplingStage, providerResampling, and per-band noData hold the other pipe stages. Raster layers also model file-based attributeTables and, for QGIS 4, pixel value labeling.

    Removing an optional setting removes the element that stores it; a list stored in its own container, such as noData, removes the container.

    QGIS stores per-field settings in layer-level lists keyed by field name. Each QgsField collects them: alias, editorWidgetType and editorWidgetConfig, default value, constraints and their strengths, split, duplicate, and merge policies, comment, and editable, labelOnTop, and reuseLastValue. Renaming a field renames all of its records.

    Vector layers also model diagram renderers (pie, histogram, text, and stacked subRenderers, with categories, their fields, and a data-defined size legend) and diagramSettings, virtual expressionFields, joins, data and layer dependencies, actions, the attribute table, conditional styles, stored expressions, the attribute form (including drag-and-drop items with container, field, and other kinds), relation editor widgets, geometry options, and relations kept with the layer.

    Every layer type models its named style variants (styles): the current style name and each variant's stored settings in style, with the same names and types as on the layer, such as renderer, labeling, opacity, and, for vector layers, fields. QGIS stores the current variant empty because the layer itself holds it, and does not re-apply current on load. Layers also model their 3D renderer (renderer3d: symbols with placement, material, and edges; rules; categories), other <maplayer> attributes, flags, customProperties, blendMode, map tip, notes, legend settings and text on legend symbols, temporal and elevation settings, metadata (including temporal extents), and server publishing settings, such as WMS dimensions. Custom properties are written as <property> elements for QGIS before 3.20, which cannot store nested values, and as an <Option> map afterwards. QGIS writes <expressionfields> twice; both copies are kept identical.

    Adding a layer to project.layers adds a tree reference and an entry in any existing drawing-order list when serialized. Removing a layer removes its tree and order references. A tree reference holds only the layer ID; its name, source, and provider are written from the layer, so layer edits reach every reference. A reference to a layer outside the project keeps its stored values.

    Layer IDs are read-only: tree, drawing-order, relation, join, layout, and plugin references use them. A layer with another ID is another layer.

    Layer IDs must have at least 11 UTF-16 code units. QGIS replaces shorter IDs on load, leaving tree and drawing-order references unresolved, even when the provider is valid. Serialization rejects these IDs with INVALID_EDIT. This also applies to unchanged IDs read from XML. To repair a short ID, assign a longer one (for example, "states_wms_layer"); tree and order references update on serialization.

    An authority ID is enough to assign a CRS:

    project.crs = { authId: "EPSG:3857" };
    

    Replace the CRS object when changing its definition so that old WKT or PROJ values are not carried over. qgserde handles QGIS's CRS lookup conventions; callers do not need its internal CRS database. Assigning project.crs also enables project projection. Removing an active CRS disables it. A disabled CRS read from XML is modeled as project.disabledCrs. An active project.crs takes precedence over that stored definition. Both use the same CRS writer. No geographic data or extent coordinates are reprojected.

    If a CRS read from XML contains only an authority ID, serialization adds the missing srsid lookup marker required by QGIS. Existing IDs, WKT and PROJ definitions are preserved as modeled values. User-defined (USER:) IDs are not completed; serializing one without WKT or PROJ causes INVALID_EDIT.

    A CRS also keeps its coordinateEpoch and, for a topocentric CRS, its topocentricBase CRS.

    project.extent can carry its own CRS in extent.crs. An extent without one uses the project CRS. Rotation is clockwise, in degrees.

    The codec writes the default extent to ProjectViewSettings for QGIS 3.10.1 and later, and rotation there for QGIS 3.28 and later. Older targets use mapcanvas. Equivalent representations in the input stay synchronized; independent view settings are modeled in project.legacyView and encoded from those values. A target that cannot represent both settings causes INVALID_EDIT.

    Editing project.title updates the root title, metadata title, and projectname attribute together.

    QGIS 4 stores project properties as <properties name="Key">; QGIS 3 stores them as <Key>. A QGIS 3 target rewrites QGIS 4 properties as element names. If both forms of a key are present, the name form is used. A key that is not a valid XML name cannot be written for QGIS 3 and causes INVALID_EDIT. QGIS 4 targets keep the format of the input.

    project.properties is the QGIS project property tree: nested keys holding strings, numbers, booleans, and string lists, such as Variables, Measurement, Measure/Ellipsoid, and the WMS* keys used by QGIS Server. Stored value types are kept when the kind of value is unchanged. New keys use the form of the tree they are added to, and QGIS 3 targets convert QGIS 4 named entries as before. SpatialRefSys/ProjectionsEnabled is not part of the model; it follows project.crs.

    The project also models its transaction mode and flags, relations and polymorphic relations, map themes, bookmarks, the coordinate transform context, snapping, server data-defined properties, elevation shading, predefined scales, style, time, terrain, display, and GPS settings, map canvas annotations, the QGIS 2 legend of older projects, other root attributes such as saveUser, and project metadata keywords, contacts, links, history, and dates. It also models 3D map views (mapViews3D) with their scene settings, camera, and animation; reports; sensors; stored processingModels; the preset full extent; labeling engine rules; and, for QGIS 4.2, elevationProfiles and selective masking source sets. Layer-tree nodes model their other attributes, such as mutually-exclusive, legend patch shapes, and custom properties; QGIS 4.2 custom nodes have type: "custom".

    project.layouts lists print layouts. Each has its pages, items, and multiFrames (such as attribute tables), atlas settings, guides, and custom properties. A QgsLayoutItem has the QGIS item type number in type (for example 65639 for maps and 65641 for labels) and its settings in attributes, such as labelText, position, and size. Items also model their colors, data-defined and custom properties, symbols, text formats, map extents, CRS, locked layers and style overrides, label-blocking items, grids and overviews, polyline nodes, group members, legend styles, trees, and map filters, scale bar symbols and number formats, elevation profile and chart plots, and 3D map scenes. Manual tables model their headers, cells, row heights, and column widths. QGIS reads only the parts an item type uses. Unmodeled item children stay with their item.

    Settings that QGIS stores as attributes of one element, such as a text buffer's bufferSize or a layout item's positionLock, are attribute groups. Each group has a generated interface, such as QgsTextBufferAttributes, keyed by the QGIS attribute name. Values are numbers, booleans, or strings, according to how QGIS writes them; absent keys take QGIS defaults.

    const buffer = settings.format.buffer;
    if (buffer) {
    buffer.bufferDraw = true; // stored as 1
    buffer.bufferSize = 1.5;
    }

    Attributes a group does not type, and values that do not parse as their kind, such as nan, are not part of the group; they stay unmodeled XML and are written back unchanged. Setting the typed key replaces such a value. A key that is not part of the group fails with INVALID_EDIT. Namespace declarations (xmlns:*) are never part of a group.

    The interfaces and their attribute kinds are generated from the QGIS 3.44 and 4.2 writers by scripts/generate-attributes.py; see CONTRIBUTING.md.

    XML a layer's model does not cover is kept in its unmodeled property as plain data: attributes and child nodes keyed by the path of the modeled element that holds them ("." for the <maplayer> itself, "srs/spatialrefsys" for a descendant), each child with the modeled sibling it follows. Edit, copy, or delete it like any other property; copying a layer copies it. Data under an element the model no longer writes, such as a removed CRS, is dropped with it. Modeled values take precedence over unmodeled attributes of the same name. Unmodeled data of a field's records, such as an unknown attribute on its <alias>, is kept in the field's own unmodeled ("aliases/alias"), so it follows the field through renames and reordering. <maplayer> children are written in the order the target QGIS version writes them, and unmodeled children follow their recorded sibling.

    Other objects still keep unknown data and element positions in internal extensions while they move to the same scheme. The original XML string and a complete XML tree are not kept in the model.

    Known settings always pass through the intermediate model and are reconstructed on every write, even when unchanged. Parsed, JSON-restored, and new models use the same validation and normalization rules. Unknown elements and their parent–child relationships and order are preserved. Comments, CDATA, and processing instructions are retained. Byte-for-byte reproduction is not guaranteed: numeric and boolean spelling, quotes, empty-element syntax, entity notation, and XML line-ending normalization may differ; modeled values are written as QGIS writes them. Unknown strings, including leading zeros, remain strings. Layers are indented with two spaces per level, as QGIS does; elsewhere existing whitespace is kept.

    Legacy aliases and defaults without field configuration become typed fields. Duplicate alias/default records for the same field are rejected with INVALID_PROJECT; missing alias names or default expressions become empty strings. Operations that would erase unknown nested elements or collapse distinct view settings fail with INVALID_EDIT. Explicit removal of a modeled object removes that object's associated data.

    Store models with serializeJson and restore them with parseJson:

    import { parseJson, serializeJson } from "qgserde";

    const saved = serializeJson(project);
    const restored = parseJson(saved);
    const xml = serializeQgs(restored, { version: "4.2" });

    The output has the form {"qgserde":"<version>","project":{...}}. parseJson accepts JSON written by a compatible qgserde version: the same major version, or the same minor version before 1.0. Other versions cause INVALID_VERSION, because the unmodeled and extensions formats may change between them. Malformed JSON or a missing envelope causes INVALID_JSON. The model itself is validated when it is written with serializeQgs.

    The internal extensions property holds the unknown data and order needed for reconstruction and has no public editing API. Serialization does not mutate the model, including when it fails.

    Pass a QGIS 3 or 4 version to every serializeQgs call. "3.40" is normalized to "3.40.0"; release names such as "3.40.0-Bratislava" and "4.2.0-Belém do Pará" are accepted. Missing or malformed versions, and target major versions other than 3 or 4, cause INVALID_VERSION.

    The same model can be written for different versions, including after JSON storage. Known properties are encoded for the requested target. Unmodeled plugin settings and other unmodeled features are preserved without version conversion. Choosing a version does not guarantee that the target QGIS installation supports every feature in the project.

    parseQgisVersion parses version syntax into major, minor, patch, and an optional suffix. It defaults a missing patch to zero; the restriction to QGIS 3 and 4 is enforced by serialization.

    Catch QgsError and use its code to classify a failure. Messages provide context and should not be used for branching.

    import { parseQgs, QgsError } from "qgserde";

    try {
    const project = parseQgs(qgsXml);
    } catch (error) {
    if (error instanceof QgsError) console.error(error.code, error.message);
    else throw error;
    }
    Code Meaning
    INVALID_XML Malformed XML, unsupported XML syntax, an internal DTD subset, or excessive depth.
    INVALID_PROJECT Invalid root, missing required attributes, or invalid modeled values.
    INVALID_JSON Malformed JSON or a missing qgserde JSON envelope.
    INVALID_VERSION Invalid version syntax, a missing target, an unsupported target major version, or incompatible JSON.
    INVALID_EDIT An edit that would lose data, duplicate IDs, cycles, non-finite numbers, or other invalid model data.

    qgserde handles QGS XML strings. QGZ archives, QGD databases, attachments, and geographic data are outside its scope. It does not check data source availability or rewrite paths for another project location. It validates XML and known properties, rather than the full QGIS schema.

    Only XML 1.0 is supported. External DTDs are never fetched. Internal DTD subsets, custom entities, cyclic structures, and XML deeper than 512 levels are rejected.

    The package is ESM and requires Node.js 24 or later. The library uses no Node.js APIs or browser DOM; browser applications need a bundler and structuredClone. For source setup and QGIS integration tests, see CONTRIBUTING.md.

    qgserde is licensed under the GNU Affero General Public License, version 3 or any later version (AGPL-3.0-or-later). Third-party material retains its original license; see the fixture sources and licenses.