.Stat Suite constraints beyond SDMx
Question. Several SDMx conventions are optional in SDMx 3.1. Are any of them mandatory because of how .Stat Suite parses, stores or displays data?
Short answer. .Stat Suite publishes official documentation for its constraints, at https://sis-cc.gitlab.io/dotstatsuite-documentation/. Sources were read on 2026-10-23; where a page or changelog entry carries a release date, it is quoted. The constraints fall into three groups:
- Hard in the platform. Upload, storage or structure management refuses the structure or the data. This covers lengths, versions, finality, patch-version rules, a few annotations and MeasureDimension.
- Soft in the Data Explorer (DE). The data loads, but a feature disappears. This is where FREQ and TIME_PERIOD live. DE recognises them by id or concept role. Without them, the time filter, the timeline chart and the map are hidden.
- Product intentions that are not documented as implemented. The DLM product vision says "FREQ is always the first concept" and "TIME_PERIOD is always a TimeDimension". No implementing documentation, code or error message was found.
So "FREQ first" and "TIME_PERIOD last" are not documented as .Stat requirements.
What .Stat does depend on is the ids TIME_PERIOD and FREQ/FREQUENCY, or the
matching concept roles.
How the evidence was gathered:
- Three independent research passes covered the core/transfer/NSI docs, the DE/DLM docs, and source code plus the issue tracker.
- The main claims were then re-read in the primary pages; the items below are those. Items taken from code are marked CODE.
- GitLab code search needs a login. Only a few source files reachable by raw URL were read, so absence of a check in code is not evidence that no check exists.
Page paths below are relative to https://sis-cc.gitlab.io/dotstatsuite-documentation/.
1. Hard constraints (upload, storage or structure management fails)
| # | Constraint | Component | Source (quote) |
|---|---|---|---|
| H1 | MeasureDimension is not supported. | Core | using-api/core-data-model/: "This special SDMX 2.1 'MeasureDimension' construct is not implemented in the .Stat Suite Core because in SDMX 3.0 it will be transformed into a normal Dimension with a role 'Measure'." |
| H2 | One measure. On coded or non-numeric measures, the page contradicts itself. | Core | Same page, model section: "There must be at least one Measure, the default is called the PrimaryMeasure … coded … this is not yet implemented … only the double number type is currently imlemented". The page's version note says: ".Stat Suite supports the use of non-numeric and coded measure values since March 5, 2021 Release .Stat Suite .NET 6.0.0". |
| H3 | Component ids (dimension, attribute, measure, group) ≤ 50 characters in the data database. The structure database accepts 255. | Core DB | using-api/supported-lengths/: "Keep component IDs at 50 characters or less." |
| H4 | Codes ≤ 150 characters once the codelist is used by a DSD. Time-period values ≤ 30. Agency id ≤ 50 for artefacts used by data. | Core DB | Same page: "the 150-character limit applies as soon as the codelist is referenced by a DSD". Time period value: effective limit 30. Agency: "50 for artefacts used by data". |
| H5 | Artefact version: "3 numeric parts, each within the 32-bit integer range" (and "10 characters as text" in the permissions database). | Structure, Data and Common DB | Same page, "Artefact version" row. Consequence for semver: see §4.2. |
| H6 | Sub-daily time periods need the DSD annotation SUPPORT_DATETIME before data is uploaded. |
Core / Transfer | using-api/core-data-model/: "by default only time periods without a time component … are supported. In case a DSD requires … hours, minutes, seconds or milli-seconds, this needs to be communicated through the annotation of type SUPPORT_DATETIME". |
| H7 | Intentionally missing values need the DSD annotation SUPPORT_INTENT_MISS_VALUES. |
Core | Same page: "Intentionally missing values are supported only when the DSD has the annotation of type 'SUPPORT_INTENT_MISS_VALUES'." |
| H8 | Finality. A final artefact can only be replaced if its main content is unchanged. A non-final artefact can only be replaced if nothing references it. Nothing referenced can be deleted. | NSI | using-api/api-main-features/: "Final artefacts can only be replaced, if the main content is not changed … adding or removing Codes from a Codelist are not permitted." "Non-final artefacts can only be replaced, if they are not referenced by other artefacts." "Artefacts can only be deleted if they are currently not beeing referenced by any other structural artefact." |
| H9 | A final artefact must not reference a non-final one. This is announced as a future import-time check. | NSI / DLM | changelog/, June 12, 2026, patch release ".NET jackfruit" (nsi-ws v10.11.6, the version SPC runs): "a final artefact referencing a non-final artefact. This configuration is not supported in SDMX 3 and will cause deletion failures … A permanent fix (validating that a final artefact cannot reference a non-final artefact at import time) will be integrated in the future." |
| H10 | Patch-version groups. Versions sharing major.minor share one data store. A patch version may not add or remove dimensions, attributes or measures, add or remove the time dimension, change coded ↔ non-coded, change MSD, or introduce a new codelist. Versions must be loaded from lowest to highest. "A version without a patch part is part of the group. 1.0 holds the data for 1.0.1, 1.0.2". |
Transfer / Core DB | using-api/patch-versions/ (since August 15, 2026 Release .NET "kiwi"). Guidance on the same page: "Increment the minor or major part as soon as the set of valid values or the structure itself changes … Do not use a patch increment in these cases: it will be refused". |
| H11 | Non-final codelist or concept scheme behind a DSD: get-data JSON/CSV queries failed. | get-data service | changelog/, August 15, 2026 section: "dotstatsuite-core-getdata#117 get-data JSON/CSV queries fail when the DSD references a non-final codelist or concept scheme." Listed as fixed; relevant only where the get-data service is deployed. |
| H12 | Historical: non-sequential dimension position values made the upload fail. |
NSI / DLM | changelog/, Release .NET "blueberry", September 22, 2022: "dotstatsuite-data-lifecycle-manager#235 Dimension position: Error when uploading non-sequential positions." Fixed. |
2. Soft constraints (Data Explorer hides or degrades a feature)
| # | Convention | What happens without it | Source |
|---|---|---|---|
| S1 | Time dimension with id TIME_PERIOD (or concept role TIME_PERIOD) |
No time-period filter, no timeline chart | using-api/typical-use-cases/: "For the time dimension, we should search for the ID TIME_PERIOD." "Other IDs, such as TIME and YEAR, are not supported as TimeDimension for now." CODE: DE src/web/lib/rules/dimension-utils.js (develop): isTimePeriodDimension = dimension.role === 'TIME_PERIOD' || dimension.id === 'TIME_PERIOD'. The docs disagree: using-de/viewing-data/common-features/ describes a further fallback "by its concept ID or by its dimension ID". |
| S2 | Frequency dimension with id FREQ or FREQUENCY, or concept role FREQ |
DE falls back to a TIME_FORMAT attribute, then to the spacing of observations. If all fail, the time filter and timeline are hidden |
using-de/viewing-data/common-features/: "The frequency dimension can be recognised by its role: 'FREQ' … If such role is not available/found, then by its concept ID or by its dimension ID: 'FREQ' or 'FREQUENCY'." "If no frequency dimension, time-format attribute and time dimension are found, then the time period/frequency filter and the timeline chart menu option are disabled/hidden." CODE: FREQ_DIM_IDS = new Set(['FREQ', 'FREQUENCY']). using-api/typical-use-cases/: "dataflows with data for only one frequency might not have defined a specific frequency dimension." No position requirement anywhere. |
| S3 | One frequency per view | A selection that mixes frequencies is invalid | using-de/viewing-data/common-features/: "data views only allow for the display of data for one frequency at the time". |
| S4 | Geography dimension (role GEO/REF_AREA, or id REF_AREA, COUNTRY, LOCATION, REGION, REFERENCE_AREA) |
No choropleth map | common-features/ and CODE dimension-utils.js (REF_AREA_ROLES, REF_AREA_IDS). |
| S5 | Actual content constraints (availability) | Empty filters and "There is no data available." | using-de/viewing-data/filters/data-availability/: "a dataflow that has no data, which is indicated by the fact that the actual content constraints are empty, then the filters are also empty (without values) and the data table/view is replaced with the text 'There is no data available.'". In .Stat these constraints are auto-generated at every upload (using-dlm/manage-data/upload-data/). |
| S6 | Categorisation | The dataflow is not indexed for search | using-de/searching-data/indexing-data/: only dataflows categorised in the configured category schemes are indexed. |
| S7 | One dataflow version per id in search | Only one version is indexed | Same page: "if there are dataflows, categorised for search indexing, with the same ID, but with different Agencies or different Versions, then only one of them is indexed (first version retrieved through dataflow/all/ID/latest). In such a case, it is needed to create and categorise separate dataflows with different IDs." |
3. Intentions not documented as implemented
using-dlm/product_vision/ (user journeys for creating DSDs in the DLM):
- "see mandatory (FREQ) and recommended concepts which are automatically pre-selected"
- "change the order of selected concepts (not allowed?) FREQ is always the first concept."
- "TIME_PERIOD is always a TimeDimension and is selected by default. FREQ is always a FrequencyDimension."
This is a product-vision page. The "(not allowed?)" shows the rule was still open, and no other page, code or error message confirms it is implemented. Status: intention only. Ask SIS-CC.
4. What this means for the readiness rules and for SPC
4.1 Rules affected
| Rule | .Stat evidence | Consequence |
|---|---|---|
| DSD-008 (FREQ first) | S2: DE needs FREQ by id or role, not first. §3: "FREQ first" is only a product intention | Keep as INFO. A separate check "time dimension present but no FREQ/FREQUENCY id, FREQ role or TIME_FORMAT attribute" would match DE behaviour exactly. Candidate .Stat-profile rule |
| DSD-001 (TIME_PERIOD last) | No .Stat rule on position. H10: reordering dimensions changes "the structure itself", so on .Stat the reordered DSD needs a minor or major version and the data must be re-uploaded (a patch version would be refused or misleading) | The SDMx fix is mechanical; on .Stat it costs a data reload. 42 SPC DSDs. This applies the documented H10 guidance to reordering; reordering is not in the explicit list of refused changes. Confirm with SIS-CC. |
| DSD-002 (MeasureDimension) | H1: not supported by .Stat | Cannot occur in a .Stat data space; the rule only matters for non-.Stat sources |
| VER-005 (final -> non-final) | H9: "not supported in SDMX 3"; an import-time check is announced | On .Stat this becomes a hard rule. Raise VER-005 to BLOCKER in a .Stat profile |
Migration plan (X.Y -> X.Y.0[-draft]) |
H5: versions are "3 numeric parts". H10: "1.0 holds the data for 1.0.1, 1.0.2" | Moving 1.0 to 1.0.0 stays in the same version group, so data is kept (inference: a version written as 1.0.0 should belong to the 1.0 group; not stated explicitly). A -draft extension cannot be stored as a version, so non-finality presumably stays the internal isFinal flag, rendered as -draft in 3.x output. The SIS-CC QA NSI does this: 35 non-final X.Y.Z artefacts are served as X.Y.Z-draft in SDMX-ML 3.0. Inference, confirm with SIS-CC. |
| MOD-004 (Actual constraints) | S5: DE filters and "no data" depend on actual constraints | When 3.1 drops maintained Actual constraints, DE must use the /availability API. SPC's NSI does not serve it as SDMX-ML 3.1 yet (406) |
| MOD-005 (hierarchical codelists) | using-de/viewing-data/filters/advanced-hierarchies/: "The application of advanced hierarchies is defined through a DSD and/or dataflow SDMX annotation of type HIER_CONTEXT … this is a work-around for the not yet available SDMX 3.0 HierarchyAssociation artefact" |
Remodelling SPC's 7 HCLs as 3.1 Hierarchies also means replacing the HIER_CONTEXT annotations that point at them, and waiting for DE support for HierarchyAssociation |
4.2 SPC facts this adds
- Parallel dataflow versions are invisible in search. SDG 4.2 / 4.3 / 4.4 are 18 dataflows each, sharing ids. Only one version per id is indexed (S7).
- No final artefacts at all. All 887 SPC artefacts are non-final, so H9 does not fire today. Once SPC finalises a DSD, every codelist and concept scheme it references must be final as well.
- TIME_PERIOD second in 42 DSDs. DE is unaffected, because it finds the time dimension by id. The 3.1 migration will force a new minor or major version, and a data reload, for those DSDs (§4.1).
5. Candidate ".Stat profile" rules
These are .Stat product limits, not SDMx rules. They would be a separate, optional profile
(e.g. --profile dotstat) so other organisations' reports stay comparable. None is
implemented yet.
| Candidate | Basis | Severity in the .Stat profile |
|---|---|---|
| Component id > 50 characters; code > 150 characters in a codelist used by a DSD; agency id > 50 for data artefacts (H3, H4) | supported-lengths |
BLOCKER |
| Version not expressible as 3 numeric parts within 32-bit integers, or longer than 10 characters (H5) | supported-lengths |
BLOCKER |
| MeasureDimension (H1) | core-data-model |
BLOCKER |
| Final artefact references a non-final artefact (H9) | changelog June 12, 2026 | BLOCKER (VER-005 raised) |
| Time dimension without FREQ/FREQUENCY id, FREQ role or TIME_FORMAT attribute (S2) | common-features + DE code |
WARNING (DE time filter hidden) |
| Time dimension with an id other than TIME_PERIOD and no TIME_PERIOD role (S1) | typical-use-cases + DE code |
WARNING |
| Dataflow not categorised (S6); several versions of one dataflow id categorised (S7) | indexing-data |
INFO |
6. Questions for SIS-CC
- Does the DLM enforce "FREQ is always the first concept" / "TIME_PERIOD is always a TimeDimension" (product vision), or is it intention only?
- Is moving TIME_PERIOD to the end of the dimension list a patch-level change, or does it need a new minor/major version and a data reload?
- How will .Stat store SDMx 3.1 version extensions (
1.0.0-draft), given that versions are "3 numeric parts"? Is-draftonly how the NSI rendersisFinal=false? - Is
1.0.0stored in the same version group as1.0? - Which
common-featurestime-dimension fallback is current: TIME_PERIOD id or role only (code), or also concept id / dimension id (docs)?