Document Purpose: Explain XBRL's built-in versioning capabilities for tracking and documenting changes between taxonomy versions, including the Versioning specification, report formats, and practical applications
Last Updated: January 2026
Target Audience: Taxonomy developers, XBRL implementers, change managers
The Challenge:
Taxonomies evolve over time. Concepts are added, deprecated, or modified. Relationships change. Understanding what changed between versions is critical for:
The Problem with Manual Change Tracking:
XBRL Solution: The Versioning Specification
XBRL International provides a formal specification for creating machine-readable version reports that document all changes between taxonomy versions.
Key Features:
Result:
Taxonomies are NOT static.
Example: US GAAP Taxonomy Evolution
US GAAP 2022 → US GAAP 2023 → US GAAP 2024
Changes in 2023:
├─ New concepts: 156 added
├─ Deprecated concepts: 43 removed
├─ Modified concepts: 89 changed
├─ New relationships: 234 added
├─ Modified relationships: 167 changed
└─ Label changes: 312 updated
Changes in 2024:
├─ New concepts: 142 added
├─ Deprecated concepts: 38 removed
├─ Modified concepts: 76 changed
├─ New relationships: 198 added
├─ Modified relationships: 143 changed
└─ Label changes: 287 updated
Every year, hundreds of changes!
Scenario: Public company must file with new taxonomy version
Questions they need answered:
Without version tracking:
Step 1: Load old taxonomy → Extract concepts used
Step 2: Load new taxonomy → Try to find same concepts
Step 3: Manually compare → Hope nothing is missed
Step 4: Test instance → Find errors
Step 5: Debug → Figure out what changed
Step 6: Fix and repeat
Time: Weeks to months
Risk: High (missed changes)
With version tracking:
Step 1: Load version report
Step 2: Identify changes affecting your concepts
Step 3: Plan migration
Step 4: Execute migration
Step 5: Validate
Time: Days to weeks
Risk: Low (all changes documented)
Scenario: XBRL processor vendor must support new taxonomy version
Questions:
Impact:
Version reports enable automated impact analysis.
Scenario: Banking regulator updates COREP/FINREP taxonomy
Requirements:
Version reports provide authoritative change documentation.
Scenario: Company extends standard taxonomy
Challenge:
Version reports enable systematic extension updates.
Concept Changes:
Relationship Changes:
Label Changes:
Reference Changes:
Structural Changes:
Official Name: Versioning 1.0
Status: Recommendation (2013)
Namespace: http://xbrl.org/2010/versioning
Purpose: Define standard format for taxonomy version reports
Key Concepts:
Version Report
├─ FromTaxonomy (old version)
├─ ToTaxonomy (new version)
└─ Changes
├─ ConceptChanges
├─ RelationshipSetChanges
├─ LabelChanges
└─ ReferenceChanges
Basic Structure:
<?xml version="1.0" encoding="UTF-8"?>
<ver:versioningReport
xmlns:ver="http://xbrl.org/2010/versioning"
xmlns:vercu="http://xbrl.org/2010/versioning-concept-use"
xmlns:vercb="http://xbrl.org/2010/versioning-concept-basic"
xmlns:verrel="http://xbrl.org/2010/versioning-relationship-sets"
xml:lang="en">
<!-- Document information -->
<ver:namespacePrefixes>
<ver:namespacePrefix prefix="us-gaap-2023">
http://fasb.org/us-gaap/2023
</ver:namespacePrefix>
<ver:namespacePrefix prefix="us-gaap-2024">
http://fasb.org/us-gaap/2024
</ver:namespacePrefix>
</ver:namespacePrefixes>
<!-- Identify taxonomies being compared -->
<ver:reportRef
xlink:type="simple"
xlink:href="us-gaap-2023.xsd"
ver:role="from"/>
<ver:reportRef
xlink:type="simple"
xlink:href="us-gaap-2024.xsd"
ver:role="to"/>
<!-- Changes go here -->
<ver:changes>
<!-- Concept changes -->
<!-- Relationship changes -->
<!-- Label changes -->
<!-- Reference changes -->
</ver:changes>
</ver:versioningReport>
<vercb:conceptAdd>
<vercb:toConceptRef xlink:type="resource">
<vercb:qname>us-gaap-2024:ContractWithCustomerAssetGross</vercb:qname>
<vercb:periodType>instant</vercb:periodType>
<vercb:dataType>xbrli:monetaryItemType</vercb:dataType>
</vercb:toConceptRef>
<ver:customAttribute name="reason">
New ASU 2024-XX requires disclosure of gross contract assets
</ver:customAttribute>
</vercb:conceptAdd>
Meaning:
ContractWithCustomerAssetGross added in 2024 taxonomy<vercb:conceptDelete>
<vercb:fromConceptRef xlink:type="resource">
<vercb:qname>us-gaap-2023:AvailableForSaleSecurities</vercb:qname>
</vercb:fromConceptRef>
<ver:customAttribute name="reason">
Deprecated - replaced by new classification approach
</ver:customAttribute>
</vercb:conceptDelete>
Meaning:
<vercb:conceptChange>
<vercb:fromConceptRef xlink:type="resource">
<vercb:qname>us-gaap-2023:LeaseLiability</vercb:qname>
<vercb:periodType>instant</vercb:periodType>
<vercb:balance>credit</vercb:balance>
</vercb:fromConceptRef>
<vercb:toConceptRef xlink:type="resource">
<vercb:qname>us-gaap-2024:LeaseLiability</vercb:qname>
<vercb:periodType>instant</vercb:periodType>
<vercb:balance>credit</vercb:balance>
<vercb:nillable>true</vercb:nillable>
</vercb:toConceptRef>
<vercb:conceptAttributeChange>
<vercb:attribute>nillable</vercb:attribute>
<vercb:oldValue>false</vercb:oldValue>
<vercb:newValue>true</vercb:newValue>
</vercb:conceptAttributeChange>
</vercb:conceptChange>
Meaning:
LeaseLiability modifiednillable changed from false to true<vercu:conceptExtendedUse>
<vercu:fromConceptRef xlink:type="resource">
<vercu:qname>us-gaap-2023:Revenue</vercu:qname>
</vercu:fromConceptRef>
<vercu:toConceptRef xlink:type="resource">
<vercu:qname>us-gaap-2024:Revenue</vercu:qname>
</vercu:toConceptRef>
<vercu:dimensionChange>
<vercu:dimension>us-gaap:ProductOrServiceAxis</vercu:dimension>
<vercu:changeType>domainExtended</vercu:changeType>
<vercu:newMembers>
<vercu:member>us-gaap:SubscriptionServiceMember</vercu:member>
<vercu:member>us-gaap:CloudServiceMember</vercu:member>
</vercu:newMembers>
</vercu:dimensionChange>
</vercu:conceptExtendedUse>
Meaning:
Revenue can now use additional dimension members<verrel:relationshipSetChange>
<!-- Presentation relationship added -->
<verrel:relationshipSet>
<verrel:linkRole>
http://fasb.org/us-gaap/role/BalanceSheet
</verrel:linkRole>
<verrel:arc>link:presentationArc</verrel:arc>
</verrel:relationshipSet>
<verrel:relationships>
<!-- New parent-child relationship -->
<verrel:relationshipAdd>
<verrel:fromConcept>
us-gaap-2024:Assets
</verrel:fromConcept>
<verrel:toConcept>
us-gaap-2024:ContractWithCustomerAssetGross
</verrel:toConcept>
<verrel:order>1.5</verrel:order>
<verrel:preferredLabel>
http://www.xbrl.org/2003/role/label
</verrel:preferredLabel>
</verrel:relationshipAdd>
</verrel:relationships>
</verrel:relationshipSetChange>
Meaning:
ContractWithCustomerAssetGross is now child of Assets<verrel:relationshipSetChange>
<verrel:relationshipSet>
<verrel:linkRole>
http://fasb.org/us-gaap/role/IncomeStatement
</verrel:linkRole>
<verrel:arc>link:calculationArc</verrel:arc>
</verrel:relationshipSet>
<verrel:relationships>
<!-- Calculation weight changed -->
<verrel:relationshipChange>
<verrel:fromConcept>
us-gaap:NetIncomeLoss
</verrel:fromConcept>
<verrel:toConcept>
us-gaap:OtherComprehensiveIncomeLoss
</verrel:toConcept>
<verrel:fromWeight>1.0</verrel:fromWeight>
<verrel:toWeight>-1.0</verrel:toWeight>
</verrel:relationshipChange>
</verrel:relationships>
</verrel:relationshipSetChange>
Meaning:
<ver:labelChange>
<ver:fromLabel>
<ver:concept>us-gaap-2023:CashAndCashEquivalents</ver:concept>
<ver:role>http://www.xbrl.org/2003/role/label</ver:role>
<ver:lang>en-US</ver:lang>
<ver:text>Cash and Cash Equivalents, at Carrying Value</ver:text>
</ver:fromLabel>
<ver:toLabel>
<ver:concept>us-gaap-2024:CashAndCashEquivalents</ver:concept>
<ver:role>http://www.xbrl.org/2003/role/label</ver:role>
<ver:lang>en-US</ver:lang>
<ver:text>Cash and Cash Equivalents</ver:text>
</ver:toLabel>
<ver:customAttribute name="reason">
Simplified label for clarity
</ver:customAttribute>
</ver:labelChange>
Meaning:
<ver:referenceChange>
<ver:fromReference>
<ver:concept>us-gaap-2023:LeaseLiability</ver:concept>
<ver:reference>
<ver:Name>Accounting Standards Codification</ver:Name>
<ver:Topic>842</ver:Topic>
<ver:SubTopic>20</ver:SubTopic>
<ver:Section>45</ver:Section>
<ver:Paragraph>1</ver:Paragraph>
</ver:reference>
</ver:fromReference>
<ver:toReference>
<ver:concept>us-gaap-2024:LeaseLiability</ver:concept>
<ver:reference>
<ver:Name>Accounting Standards Codification</ver:Name>
<ver:Topic>842</ver:Topic>
<ver:SubTopic>20</ver:SubTopic>
<ver:Section>45</ver:Section>
<ver:Paragraph>1</ver:Paragraph>
<ver:Paragraph>2</ver:Paragraph>
</ver:reference>
</ver:toReference>
</ver:referenceChange>
Meaning:
<?xml version="1.0" encoding="UTF-8"?>
<ver:versioningReport
xmlns:ver="http://xbrl.org/2010/versioning"
xmlns:vercb="http://xbrl.org/2010/versioning-concept-basic"
xmlns:vercu="http://xbrl.org/2010/versioning-concept-use"
xmlns:verrel="http://xbrl.org/2010/versioning-relationship-sets"
xmlns:xlink="http://www.w3.org/1999/xlink"
xml:lang="en">
<!-- Metadata -->
<ver:documentInfo>
<ver:title>US GAAP Taxonomy Version Report: 2023 to 2024</ver:title>
<ver:description>
Documents changes between US GAAP Taxonomy 2023 and 2024 versions.
This report includes 142 concept additions, 38 concept deletions,
76 concept modifications, and 341 relationship changes.
</ver:description>
<ver:publishDate>2023-12-15</ver:publishDate>
<ver:publisher>FASB (Financial Accounting Standards Board)</ver:publisher>
<ver:version>1.0</ver:version>
</ver:documentInfo>
<!-- Namespace prefixes -->
<ver:namespacePrefixes>
<ver:namespacePrefix prefix="us-gaap-2023">
http://fasb.org/us-gaap/2023
</ver:namespacePrefix>
<ver:namespacePrefix prefix="us-gaap-2024">
http://fasb.org/us-gaap/2024
</ver:namespacePrefix>
</ver:namespacePrefixes>
<!-- From and To taxonomies -->
<ver:reportRef
xlink:type="simple"
xlink:href="https://xbrl.fasb.org/us-gaap/2023/us-gaap-2023.xsd"
ver:role="from">
<ver:taxonomyInfo>
<ver:version>2023</ver:version>
<ver:releaseDate>2023-01-25</ver:releaseDate>
</ver:taxonomyInfo>
</ver:reportRef>
<ver:reportRef
xlink:type="simple"
xlink:href="https://xbrl.fasb.org/us-gaap/2024/us-gaap-2024.xsd"
ver:role="to">
<ver:taxonomyInfo>
<ver:version>2024</ver:version>
<ver:releaseDate>2024-01-31</ver:releaseDate>
</ver:taxonomyInfo>
</ver:reportRef>
<!-- Changes -->
<ver:changes>
<!-- EXAMPLE 1: New concept added for crypto assets -->
<vercb:conceptAdd>
<vercb:toConceptRef xlink:type="resource">
<vercb:qname>us-gaap-2024:DigitalAssetsCrypto</vercb:qname>
<vercb:periodType>instant</vercb:periodType>
<vercb:dataType>xbrli:monetaryItemType</vercb:dataType>
<vercb:balance>debit</vercb:balance>
<vercb:nillable>true</vercb:nillable>
</vercb:toConceptRef>
<ver:customAttribute name="asuReference">ASU 2023-08</ver:customAttribute>
<ver:customAttribute name="reason">
New accounting standard for crypto assets effective 2024
</ver:customAttribute>
<ver:customAttribute name="category">New Disclosure</ver:customAttribute>
</vercb:conceptAdd>
<!-- EXAMPLE 2: Deprecated concept removed -->
<vercb:conceptDelete>
<vercb:fromConceptRef xlink:type="resource">
<vercb:qname>us-gaap-2023:AvailableForSaleSecuritiesGrossUnrealizedGains</vercb:qname>
</vercb:fromConceptRef>
<ver:customAttribute name="deprecatedSince">2022</ver:customAttribute>
<ver:customAttribute name="replacementConcept">
us-gaap-2024:DebtSecuritiesAvailableForSaleUnrealizedGains
</ver:customAttribute>
<ver:customAttribute name="reason">
Replaced by more specific debt securities concept
</ver:customAttribute>
</vercb:conceptDelete>
<!-- EXAMPLE 3: Concept data type changed -->
<vercb:conceptChange>
<vercb:fromConceptRef xlink:type="resource">
<vercb:qname>us-gaap-2023:NumberOfOperatingSegments</vercb:qname>
<vercb:dataType>xbrli:integerItemType</vercb:dataType>
</vercb:fromConceptRef>
<vercb:toConceptRef xlink:type="resource">
<vercb:qname>us-gaap-2024:NumberOfOperatingSegments</vercb:qname>
<vercb:dataType>num:nonNegativeIntegerItemType</vercb:dataType>
</vercb:toConceptRef>
<vercb:conceptAttributeChange>
<vercb:attribute>dataType</vercb:attribute>
<vercb:oldValue>xbrli:integerItemType</vercb:oldValue>
<vercb:newValue>num:nonNegativeIntegerItemType</vercb:newValue>
</vercb:conceptAttributeChange>
<ver:customAttribute name="reason">
Changed to enforce non-negative values
</ver:customAttribute>
</vercb:conceptChange>
<!-- EXAMPLE 4: New presentation relationship -->
<verrel:relationshipSetChange>
<verrel:relationshipSet>
<verrel:linkRole>
http://fasb.org/us-gaap/role/StatementBalanceSheet
</verrel:linkRole>
<verrel:arc>link:presentationArc</verrel:arc>
</verrel:relationshipSet>
<verrel:relationships>
<verrel:relationshipAdd>
<verrel:fromConcept>us-gaap-2024:Assets</verrel:fromConcept>
<verrel:toConcept>us-gaap-2024:DigitalAssetsCrypto</verrel:toConcept>
<verrel:order>1.45</verrel:order>
<verrel:preferredLabel>
http://www.xbrl.org/2003/role/label
</verrel:preferredLabel>
</verrel:relationshipAdd>
</verrel:relationships>
</verrel:relationshipSetChange>
<!-- EXAMPLE 5: Calculation relationship added -->
<verrel:relationshipSetChange>
<verrel:relationshipSet>
<verrel:linkRole>
http://fasb.org/us-gaap/role/StatementBalanceSheet
</verrel:linkRole>
<verrel:arc>link:calculationArc</verrel:arc>
</verrel:relationshipSet>
<verrel:relationships>
<verrel:relationshipAdd>
<verrel:fromConcept>us-gaap-2024:Assets</verrel:fromConcept>
<verrel:toConcept>us-gaap-2024:DigitalAssetsCrypto</verrel:toConcept>
<verrel:weight>1.0</verrel:weight>
<verrel:order>1.45</verrel:order>
</verrel:relationshipAdd>
</verrel:relationships>
</verrel:relationshipSetChange>
<!-- EXAMPLE 6: Dimensional usage extended -->
<vercu:conceptExtendedUse>
<vercu:fromConceptRef xlink:type="resource">
<vercu:qname>us-gaap-2023:RevenueFromContractWithCustomer</vercu:qname>
</vercu:fromConceptRef>
<vercu:toConceptRef xlink:type="resource">
<vercu:qname>us-gaap-2024:RevenueFromContractWithCustomer</vercu:qname>
</vercu:toConceptRef>
<vercu:dimensionChange>
<vercu:dimension>us-gaap:ProductOrServiceAxis</vercu:dimension>
<vercu:changeType>domainExtended</vercu:changeType>
<vercu:newMembers>
<vercu:member>us-gaap-2024:ArtificialIntelligenceServiceMember</vercu:member>
<vercu:member>us-gaap-2024:QuantumComputingServiceMember</vercu:member>
</vercu:newMembers>
<ver:customAttribute name="reason">
Added emerging technology service categories
</ver:customAttribute>
</vercu:dimensionChange>
</vercu:conceptExtendedUse>
<!-- EXAMPLE 7: Label simplified -->
<ver:labelChange>
<ver:fromLabel>
<ver:concept>us-gaap-2023:CashAndCashEquivalentsAtCarryingValue</ver:concept>
<ver:role>http://www.xbrl.org/2003/role/label</ver:role>
<ver:lang>en-US</ver:lang>
<ver:text>
Cash and Cash Equivalents, at Carrying Value
</ver:text>
</ver:fromLabel>
<ver:toLabel>
<ver:concept>us-gaap-2024:CashAndCashEquivalentsAtCarryingValue</ver:concept>
<ver:role>http://www.xbrl.org/2003/role/label</ver:role>
<ver:lang>en-US</ver:lang>
<ver:text>Cash and Cash Equivalents</ver:text>
</ver:toLabel>
<ver:customAttribute name="reason">
Simplified label - carrying value is implicit
</ver:customAttribute>
</ver:labelChange>
<!-- EXAMPLE 8: Documentation label enhanced -->
<ver:labelChange>
<ver:fromLabel>
<ver:concept>us-gaap-2023:LeaseLiability</ver:concept>
<ver:role>http://www.xbrl.org/2003/role/documentation</ver:role>
<ver:lang>en-US</ver:lang>
<ver:text>
Present value of lessee's obligation to make lease payments.
</ver:text>
</ver:fromLabel>
<ver:toLabel>
<ver:concept>us-gaap-2024:LeaseLiability</ver:concept>
<ver:role>http://www.xbrl.org/2003/role/documentation</ver:role>
<ver:lang>en-US</ver:lang>
<ver:text>
Present value of lessee's obligation to make lease payments,
arising from a lease, measured on a discounted basis. Includes
both current and noncurrent portions.
</ver:text>
</ver:toLabel>
<ver:customAttribute name="reason">
Enhanced documentation for clarity
</ver:customAttribute>
</ver:labelChange>
<!-- EXAMPLE 9: Reference updated -->
<ver:referenceChange>
<ver:fromReference>
<ver:concept>us-gaap-2023:DigitalAssetsCrypto</ver:concept>
<!-- No previous reference - concept was new -->
</ver:fromReference>
<ver:toReference>
<ver:concept>us-gaap-2024:DigitalAssetsCrypto</ver:concept>
<ver:reference>
<ver:Name>Accounting Standards Codification</ver:Name>
<ver:Topic>350</ver:Topic>
<ver:SubTopic>60</ver:SubTopic>
<ver:Section>25</ver:Section>
<ver:Paragraph>1</ver:Paragraph>
<ver:Publisher>FASB</ver:Publisher>
<ver:URI>https://asc.fasb.org/350-60-25-1</ver:URI>
</ver:reference>
</ver:toReference>
<ver:customAttribute name="reason">
Added reference to new ASU 2023-08
</ver:customAttribute>
</ver:referenceChange>
</ver:changes>
<!-- Summary statistics -->
<ver:changeSummary>
<ver:conceptsAdded>142</ver:conceptsAdded>
<ver:conceptsDeleted>38</ver:conceptsDeleted>
<ver:conceptsChanged>76</ver:conceptsChanged>
<ver:relationshipsAdded>234</ver:relationshipsAdded>
<ver:relationshipsDeleted>45</ver:relationshipsDeleted>
<ver:relationshipsChanged>167</ver:relationshipsChanged>
<ver:labelsChanged>312</ver:labelsChanged>
<ver:referencesChanged>89</ver:referencesChanged>
</ver:changeSummary>
</ver:versioningReport>
Key Elements:
1. Metadata Section
2. Namespace Declarations
3. Taxonomy References
from taxonomy (2023)to taxonomy (2024)4. Change Entries
Each change documented with:
5. Summary Statistics
For Business Users:
1. Load version report in viewer/browser
2. Search for concepts you currently use
3. Identify:
├─ Concepts being deprecated
├─ Replacement concepts
├─ Label changes
└─ Relationship changes
4. Plan migration strategy
5. Update filing templates
For Software Systems:
public class VersionReportAnalyzer {
public MigrationPlan analyzeChanges(
File versionReport,
Set<String> conceptsInUse) {
// Parse version report
VersionReport report = VersionReportParser.parse(versionReport);
MigrationPlan plan = new MigrationPlan();
// Check for deprecated concepts in use
for (String conceptQName : conceptsInUse) {
ConceptDelete deletion =
report.getConceptDeletion(conceptQName);
if (deletion != null) {
// This concept is being removed!
String replacement =
deletion.getReplacementConcept();
plan.addDeprecation(conceptQName, replacement);
}
// Check for modifications
ConceptChange change =
report.getConceptChange(conceptQName);
if (change != null) {
// Concept attributes changed
for (AttributeChange attr : change.getAttributeChanges()) {
plan.addModification(conceptQName, attr);
}
}
}
// Check for new concepts that might be relevant
for (ConceptAdd addition : report.getConceptAdditions()) {
// Analyze if new concept is relevant to this filer
if (isRelevant(addition, conceptsInUse)) {
plan.addNewConcept(addition.getQName());
}
}
return plan;
}
public static class MigrationPlan {
private Map<String, String> deprecations = new HashMap<>();
private Map<String, List<AttributeChange>> modifications = new HashMap<>();
private Set<String> newConcepts = new HashSet<>();
public void addDeprecation(String oldConcept, String replacement) {
deprecations.put(oldConcept, replacement);
}
public void addModification(String concept, AttributeChange change) {
modifications.computeIfAbsent(concept, k -> new ArrayList<>())
.add(change);
}
public void addNewConcept(String concept) {
newConcepts.add(concept);
}
public void printReport() {
System.out.println("=== Migration Plan ===");
if (!deprecations.isEmpty()) {
System.out.println("\nDEPRECATED CONCEPTS IN USE:");
for (Map.Entry<String, String> entry : deprecations.entrySet()) {
System.out.println(" ❌ " + entry.getKey());
System.out.println(" → Replace with: " + entry.getValue());
}
}
if (!modifications.isEmpty()) {
System.out.println("\nMODIFIED CONCEPTS IN USE:");
for (Map.Entry<String, List<AttributeChange>> entry :
modifications.entrySet()) {
System.out.println(" ⚠ " + entry.getKey());
for (AttributeChange change : entry.getValue()) {
System.out.println(" - " + change.getAttribute() +
": " + change.getOldValue() +
" → " + change.getNewValue());
}
}
}
if (!newConcepts.isEmpty()) {
System.out.println("\nRELEVANT NEW CONCEPTS:");
for (String concept : newConcepts) {
System.out.println(" ✚ " + concept);
}
}
}
}
}
Usage:
// Load version report
File versionReport = new File("us-gaap-2023-to-2024-version-report.xml");
// Get concepts currently used in our filings
Set<String> conceptsInUse = extractConceptsFromFilings();
// Analyze impact
VersionReportAnalyzer analyzer = new VersionReportAnalyzer();
MigrationPlan plan = analyzer.analyzeChanges(versionReport, conceptsInUse);
// Print migration plan
plan.printReport();
Output:
=== Migration Plan ===
DEPRECATED CONCEPTS IN USE:
❌ us-gaap:AvailableForSaleSecuritiesGrossUnrealizedGains
→ Replace with: us-gaap:DebtSecuritiesAvailableForSaleUnrealizedGains
MODIFIED CONCEPTS IN USE:
⚠ us-gaap:NumberOfOperatingSegments
- dataType: xbrli:integerItemType → num:nonNegativeIntegerItemType
RELEVANT NEW CONCEPTS:
✚ us-gaap:DigitalAssetsCrypto
public class InstanceMigrator {
public XBRLInstance migrate(
XBRLInstance oldInstance,
VersionReport versionReport) {
XBRLInstance newInstance = new XBRLInstance();
// Copy metadata
newInstance.setEntity(oldInstance.getEntity());
newInstance.setPeriod(oldInstance.getPeriod());
// Migrate facts
for (Fact oldFact : oldInstance.getFacts()) {
String conceptQName = oldFact.getConcept();
// Check if concept was deleted
ConceptDelete deletion =
versionReport.getConceptDeletion(conceptQName);
if (deletion != null) {
// Use replacement concept
String newConcept = deletion.getReplacementConcept();
Fact newFact = oldFact.clone();
newFact.setConcept(newConcept);
newInstance.addFact(newFact);
System.out.println("Migrated: " + conceptQName +
" → " + newConcept);
} else {
// Check if concept was modified
ConceptChange change =
versionReport.getConceptChange(conceptQName);
if (change != null) {
// Apply modifications
Fact newFact = applyChanges(oldFact, change);
newInstance.addFact(newFact);
} else {
// Concept unchanged
newInstance.addFact(oldFact);
}
}
}
return newInstance;
}
private Fact applyChanges(Fact fact, ConceptChange change) {
Fact newFact = fact.clone();
for (AttributeChange attr : change.getAttributeChanges()) {
if (attr.getAttribute().equals("dataType")) {
// Validate value against new data type
if (!isValidForType(fact.getValue(), attr.getNewValue())) {
throw new MigrationException(
"Value '" + fact.getValue() +
"' invalid for new type: " + attr.getNewValue());
}
}
}
return newFact;
}
}
For Small Taxonomies:
<!-- Document your changes as you make them -->
<vercb:conceptAdd>
<vercb:toConceptRef xlink:type="resource">
<vercb:qname>company:CustomRevenueConcept</vercb:qname>
<vercb:periodType>duration</vercb:periodType>
<vercb:dataType>xbrli:monetaryItemType</vercb:dataType>
</vercb:toConceptRef>
<ver:customAttribute name="reason">
Added to support new revenue recognition
</ver:customAttribute>
</vercb:conceptAdd>
Best Practices:
Tools can compare two taxonomy versions automatically:
public class VersionReportGenerator {
public VersionReport generateReport(
Taxonomy fromTaxonomy,
Taxonomy toTaxonomy) {
VersionReport report = new VersionReport();
report.setFromTaxonomy(fromTaxonomy);
report.setToTaxonomy(toTaxonomy);
// Compare concepts
Set<String> fromConcepts = fromTaxonomy.getConcepts().keySet();
Set<String> toConcepts = toTaxonomy.getConcepts().keySet();
// Find additions
Set<String> added = new HashSet<>(toConcepts);
added.removeAll(fromConcepts);
for (String concept : added) {
report.addConceptAddition(
toTaxonomy.getConcept(concept));
}
// Find deletions
Set<String> deleted = new HashSet<>(fromConcepts);
deleted.removeAll(toConcepts);
for (String concept : deleted) {
report.addConceptDeletion(
fromTaxonomy.getConcept(concept));
}
// Find modifications
Set<String> common = new HashSet<>(fromConcepts);
common.retainAll(toConcepts);
for (String concept : common) {
Concept fromConcept = fromTaxonomy.getConcept(concept);
Concept toConcept = toTaxonomy.getConcept(concept);
if (!fromConcept.equals(toConcept)) {
report.addConceptChange(fromConcept, toConcept);
}
}
// Compare relationships
compareRelationships(fromTaxonomy, toTaxonomy, report);
// Compare labels
compareLabels(fromTaxonomy, toTaxonomy, report);
return report;
}
}
Automated tools:
Company workflow:
1. SEC announces new taxonomy (November)
2. Download version report (December)
3. Analyze impact:
├─ Load version report
├─ Extract concepts used in last filing
├─ Identify deprecations
└─ Identify new requirements
4. Plan migration (January)
5. Update mapping templates (February)
6. Test with new taxonomy (March)
7. File with new taxonomy (April)
Version report enables early planning.
XBRL processor vendor workflow:
1. New taxonomy version released
2. Load version report
3. Automated analysis:
├─ New concepts → Update metadata
├─ Modified data types → Update validation
├─ New dimensions → Update dimension handling
├─ Changed relationships → Update relationship logic
4. Update conformance test suite
5. Run regression tests
6. Release updated software
EBA updating COREP/FINREP:
1. Create new taxonomy version
2. Generate version report
3. Publish version report alongside taxonomy
4. Banks download version report
5. Banks analyze impact automatically
6. Banks submit questions about specific changes
7. EBA updates version report with clarifications
Version report is official change documentation.
Company extending US GAAP:
Company Extension 2023 (based on US GAAP 2023)
↓
US GAAP 2024 released
↓
Load version report
↓
Check for conflicts:
- Did standard taxonomy add concept I extended?
- Did relationships I use change?
- Are my extensions still valid?
↓
Update extension for US GAAP 2024
DO:
DON'T:
DO:
DON'T:
Recommended approach:
Repository Structure:
├── taxonomies/
│ ├── v2023/
│ │ ├── schema/
│ │ ├── linkbases/
│ │ └── metadata.json
│ ├── v2024/
│ │ ├── schema/
│ │ ├── linkbases/
│ │ └── metadata.json
│ └── versions/
│ ├── v2023-to-v2024-report.xml
│ └── v2022-to-v2023-report.xml
├── mappings/
│ ├── v2023/
│ └── v2024/
└── test-data/
├── v2023/
└── v2024/
Taxonomies evolve constantly:
Without version tracking:
With version reports:
Versioning is built into XBRL
Version reports are machine-readable
Multiple change types supported
Essential for practical XBRL use
Widely used in practice
XBRL versioning turns taxonomy evolution from a problem into a managed process.
Version reports:
For anyone working with XBRL taxonomies, understanding and using version reports is essential.
This document explains XBRL's built-in versioning capabilities, the Version Report specification, and how to use version reports for taxonomy change management and migration planning.