> For the complete documentation index, see [llms.txt](https://docs.cloud-halo.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cloud-halo.io/finops/focus-alignment.md). # FOCUS alignment Cloud Halo aligns its cost data model to the FinOps Open Cost and Usage Specification (FOCUS) so Azure cost data can move toward a portable, vendor-neutral FinOps contract. The current target is FOCUS 1.4, ratified on June 4, 2026. ## Current implementation Cloud Halo creates FOCUS-shaped Cost and Usage rows after each successful Azure cost sync. The first implementation is intentionally marked as `derived_from_summary` because the existing Azure ingestion path reads Cloud Halo's month-to-date summary data from Azure Cost Management, not invoice-grade provider line items. Cloud Halo can also import Azure Cost Management FOCUS CSV exports. Imported provider exports are marked as `provider_focus_export` and each upload is tracked in `focus_import_runs` with row counts, skipped rows, completeness status, and validation warnings. Current rows are stored in `focus_cost_usage_rows` and include: * FOCUS version and data generator metadata * Dataset completeness and data quality flags * Billing and charge period boundaries * Provider, subscription, service, resource, region, and tag dimensions * Billed, effective, contracted, and list cost fields * Source payload metadata for traceability back to the Cloud Halo sync snapshot The Cost and Usage CSV export now uses a FOCUS 1.4 Cost and Usage column inventory and returns a validation report per export. Validation fails when summary-derived rows are included because those rows are an internal FOCUS-aligned projection, not provider-sourced FOCUS billing rows. Azure reservation and savings-plan data is projected into `focus_contract_commitments`. This projection is marked as `derived_from_provider_commitment`. Cloud Halo can also import provider-native FOCUS Contract Commitment CSV exports into the same table as `provider_focus_export`. The commitments CSV uses the FOCUS 1.4 Contract Commitment column inventory and returns a validation report; derived rows fail conformance checks when provider-native commitment fields are unavailable or Cloud Halo fallback values are used, while complete provider-native rows can pass. Downloaded FOCUS datasets are recorded in `focus_dataset_exports` with a dataset instance id, source quality, row counts, validation status, and the linked report run. This helps customers understand whether exported CSVs were provider-sourced, mixed, or internally projected. ## What this enables This gives Cloud Halo a stable internal FOCUS vocabulary for: * Cost export work * Azure provider FOCUS export import and validation * Report builder datasets * Cross-provider readiness * Consistent naming across allocation, unit economics, budgets, and recommendations * Future validation against FOCUS tooling ## Current limitations The current rows are not a full FOCUS-conformant billing dataset yet. Known gaps: * Summary-sync costs are derived from resource aggregates, not raw invoice or usage detail rows. * Azure provider imports follow Microsoft's currently documented Azure FOCUS cost and usage export schema, which is versioned as `1.2-preview`. * Invoice detail and billing-period datasets are not populated yet. * Commitment data can be projected from `azure_commitments` or imported from provider-native FOCUS Contract Commitment CSVs. Derived commitment projections remain non-conformant until replaced by provider-native rows. * Billed, effective, contracted, and list cost are equal only for summary-derived rows. Provider-imported rows preserve the provider export values where present. * Billing account and invoice identifiers are only available where provider imports include them. * Cost and Usage validation is implemented in Cloud Halo, but exports still need to be run through the official FOCUS Validator before any external conformance claim. ## Adoption path 1. Use `focus_cost_usage_rows` as the canonical FOCUS-aligned projection for Cloud Halo cost exports. 2. Import Azure FOCUS cost and usage exports where customers have provider-generated FOCUS files available. 3. Record each downloaded FOCUS dataset with dataset-instance metadata, source quality, and validation status. 4. Populate invoice detail and billing-period datasets from provider billing exports. 5. Prefer provider-native FOCUS Contract Commitment imports over derived Azure commitment projections where customers can provide those files. 6. Run sample exports through the FOCUS validator before making any conformance claim. Use `pnpm focus:validate:cost-usage` for Cloud Halo's FOCUS 1.4 Cost and Usage inventory check, and use the in-app Contract Commitment validation report until the official validator path for this dataset is added. ## Validator workflow The hosted FOCUS Validator is useful for exploration and sample files, while the FOCUS project recommends running the open-source validator locally for production datasets and CI/CD. The hosted validator currently exposes v1.2 and v1.3 options, so Cloud Halo keeps a separate internal FOCUS 1.4 Cost and Usage inventory check until the official validator supports the same target version. Commands: ```bash pnpm focus:validate:cost-usage pnpm focus:validate:cost-usage:official node scripts/focus-cost-usage-validator.mjs --file path/to/focus-cost-usage.csv ``` See [FOCUS Cost and Usage conformance matrix](https://github.com/nate8523/cloud-halo/tree/main/docs/focus-cost-usage-conformance-matrix.md) for the current column inventory and validation policy. See [FOCUS Contract Commitment conformance matrix](https://github.com/nate8523/cloud-halo/tree/main/docs/focus-contract-commitment-conformance-matrix.md) for the current commitment inventory, inferred fields, and validation policy. See [FOCUS dataset governance](https://github.com/nate8523/cloud-halo/tree/main/docs/focus-dataset-governance.md) for export metadata and dataset instance tracking. Until validation is complete, use this language externally: > Cloud Halo is aligning its cost data model and exports with FOCUS 1.4. Do not describe Cloud Halo as fully FOCUS conformant until generated datasets have been validated against the applicable FOCUS requirements. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.cloud-halo.io/finops/focus-alignment.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.