Ontology Versioning
The Carbon Arc Ontology is a dynamic framework designed to evolve with real-world entities, datasets, and user needs. Beginning September 2025, we’re introducing monthly Ontology Versioning to improve consistency, traceability, and control across the platform.
What's New
Starting September 2025:
- A new ontology version will be released monthly (last Thursday of each month)
- Impacted datasets will be automatically reinstated
- Users can download and compare versions (up to 6 months back)
- Versions are tagged using the format
ontology_vYYYY.MM(e.g.,ontology_v2025.08)
Why It Matters
- Build against a stable, versioned ontology
- Separate structural changes (reinstatements) from data refreshes
- Track entity merges, reclassifications, and additions with full transparency
- Align frameworks to the most current entity relationships
Key Definitions
| Term | Description |
|---|---|
| Data Refresh | Adds new data based on provider schedules |
| Data Reinstatement | Rewrites historical data to reflect ontology changes |
| Ontology Version | Timestamped snapshot of the entity-relationship model |
| Entity Lifecycle | Tracks creation, transformation, or deprecation of entities |
| Relationship Taxonomy | Classifies connections (e.g., hierarchical, categorical) |
| Reinstatement Resets Access | Reinstated datasets require a new purchase |
Lifecycle Stages
- Discovery – Identify gaps or new entities
- Definition – Standardize and model nodes and relationships
- Validation – QA and mapping review across datasets
- Versioning – Create and tag new snapshot (e.g.,
2025.08) - Release – Push version to Platform, APIs, and Explorer
- Monitoring – Track mapping drift, edge cases, and issue patches if needed
Entity Lifecycle
Each entity (identified by carc_id) moves through states:
| State | Trigger | Example |
|---|---|---|
| Created | New entity added | New retailer or brand |
| Destroyed | Merged or deprecated | Acquisitions or duplicates |
| Transformed | Ticker or name change | GPS → GAP |
| Reclassified | Taxonomy change | NFLX moves from Tech to Comms |
Internal changes (e.g., metadata corrections) and external events (e.g., M&A, spin-offs, renames) are both tracked.
Relationship Model
Entity relationships are:
- Time-indexed (with start/end dates)
- Classified by type (
is_in_category,has_supplier, etc.) - Stored in a standardized schema
Platform Integration
Ontology versions are surfaced in:
- Ontology Explorer and Platform UI
- Framework metadata (last refresh, reinstatement date, version ID)
- Visual indicators (e.g., red dot when reinstatement is available)
- Order history (purchase vs. refresh vs. reinstatement)
- Python SDK package
Python SDK Usage
Users can leverage the get_framework_status function in the Python SDK to monitor and manage their purchased frameworks. This function provides critical operational intelligence about framework health and maintenance requirements.
get_framework_status
Core Functionality
The get_framework_status function returns comprehensive metadata about any purchased framework, enabling programmatic decision-making around framework lifecycle management.
Response Structure
The function returns a detailed status object containing:
framework_id: Unique identifier for the framework
refresh_available: Boolean indicating if a data refresh can be initiated
reinstatement_available: Boolean flagging whether framework reinstatement is possible
framework_refresh_timestamp: Last refresh execution at the framework level
framework_reinstatement_timestamp: Most recent framework reinstatement timestamp
last_reinstatement_reason: Detailed explanation for reinstatement requirements (e.g., "Vendor Backfill" indicates upstream data provider maintenance)
All Reinstatement Reasons
- Full Refresh: New data increment ready for pipeline processing
- Ontology Change: Material modifications to the ontology structure impacting the data feed
- Vendor Reinstatement: Upstream provider has restated data requiring feed updates
- Enhancement: Carbon Arc optimization to improve data quality or coverage
- Vendor Backfill: Incremental vendor delivery containing limited historical data updates
Key Use Cases
- Automated Monitoring: Build alerts when refresh_available or reinstatement_available flags change
- Vendor Issue Tracking: Monitor node_reinstatement_reason for upstream data provider issues
- Data Freshness Validation: Compare timestamps to ensure data currency meets business requirements
- Operational Dashboards: Surface framework health metrics across your entire data portfolio
- Maintenance Windows: Programmatically identify optimal times for framework updates based on status flags
Status Interpretation
- When both refresh_available and reinstatement_available are False, the framework is operating normally with current data
- Timestamp alignment between framework and node levels indicates synchronized updates
- Reinstatement reasons provide actionable context for data delays or quality issues
This function serves as your primary diagnostic endpoint for framework lifecycle management, ensuring continuous visibility into data pipeline health and enabling proactive issue resolution.
Access & Retention
| Question | Answer |
|---|---|
| How long are versions stored? | 6 months |
| Can I compare versions? | Yes—via Ontology Explorer |
| What triggers reinstatement? | New ontology version or provider-level restatement |
| What if no changes occur? | No version or reinstatement is triggered |
FAQs
What happens on release day?
Ontology Version run begins on the last Thursday of the month. By the first Monday, all impacted datasets are reinstated.
What if an entity I use hasn’t changed?
The dataset may be reinstated, but your query results may not materially change unless the entity itself was altered.
Where can I find version change logs?
We’re building comparison tooling and will expose change summaries in the UI and API, in Ontology Explorer.
How are patch releases different?
They only add mapping tables for net-new datasets and don’t trigger full reinstatements unless core relationships are impacted.
Do reinstatements reset access?
No. However, reinstated datasets should be repurchased.
Contact us at support@carbonarc.co if you have any questions!