diff --git a/docs-mslearn/toolkit/hubs/data-model.md b/docs-mslearn/toolkit/hubs/data-model.md index e06a19519..7ad45c674 100644 --- a/docs-mslearn/toolkit/hubs/data-model.md +++ b/docs-mslearn/toolkit/hubs/data-model.md @@ -3,7 +3,7 @@ title: FinOps hubs data model description: Learn about the tables and functions available in FinOps hubs to build your own queries, reports, and dashboards. author: flanakin ms.author: micflan -ms.date: 04/01/2026 +ms.date: 05/07/2026 ms.topic: reference ms.service: finops ms.subservice: finops-toolkit @@ -54,6 +54,8 @@ Note the use of "Data Explorer" covers both Azure Data Explorer and Microsoft Fa One of the goals of the FinOps hubs data model is to guarantee backwards compatibility. To support this, each FinOps hub release uses a specific schema version which aligns to a specific FOCUS version. The **schema version** defines the columns, data types, and allowed values in the tables and functions for each [managed dataset](#managed-datasets-in-finops-hubs). +The hub schema version mirrors the FOCUS specification version it natively ingests. For example, `v1_2` ingests FOCUS 1.2 exports without transformation. Older data ingested under prior schema versions is automatically up-converted by the unversioned functions (`Costs()`, `Prices()`, etc.) so consumers always see the latest schema regardless of when the data was ingested. + The following table indicates the schema version for each FinOps hub release and which FOCUS version they align to. | Release | Schema | FOCUS version | @@ -61,6 +63,10 @@ The following table indicates the schema version for each FinOps hub release and | 12+ | `v1_2` | 1.2 | | 0.7-11 | `v1_0` | 1.0 | +When hub support ships ahead of FOCUS specification ratification, the hub schema is labeled **preview**. Preview schemas may change without notice between releases because the underlying spec is still working draft. The unversioned functions remain pinned to the latest GA schema until the preview promotes to GA, ensuring production reports stay stable while early adopters validate the new version. + +Cost Management export availability for a given FOCUS version is a separate concern. A hub schema can be GA even if Cost Management has not yet shipped a matching export; in that case, the hub is ready to ingest the new format as soon as the export ships. This is documented in the [hub upgrade procedure](https://github.com/microsoft/finops-toolkit/tree/dev/src/templates/finops-hub/docs/README.md) so adopters know which scenarios require additional setup once an export is available. +
## Managed datasets in FinOps hubs diff --git a/src/templates/finops-hub/docs/README.md b/src/templates/finops-hub/docs/README.md index 2cff88bf9..a084adff2 100644 --- a/src/templates/finops-hub/docs/README.md +++ b/src/templates/finops-hub/docs/README.md @@ -17,8 +17,11 @@ - Each versioned function unions data from versioned tables in the Ingestion database and transforms it to that FOCUS version for back compat. - Consumers should use the unversioned function for the latest and the versioned functions for back compat. -To add a new FOCUS versions: +To add a new FOCUS version: +0. Confirm dependencies + 1. Mark the hub schema as **preview** if the FOCUS specification is still working draft (not yet ratified). Preview schemas may change without notice between releases. + 2. Check whether Microsoft Cost Management has shipped a matching FOCUS export dataset version. The hub depends on a `focuscost_X.Y.json` schema mapping file in [Microsoft.CostManagement/Exports/schemas](../modules/Microsoft.CostManagement/Exports/schemas/) when ingesting from Cost Management. If the export is not yet available, the hub schema can still ship as GA — the hub will ingest the new format as soon as the export ships. Note the gap in the changelog so adopters know what additional setup will be required. 1. Add schema mapping file 1. Create new schema mapping file for the Cost Management export dataset version in the schemas folder 2. Add file to file upload list in [storage.bicep](../modules/storage.bicep) @@ -41,3 +44,26 @@ To add a new FOCUS versions: 2. Update the KQL reports to use the new versioned functions 3. Update the ADX dashboard to use the new versioned functions 4. Update the FOCUS queries in the best practices library to use the new versioned functions +5. Update open-data metadata + 1. Drop a new `FocusCost_.json` file into [src/open-data/dataset-metadata](../../../open-data/dataset-metadata/). + 2. Mirror the schema details (columns, types, descriptions) from the matching Cost Management export schema so downstream consumers see consistent metadata. +6. Update plugin skill files + 1. Refresh the FOCUS schema and function references in the following files so plugin guidance does not go stale: + - [src/templates/agent-skills/finops-toolkit/references/finops-hubs.md](../../agent-skills/finops-toolkit/references/finops-hubs.md) + - [src/templates/agent-skills/finops-toolkit/references/finops-hubs-deployment.md](../../agent-skills/finops-toolkit/references/finops-hubs-deployment.md) + - [src/templates/agent-skills/azure-cost-management/references/azure-cost-exports.md](../../agent-skills/azure-cost-management/references/azure-cost-exports.md) + - [src/templates/claude-plugin/agents/ftk-database-query.md](../../claude-plugin/agents/ftk-database-query.md) + - [src/templates/claude-plugin/output-styles/ftk-output-style.md](../../claude-plugin/output-styles/ftk-output-style.md) +7. Update changelog + 1. Add an entry under the next version in [docs-mslearn/toolkit/changelog.md](../../../../docs-mslearn/toolkit/changelog.md) describing the new FOCUS version support and any preview status. + +### Handling multiple FOCUS versions in one cycle + +Occasionally, the toolkit needs to support two FOCUS versions in a single release – for example, a newly ratified version alongside a working draft of the next version. When that happens: + +- The older version follows the standard `_v1_X` naming and ships as generally available (GA). +- The newer version uses the next `_v1_Y` suffix and is labeled **preview** in user-facing documentation, including [data-model.md](../../../../docs-mslearn/toolkit/hubs/data-model.md) and [changelog.md](../../../../docs-mslearn/toolkit/changelog.md). +- Preview schemas may change without notice between releases. Treat them as opt-in for early adopters only. +- The unversioned functions (`Costs()`, `Prices()`, etc.) alias to the latest **GA** schema, not the preview. The aliases promote to the newer version only after it transitions from preview to GA. + +This guarantees backwards compatibility for production consumers while still enabling early validation of the next FOCUS version.