Rule catalogue

<!-- Generated by uv run sdmx-readiness rules --markdown > docs/RULES.md. Do not edit by hand: change the @rule(...) metadata in sdmx_readiness/rules/*.py and regenerate. -->

Target: a direct move from SDMx 2.1 to SDMx 3.1. Definitions of severity, basis and change kind: docs/METHODOLOGY.md section 6. Rules still to be validated: docs/RULES_REVIEW.md.

VER-001

Artefact version is neither a legacy nor a semantic version - BLOCKER; basis SCHEMA; change decision; Versioning

• Applies to: every maintainable artefact
• Source: SDMX-ML 3.1 SDMXCommonReferences.xsd: VersionType = union of LegacyVersionNumberType '(0|[1-9]\d*)(.(0|[1-9]\d*))?' and SemanticVersionNumberType; SDMX-ML 2.1 VersionType was '[0-9]+(.[0-9]+)*'.
• Why: SDMx 3.1 accepts only legacy versions (MAJOR or MAJOR.MINOR, no leading zeros) or semantic versions (MAJOR.MINOR.PATCH[-EXTENSION], no leading zeros, no '+build'). SDMx 2.1 accepted any dotted number, so values such as '1.03', '01.0' or '1.0.0.0' are valid today and invalid in 3.1.
• Fix: Re-version the artefact; prefer the semantic version obtained by padding with zeros.

VER-002

Reference uses an invalid version (or a wildcard combined with an extension) - BLOCKER; basis SCHEMA; change decision; Versioning

• Applies to: structural references
• Source: SDMX-ML 3.1 SDMXCommonReferences.xsd: WildcardVersionType = VersionReferenceType (legacy | semver | SemanticVersionReferenceType with '+' on one of MAJOR/MINOR/PATCH) | WildcardType ('*'); Section 6, 14.4: version extensions 'cannot be combined with a wildcard'.
• Why: A reference version must be legacy, semver, a '+' wildcard (X+.Y.Z, X.Y+.Z, X.Y.Z+) or ''. Forms such as '1.', '1.0+.0-draft' or '1.03' are invalid.
• Fix: Point the reference at a valid version or wildcard.

VER-003

Semantically versioned artefact references a non-semver artefact - BLOCKER; basis STANDARD; change decision; Versioning

• Applies to: artefacts whose own version is X.Y.Z or X.Y.Z-EXT (not Categorisations or organisation schemes, which are unversioned in SDMx 3.1)
• Source: SDMx 3.1 Section 6, 4.3.4 and 14.4: 'Semantically versioned artefacts MUST only reference other semantically versioned artefacts.'
• Why: Generalises rule 1 of the original OECD script (3-digit parent -> 2-digit child). Any structural reference from a semver artefact to a legacy (X.Y) target violates a MUST of the standard: the target offers no change guarantee, so the parent's own guarantee is void.
• Fix: Migrate the referenced artefact to semver first (bottom-up: codelists -> concept schemes -> DSDs -> dataflows), then repoint the reference.

VER-004

Stable semver artefact references a version-extended (draft) artefact - WARNING; basis GUIDELINE; change decision; Versioning

• Applies to: artefacts whose own version is X.Y.Z (not Categorisations or organisation schemes)
• Source: SDMx 3.1 Section 6, 14.4: 'References to specific version-extended artefacts MAY be used'; 4.3.2: 'Draft artefacts should not be used outside of a specific system designed to accommodate them.' Advisory: the reference is allowed.
• Why: Replaces rules 2-3 of the original script. Allowed by the standard, but the stable artefact then depends on content that may still change, so its immutability is only nominal.
• Fix: Release the referenced artefact as a stable version and repoint the reference.

VER-005

Final (isFinal=true) artefact references a non-final artefact - WARNING; basis GUIDELINE; change decision; Versioning

• Applies to: SDMX-ML 2.1 artefacts with isFinal=true (not Categorisations or organisation schemes)
• Source: Derived, not an explicit SDMx rule: SDMx 3.1 Section 6, 14.5 maps isFinal=true X.Y -> X.Y.0 and isFinal=false X.Y -> X.Y.0-draft, which turns this reference into VER-004 after migration.
• Why: After the mechanical migration, the final parent becomes a stable X.Y.0 that references an X.Y.0-draft (VER-004), i.e. the 'final' artefact already depends on mutable content today.
• Fix: Finalise the referenced artefact before migrating, or accept VER-004 after migration.

VER-006

Mechanical semver migration would collide with an existing version - BLOCKER; basis STANDARD; change decision; Versioning

• Applies to: legacy-versioned artefacts (not Categorisations or organisation schemes)
• Source: SDMx 3.1 Section 6, 14.5 (X.Y -> X.Y.0, non-final -> X.Y.0-draft); 4.3: agency, id and version identify an artefact.
• Why: Two artefacts of the same class/agency/id would end up with the same semantic version, e.g. legacy '2.0' and an existing '2.0.0'. The migration needs a human decision on which content wins.
• Fix: Decide which artefact keeps the version; give the other a higher MINOR/MAJOR or retire it.

VER-007

Non-final artefact already carries a stable semantic version - WARNING; basis STANDARD; change decision; Versioning

• Applies to: SDMX-ML 2.1 artefacts with isFinal=false whose version is X.Y.Z
• Source: SDMx 3.1 Section 6, 4.3.2: 'For cases where an artefact is not static ... the version must indicate this by including an EXTENSION'; 14.5: isFinal=false -> '-draft'.
• Why: In 3.1 a version without extension promises immutability, which a non-final artefact does not keep, so a converter must add an extension and the artefact's identity changes between 2.1 and 3.1 (observed on the SIS-CC QA .Stat NSI on 2026-10-23: all 35 such 2.1 artefacts, e.g. OECD.ECO:CL_AREA 1.0.1, are served as 'X.Y.Z-draft' in SDMX-ML 3.0). References to 'X.Y.Z' then stop resolving for 3.1 clients.
• Fix: Finalise the artefact, or version it explicitly as X.Y.Z-draft.

REF-001

Reference cannot be resolved on this endpoint - WARNING; basis OBSERVED; change decision; References

• Applies to: structural references with an exact version, to classes that were fetched
• Source: SDMx 3.1 Section 6, 4.3.4 (references) and 14.4 (semver artefacts MUST only reference semver artefacts, which needs the target to be known).
• Why: A migration is done bottom-up along references. A target missing from the endpoint (deleted, never published to the dissemination space, or owned by another agency) cannot be migrated together with its parent and its versioning cannot be checked. Wildcard references are not resolved.
• Fix: Publish the target, repoint the reference, or confirm it is external and record its owner's versioning.

REF-002

Versioned URN embedded in an annotation - INFO; basis OBSERVED; change mechanical; References

• Applies to: annotation title/text/URL/value of any artefact
• Source: No SDMx rule: annotation text is free text that the schemas do not interpret; SDMx references are the Ref/URN elements of the structure model.
• Why: Tools such as .Stat Suite store versioned URNs in annotations (e.g. DSD 'METADATA' -> MSD). Migration tools rewrite structural references but not annotation text, so these silently keep pointing at the old version. SDMx 3.1 has a structural way to do this (DataStructure/Metadata).
• Fix: Include annotation URNs in the migration script; update them when the target is re-versioned.

MOD-001

Artefact that is unversioned in SDMx 3.1 is published in several versions - BLOCKER; basis SCHEMA; change decision; 2.1 -> 3.1 model changes

• Applies to: Categorisation; organisation schemes (in SDMX-ML 2.1 Agency, DataProvider and DataConsumer schemes are fixed at 1.0, so in practice OrganisationUnitScheme)
• Source: SDMX-ML 3.1 SDMXStructureCategorisation.xsd and SDMXStructureOrganisation.xsd (OrganisationSchemeBaseType): version use="prohibited". SDMx 3.1 Summary of major changes, 2.2 (p.5): 'If multiple versions of a Categorisation exist where the source or target differs, these Categorisations should be given a unique ID.'
• Why: In 3.1 these artefacts are identified by agency + id only, so several versions of one id collide. The rule fires even when source and target are the same in every version: the ids still collide.
• Fix: Keep one artefact per id (the latest), re-id or delete the others.

MOD-002

Constraint uses a Release Calendar - BLOCKER; basis SCHEMA; change remodel; 2.1 -> 3.1 model changes

• Applies to: ContentConstraint
• Source: SDMx 3.1 Summary of major changes, 2.1 'Removal of Advanced Release Calendar'; SDMX-ML 3.1 SDMXStructureConstraint.xsd ConstraintType has no ReleaseCalendar.
• Why: The release calendar no longer exists on constraints in 3.1 and is lost on conversion.
• Fix: Move the information to reference metadata on the dataflow / provision agreement (the guidance given in the major-changes document).

MOD-003

Constraint attached to a target that SDMx 3.1 no longer allows - BLOCKER; basis SCHEMA; change decision; 2.1 -> 3.1 model changes

• Applies to: ContentConstraint
• Source: SDMx 3.1 Section 1, 2.4 'Restrict constraint targets to Identifiable structures (not URLs)'; SDMX-ML 3.1 SDMXStructureConstraint.xsd ConstraintAttachmentType.
• Why: 3.1 constraints attach only to DataProvider, MetadataProvider, DataStructure, MetadataStructure, Dataflow, Metadataflow, ProvisionAgreement or MetadataProvisionAgreement. Attachments to SimpleDataSource, QueryableDataSource, DataSet or MetadataSet are lost.
• Fix: Re-attach to the dataflow, DSD, provision agreement or data provider.

MOD-004

Maintained 'Actual' constraint - WARNING; basis SCHEMA; change mechanical; 2.1 -> 3.1 model changes

• Applies to: ContentConstraint with type=Actual (explicit, or by default: 2.1 'type' defaults to Actual)
• Source: SDMX-ML 3.1 SDMXStructureConstraint.xsd: DataConstraint has no type/role attribute, and AvailabilityConstraintType extends AnnotableType (no id, agency or version: not maintainable). SDMx 3.1 Summary of major changes, 3.2 'Constraint Cohesion': the Availability Constraint 'is not a maintained structure', generated by the availability REST API. SDMX-ML 2.1: ContentConstraint type default="Actual".
• Why: In 3.1 every Data Constraint restricts what may be reported. Stored 'Actual' constraints have no maintained counterpart: they are dropped, and availability is computed by the /availability API instead.
• Fix: Stop maintaining actual constraints; make sure the endpoint serves /availability in SDMX-ML 3.1 (see capabilities).

MOD-005

SDMx 2.1 artefact type that does not exist in SDMx 3.1 - BLOCKER; basis SCHEMA; change remodel; 2.1 -> 3.1 model changes

• Applies to: HierarchicalCodelist, StructureSet, AttachmentConstraint
• Source: SDMX-ML 3.1 schemas define no HierarchicalCodelist, StructureSet or AttachmentConstraint. SDMx 3.0 Summary of major changes, 3.1 'Removed Maintainable Artefacts' (pp.10-11): Structure Set -> Structure Map + item scheme maps; Hierarchical Codelist -> Hierarchy + Hierarchy Association; Constraint -> Data/Metadata Constraint (AttachmentConstraint has no documented replacement).
• Why: These artefacts cannot be carried over 1:1; they must be remodelled, and servers may silently drop them from 3.x output.
• Fix: Remodel by hand or with a dedicated converter; the target model is given in the message.

MOD-006

Organisation scheme carries a version other than 1.0 - WARNING; basis SCHEMA; change mechanical; 2.1 -> 3.1 model changes

• Applies to: organisation schemes with a single version (several versions: MOD-001)
• Source: SDMX-ML 3.1 SDMXStructureOrganisation.xsd OrganisationSchemeBaseType: version use="prohibited"; SDMx 3.1 Section 6, 4.3.1: these artefacts follow the legacy versioning 'with a fixed version set to 1.0'.
• Why: The version disappears in 3.1, so the scheme's identity changes and references that name the old version no longer match.
• Fix: Re-publish the scheme as version 1.0 and repoint references before migrating.

DSD-001

Time dimension is not the last dimension - WARNING; basis SCHEMA; change mechanical; DSD structure (2.1 -> 3.1)

• Applies to: SDMX-ML 2.1 DataStructure with a TimeDimension
• Source: SDMx 3.1 Section 2 (Information Model) 5.3.2: 'The Time Dimension, when specified, must be the last within the Dimension Descriptor.' SDMX-ML 3.1 SDMXStructureDataStructure.xsd DimensionListType is a sequence Dimension+, TimeDimension?. SDMX-ML 2.1 used an unbounded choice, so any order was valid.
• Why: Valid in 2.1, invalid in 3.1. Moving TIME_PERIOD to the end does not change series keys (the time dimension 'is not represented as a member of the ordered key', DimensionListType documentation, 2.1 and 3.1), but the position of every dimension after it shifts, and 3.1 requires positions to match the order (DSD-006).
• Fix: Move TIME_PERIOD to the end of the DimensionList and renumber the positions of the dimensions that followed it.

DSD-002

DSD uses a MeasureDimension - BLOCKER; basis SCHEMA; change remodel; DSD structure (2.1 -> 3.1)

• Applies to: SDMX-ML 2.1 DataStructure
• Source: SDMx 3.0 Summary of major changes, 3.5 (pp.14-15): 'the MeasureDimension has been deprecated and replaced with the option to define zero or more measures'; SDMX-ML 3.1 DimensionListType has no MeasureDimension. SDMx 3.1 Section 6, 11.2 gives two remodels: a Dimension with concept role MEASURE, or one Measure per concept of the measure dimension's concept scheme.
• Why: There is no 3.1 element for it. The two documented remodels give different data messages, so the owner must choose (Section 6, 11.2: the Dimension route is required if data must 'resemble that of SDMX 2.1 Structure Specific').
• Fix: Choose between a MEASURE-role Dimension and multiple Measures; remodel the DSD and its dataflows.

DSD-003

Attribute attached to dimensions and attachment groups - BLOCKER; basis SCHEMA; change decision; DSD structure (2.1 -> 3.1)

• Applies to: SDMX-ML 2.1 Attribute with AttributeRelationship/AttachmentGroup
• Source: SDMX-ML 3.1 SDMXStructureDataStructure.xsd AttributeRelationshipType is a choice of Dataflow | Dimension+ | Group | Observation, with no AttachmentGroup; SDMx 3.1 Section 2, 5.3.2: 'these relationships are mutually exclusive, and therefore only one of the following is possible'.
• Why: The combination 'these dimensions, within these groups' cannot be expressed in 3.1; part of the attachment is lost.
• Fix: Decide whether the attribute attaches to the dimensions or to the group.

DSD-004

Group defined by an attachment constraint - BLOCKER; basis SCHEMA; change remodel; DSD structure (2.1 -> 3.1)

• Applies to: SDMX-ML 2.1 Group with AttachmentConstraint
• Source: SDMX-ML 3.1 SDMXStructureDataStructure.xsd GroupType allows only GroupDimension+; AttachmentConstraint artefacts do not exist in 3.1 (MOD-005).
• Why: Neither the group form nor the referenced artefact exists in 3.1.
• Fix: Redefine the group by its dimensions, or attach the attributes another way.

DSD-005

DSD declares a ReportingYearStartDay attribute - BLOCKER; basis SCHEMA; change decision; DSD structure (2.1 -> 3.1)

• Applies to: SDMX-ML 2.1 AttributeList/ReportingYearStartDay
• Source: SDMX-ML 3.1 SDMXStructureDataStructure.xsd AttributeListType is a choice of Attribute | MetadataAttributeUsage, with no ReportingYearStartDay element (the 3.1 unique-id selector still names it, an inconsistency in the schema).
• Why: The special attribute has no 3.1 element; how to carry the reporting-year start day is not documented.
• Fix: Model it as an ordinary attribute (id REPORTING_YEAR_START_DAY, text type MonthDay) and confirm with the SDMx TWG.

DSD-006

Dimension position does not match its place in the dimension list - WARNING; basis SCHEMA; change mechanical; DSD structure (2.1 -> 3.1)

• Applies to: SDMX-ML 2.1 Dimension / MeasureDimension with a position attribute
• Source: SDMX-ML 3.1 BaseDimensionType 'position': 'must be consistent with the position of the dimension in the key descriptor'. SDMX-ML 2.1 said the list order 'always takes precedence' and position is 'strictly for informational purposes'.
• Why: Tolerated in 2.1 (order wins), invalid in 3.1. Tools that trust 'position' read the key in the wrong order.
• Fix: Renumber positions to follow the list order.

DSD-007

Text attribute relies on the isMultiLingual default, which flips in 3.1 - WARNING; basis SCHEMA; change mechanical; DSD structure (2.1 -> 3.1)

• Applies to: SDMX-ML 2.1 Attribute with a String, Alpha, AlphaNumeric or XHTML TextFormat (textType defaults to String) and no isMultiLingual
• Source: SDMX-ML 2.1 SDMXStructureBase.xsd TextFormatType isMultiLingual default="true"; SDMX-ML 3.1 default="false".
• Why: Without an explicit value, these attributes are multilingual in 2.1 and single-language in 3.1. (The 2.1 PrimaryMeasure cannot carry isMultiLingual, so it is not checked; a remodelled 3.1 Measure can.)
• Fix: Write isMultiLingual="true" explicitly to keep the 2.1 meaning, or confirm that single-language is intended.

DSD-008

No frequency dimension, or frequency is not the first dimension - INFO; basis GUIDELINE; change none; DSD modelling guidelines

• Applies to: SDMX-ML 2.1 DataStructure with a TimeDimension
• Source: SDMX-ML 2.1 and 3.1 DimensionListType documentation (identical text): 'Any data structure definition which uses the time dimension should also declare a frequency dimension, conventionally the first dimension in the key'. Not enforced by the schema; SDMx 1.0 Implementor's Guide 2.5 (non-normative) has the same convention.
• Why: Unchanged between 2.1 and 3.1, so not a migration issue; reported because it is the most common DSD convention.
• Fix: None required. Frequency is detected by dimension id FREQ or concept role FREQ.

DSD-009

Same concept used as a dimension and as an attribute - INFO; basis GUIDELINE; change none; DSD modelling guidelines

• Applies to: SDMX-ML 2.1 DataStructure
• Source: SDMx Guidelines for the design of DSDs 1.0 (2013), 5.2: 'Each concept can only be used once as a dimension or an attribute in one DSD'; SDMx 1.0 Implementor's Guide 2.5 item 16. Both non-normative.
• Why: Not a 3.1 change; a modelling-quality check.
• Fix: None required by 3.1.

DSD-010

More than 7 key dimensions - INFO; basis GUIDELINE; change none; DSD modelling guidelines

• Applies to: SDMX-ML 2.1 DataStructure
• Source: SDMx 3.1 Section 6, 3.4.1.2 (guidance): 'A DSD with the number dimensions in excess 6 or 7 is often difficult for non-specialist users to understand.'
• Why: Not a 3.1 change; usability guidance. The threshold 7 is our reading of '6 or 7'.
• Fix: None required by 3.1.

MSD-001

Metadata Structure Definition has metadata targets / report structures - BLOCKER; basis SCHEMA; change remodel; MSD structure (2.1 -> 3.1)

• Applies to: SDMX-ML 2.1 MetadataStructure that declares a MetadataTarget or a ReportStructure
• Source: SDMx 3.0 Summary of major changes, 3.4 (p.13): 'The Metadata Structure Definition (MSD) has been simplified to remove target information, and the support of multiple report structures'; SDMx 3.1 Section 2, 7.3.2: 'target objects are contained in Metadataflow and MetadataProvisionAgreement'; SDMX-ML 3.1 MetadataStructureComponentsType = MetadataAttributeList only.
• Why: The targets must move to Metadataflows / Metadata Provision Agreements and report structures be merged or split into several MSDs.
• Fix: Remodel: one MSD per report structure, targets on the metadataflow.

XF-001

Artefact served in SDMX-ML 2.1 but missing from the SDMX-ML 3.1 output - WARNING; basis OBSERVED; change remodel; Endpoint conversion (2.1 vs 3.1 output)

• Applies to: endpoints that serve both SDMX-ML 2.1 and 3.1
• Source: Endpoint behaviour; compares (class, agency, id, version) across the two outputs (Categorisations: agency, id).
• Why: The server cannot represent the artefact in 3.1, so 3.1 clients will not see it. Artefacts served under a rewritten version are XF-003 instead.
• Fix: Remodel the artefact (see MOD-005) or report the conversion gap to the platform team.

XF-002

Artefact only served in SDMX-ML 3.1 - INFO; basis OBSERVED; change none; Endpoint conversion (2.1 vs 3.1 output)

• Applies to: endpoints that serve both SDMX-ML 2.1 and 3.1
• Source: SDMx 3.1 Section 6, 14.5 (p.120): 'some cases of semantically versioned SDMX 3.0 artefacts cannot be converted back to earlier SDMX versions', e.g. parallel '-draft' extensions.
• Why: Expected for 3.1-native artefacts; listed so 2.1-only consumers know what they miss.
• Fix: None required.

XF-003

Artefact served under a different version in SDMX-ML 3.1 - WARNING; basis OBSERVED; change decision; Endpoint conversion (2.1 vs 3.1 output)

• Applies to: endpoints that serve both SDMX-ML 2.1 and 3.1
• Source: SDMx 3.1 Section 6, 14.5 (isFinal=false -> '-draft'); 4.3: artefact identifiers 'are qualified by their version numbers'.
• Why: The server rewrites the version when converting (e.g. non-final 2.1 '1.0.1' becomes '1.0.1-draft'). The same artefact then has two identities: 2.1 references to '1.0.1' do not resolve for 3.1 clients, and the 3.1 version is not the one the owner chose.
• Fix: Make the 2.1 version explicit (finalise it, or version it X.Y.Z-draft); see VER-007.