focus-data-toolkit 0.11.0__py3-none-any.whl

focus_data_toolkit/model/focus_1_4_servicesubcategory.json

@@ -0,0 +1,84 @@
+{
+  "AI Platforms": "AI and Machine Learning",
+  "API Management": "Integration",
+  "Analytics Platforms": "Analytics",
+  "Application Networking": "Networking",
+  "Application Platforms": "Web",
+  "Architecture": "Management and Governance",
+  "Backup Storage": "Storage",
+  "Block Storage": "Storage",
+  "Bots": "AI and Machine Learning",
+  "Business Intelligence": "Analytics",
+  "Caching": "Databases",
+  "Compliance": "Management and Governance",
+  "Containers": "Compute",
+  "Content Creation": "Media",
+  "Content Delivery": "Networking",
+  "Continuous Integration and Deployment": "Developer Tools",
+  "Cost Management": "Management and Governance",
+  "Data Governance": "Management and Governance",
+  "Data Migration": "Migration",
+  "Data Processing": "Analytics",
+  "Data Warehouses": "Databases",
+  "Developer Platforms": "Developer Tools",
+  "Development Environments": "Developer Tools",
+  "Disaster Recovery": "Management and Governance",
+  "End User Computing": "Compute",
+  "Endpoint Management": "Management and Governance",
+  "File Storage": "Storage",
+  "Gaming": "Media",
+  "Generative AI": "AI and Machine Learning",
+  "Identity and Access Management": "Identity",
+  "IoT Analytics": "Internet of Things",
+  "IoT Platforms": "Internet of Things",
+  "Ledger Databases": "Databases",
+  "Machine Learning": "AI and Machine Learning",
+  "Media Streaming": "Media",
+  "Messaging": "Integration",
+  "Mixed Reality": "Media",
+  "Multicloud Integration": "Multicloud",
+  "Natural Language Processing": "AI and Machine Learning",
+  "Network Connectivity": "Networking",
+  "Network Infrastructure": "Networking",
+  "Network Routing": "Networking",
+  "Network Security": "Networking",
+  "NoSQL Databases": "Databases",
+  "Object Storage": "Storage",
+  "Observability": "Management and Governance",
+  "Other (AI and Machine Learning)": "AI and Machine Learning",
+  "Other (Analytics)": "Analytics",
+  "Other (Business Applications)": "Business Applications",
+  "Other (Compute)": "Compute",
+  "Other (Databases)": "Databases",
+  "Other (Developer Tools)": "Developer Tools",
+  "Other (Identity)": "Identity",
+  "Other (Integration)": "Integration",
+  "Other (Internet of Things)": "Internet of Things",
+  "Other (Management and Governance)": "Management and Governance",
+  "Other (Media)": "Media",
+  "Other (Migration)": "Migration",
+  "Other (Mobile)": "Mobile",
+  "Other (Multicloud)": "Multicloud",
+  "Other (Networking)": "Networking",
+  "Other (Other)": "Other",
+  "Other (Security)": "Security",
+  "Other (Storage)": "Storage",
+  "Other (Web)": "Web",
+  "Productivity and Collaboration": "Business Applications",
+  "Quality Assurance": "Developer Tools",
+  "Quantum Compute": "Compute",
+  "Relational Databases": "Databases",
+  "Resource Migration": "Migration",
+  "Search": "Analytics",
+  "Secret Management": "Security",
+  "Security Posture Management": "Security",
+  "Serverless Compute": "Compute",
+  "Source Code Management": "Developer Tools",
+  "Storage Platforms": "Storage",
+  "Streaming Analytics": "Analytics",
+  "Support": "Management and Governance",
+  "Threat Detection and Response": "Security",
+  "Time Series Databases": "Databases",
+  "Virtual Machines": "Compute",
+  "Workflow Orchestration": "Integration"
+}

focus_data_toolkit/model/focus_json_keys.py

@@ -0,0 +1,112 @@
+"""FOCUS-defined property keys for JSON / Key-Value typed columns.
+
+Sourced verbatim from the frozen FOCUS specification tags
+(``FinOps-Open-Cost-and-Usage-Spec/FOCUS_Spec`` at ``v1.3`` / ``v1.4``). These
+registries drive the ``x_`` custom-key rule: inside a FOCUS JSON column, any key
+that is **not** a FOCUS-defined property MUST be prefixed with ``x_`` (FOCUS
+attributes ``CustomColumnHandling`` / per-column ``KeyValueFormat`` /
+``JsonObjectFormat``).
+
+Important exceptions: ``Tags`` and ``AllocatedTags`` are Key-Value columns whose
+keys are arbitrary user tag names — the ``x_`` rule does **not** apply to them
+(FOCUS ``tags.md``: a single user-defined tag scheme carries no prefix). They are
+deliberately absent from :data:`XPREFIX_ENFORCED_COLUMNS`.
+"""
+
+from __future__ import annotations
+
+# --- Key-Value columns with a FOCUS-defined property set ------------------- #
+
+# SkuPriceDetails FOCUS-defined properties (identical in v1.3 and v1.4):
+# skupricedetails.md "FOCUS-Defined Properties" table — 13 keys.
+SKU_PRICE_DETAILS_KEYS: frozenset[str] = frozenset(
+    {
+        "CoreCount",
+        "DiskMaxIops",
+        "DiskSpace",
+        "DiskType",
+        "GpuCount",
+        "InstanceType",
+        "InstanceSeries",
+        "MemorySize",
+        "NetworkMaxIops",
+        "NetworkMaxThroughput",
+        "OperatingSystem",
+        "Redundancy",
+        "StorageClass",
+    }
+)
+
+# InvoiceDetailGrain FOCUS-defined properties (v1.4 invoicedetailgrain.md).
+# Each links to a Cost and Usage column; the JSON key is that column's Column ID.
+INVOICE_DETAIL_GRAIN_KEYS: frozenset[str] = frozenset(
+    {
+        "ContractId",
+        "RegionId",
+        "ResourceId",
+        "ResourceType",
+        "ServiceName",
+        "SkuId",
+        "SkuMeter",
+        "SkuPriceId",
+        "SubAccountId",
+    }
+)
+
+# --- JSON-Object columns with a top-level ``Elements`` array --------------- #
+
+# ContractApplied element keys. The identifier keys changed casing between
+# versions (contractapplied.md @ v1.3 vs v1.4); the three metric keys are stable.
+CONTRACT_APPLIED_ELEMENT_KEYS_1_3: frozenset[str] = frozenset(
+    {
+        "ContractID",
+        "ContractCommitmentID",
+        "ContractCommitmentAppliedCost",
+        "ContractCommitmentAppliedQuantity",
+        "ContractCommitmentAppliedUnit",
+    }
+)
+CONTRACT_APPLIED_ELEMENT_KEYS_1_4: frozenset[str] = frozenset(
+    {
+        "ContractId",
+        "ContractCommitmentId",
+        "ContractCommitmentAppliedCost",
+        "ContractCommitmentAppliedQuantity",
+        "ContractCommitmentAppliedUnit",
+    }
+)
+
+# AllocatedMethodDetails element keys (allocatedmethoddetails.md, v1.3 & v1.4).
+ALLOCATED_METHOD_DETAILS_ELEMENT_KEYS: frozenset[str] = frozenset(
+    {
+        "AllocatedRatio",
+        "UsageUnit",
+        "UsageQuantity",
+    }
+)
+
+# CommitmentProgramEligibilityDetails element keys
+# (commitmentprogrameligibilitydetails.md @ v1.4; top-level array key is
+# ``CommitmentPrograms``, not ``Elements``).
+COMMITMENT_PROGRAM_ELIGIBILITY_ELEMENT_KEYS: frozenset[str] = frozenset({"ProgramType"})
+
+# Columns whose custom keys MUST be ``x_``-prefixed, mapped to their FOCUS-defined
+# key set. Key-Value columns match keys at the top level. Array-of-objects columns
+# map to ``(top_level_array_key, element_focus_keys)``: top-level keys must be the
+# array key or ``x_``-prefixed, and element keys must be FOCUS-defined or
+# ``x_``-prefixed (custom properties are allowed at both levels per the v1.4 column
+# docs). ``ContractApplied`` is validated in depth by
+# ``focus_data_toolkit.convert.contract_applied.parse`` and is therefore absent
+# here. Tags / AllocatedTags are intentionally excluded (arbitrary tag keys are
+# allowed).
+XPREFIX_ENFORCED_KEYVALUE_COLUMNS: dict[str, frozenset[str]] = {
+    "SkuPriceDetails": SKU_PRICE_DETAILS_KEYS,
+    "InvoiceDetailGrain": INVOICE_DETAIL_GRAIN_KEYS,
+}
+XPREFIX_ENFORCED_ELEMENTS_COLUMNS: dict[str, tuple[str, frozenset[str]]] = {
+    "AllocatedMethodDetails": ("Elements", ALLOCATED_METHOD_DETAILS_ELEMENT_KEYS),
+    "CommitmentProgramEligibilityDetails": (
+        "CommitmentPrograms",
+        COMMITMENT_PROGRAM_ELIGIBILITY_ELEMENT_KEYS,
+    ),
+}

focus_data_toolkit/model/iso_4217_currencies.json

@@ -0,0 +1,23 @@
+{
+  "_source": "ISO 4217 active alphabetic currency codes (incl. fund/precious-metal/test codes X*).",
+  "codes": [
+    "AED", "AFN", "ALL", "AMD", "ANG", "AOA", "ARS", "AUD", "AWG", "AZN",
+    "BAM", "BBD", "BDT", "BGN", "BHD", "BIF", "BMD", "BND", "BOB", "BOV",
+    "BRL", "BSD", "BTN", "BWP", "BYN", "BZD", "CAD", "CDF", "CHE", "CHF",
+    "CHW", "CLF", "CLP", "CNY", "COP", "COU", "CRC", "CUP", "CVE", "CZK",
+    "DJF", "DKK", "DOP", "DZD", "EGP", "ERN", "ETB", "EUR", "FJD", "FKP",
+    "GBP", "GEL", "GHS", "GIP", "GMD", "GNF", "GTQ", "GYD", "HKD", "HNL",
+    "HTG", "HUF", "IDR", "ILS", "INR", "IQD", "IRR", "ISK", "JMD", "JOD",
+    "JPY", "KES", "KGS", "KHR", "KMF", "KPW", "KRW", "KWD", "KYD", "KZT",
+    "LAK", "LBP", "LKR", "LRD", "LSL", "LYD", "MAD", "MDL", "MGA", "MKD",
+    "MMK", "MNT", "MOP", "MRU", "MUR", "MVR", "MWK", "MXN", "MXV", "MYR",
+    "MZN", "NAD", "NGN", "NIO", "NOK", "NPR", "NZD", "OMR", "PAB", "PEN",
+    "PGK", "PHP", "PKR", "PLN", "PYG", "QAR", "RON", "RSD", "RUB", "RWF",
+    "SAR", "SBD", "SCR", "SDG", "SEK", "SGD", "SHP", "SLE", "SOS", "SRD",
+    "SSP", "STN", "SVC", "SYP", "SZL", "THB", "TJS", "TMT", "TND", "TOP",
+    "TRY", "TTD", "TWD", "TZS", "UAH", "UGX", "USD", "USN", "UYI", "UYU",
+    "UYW", "UZS", "VED", "VES", "VND", "VUV", "WST", "XAF", "XAG", "XAU",
+    "XBA", "XBB", "XBC", "XBD", "XCD", "XCG", "XDR", "XOF", "XPD", "XPF",
+    "XPT", "XSU", "XTS", "XUA", "XXX", "YER", "ZAR", "ZMW", "ZWG"
+  ]
+}

focus_data_toolkit/model/json_schema_check.py

@@ -0,0 +1,205 @@
+"""Validate FOCUS JSON-object column values against the vendored official schemas.
+
+The FOCUS specification publishes normative JSON Schemas (draft 2020-12) for its
+JSON-object columns under ``specification/schemas/datasets/``. Those files are
+vendored verbatim in ``model/json_schemas/`` (see ``json_schemas_provenance.json``)
+and evaluated here with a small interpreter covering exactly the keyword subset the
+official schemas use — no runtime dependency, and the vendored files (not hand-coded
+rules) remain the single source of truth.
+
+Supported keywords: ``$ref`` (``#/$defs/...``), ``type`` (incl. type lists),
+``properties``, ``patternProperties``, ``additionalProperties`` (boolean),
+``required``, ``items``, ``minItems`` / ``maxItems``, ``contains``, ``enum``,
+``const``, ``minimum`` / ``maximum``, ``allOf`` / ``anyOf`` / ``oneOf`` / ``not``,
+``if`` / ``then``, and boolean schemas. An unsupported keyword raises — a vendored
+schema update that outgrows the subset must fail loudly, never silently pass.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import re
+from functools import cache
+from pathlib import Path
+
+SCHEMA_DIR = Path(__file__).resolve().parent / "json_schemas"
+PROVENANCE_PATH = SCHEMA_DIR / "json_schemas_provenance.json"
+
+# FOCUS column -> vendored official schema file.
+OFFICIAL_SCHEMA_COLUMNS: dict[str, str] = {
+    "ContractApplied": "contractappliedobjectschema.json",
+    "AllocatedMethodDetails": "allocatedmethoddetailsobjectschema.json",
+    "CommitmentProgramEligibilityDetails": "commitmentprogrameligibilitydetailsobjectschema.json",
+    "ContractCommitmentApplicability": "contractcommitmentapplicabilityobjectschema.json",
+}
+
+# Keywords the interpreter evaluates, plus annotations it may safely ignore.
+_HANDLED = frozenset({
+    "$ref", "type", "properties", "patternProperties", "additionalProperties",
+    "required", "items", "minItems", "maxItems", "contains", "enum", "const",
+    "minimum", "maximum", "allOf", "anyOf", "oneOf", "not", "if", "then",
+})
+_ANNOTATIONS = frozenset({"$schema", "$id", "$defs", "title", "description", "default"})
+
+def _is_number(v: object) -> bool:
+    # Standard JSON has no NaN/Infinity; Python's parser may still produce them from
+    # the non-standard constants, so a non-finite float is never a schema "number".
+    if isinstance(v, bool) or not isinstance(v, int | float):
+        return False
+    return math.isfinite(v)
+
+
+_TYPE_CHECKS = {
+    "object": lambda v: isinstance(v, dict),
+    "array": lambda v: isinstance(v, list),
+    "string": lambda v: isinstance(v, str),
+    "number": _is_number,
+    "integer": lambda v: _is_number(v) and (isinstance(v, int) or v.is_integer()),
+    "boolean": lambda v: isinstance(v, bool),
+    "null": lambda v: v is None,
+}
+
+
+class UnsupportedSchemaKeyword(ValueError):
+    """A vendored schema uses a keyword outside the interpreter's subset."""
+
+
+@cache
+def load_official_schema(filename: str) -> dict:
+    schema = json.loads((SCHEMA_DIR / filename).read_text(encoding="utf-8"))
+    _assert_supported(schema)
+    return schema
+
+
+def _assert_supported(schema: object) -> None:
+    if isinstance(schema, bool):
+        return
+    if isinstance(schema, dict):
+        for key, sub in schema.items():
+            if key in _ANNOTATIONS:
+                continue
+            if key not in _HANDLED:
+                raise UnsupportedSchemaKeyword(f"unsupported JSON Schema keyword {key!r}")
+            if key in ("properties", "patternProperties"):
+                for nested in sub.values():
+                    _assert_supported(nested)
+            elif key in ("allOf", "anyOf", "oneOf"):
+                for nested in sub:
+                    _assert_supported(nested)
+            elif key in ("items", "contains", "not", "if", "then", "additionalProperties"):
+                _assert_supported(sub)
+        for nested in schema.get("$defs", {}).values():
+            _assert_supported(nested)
+
+
+def check_against_official_schema(column: str, obj: object) -> list[str]:
+    """Return the official-schema violations for ``obj`` (empty list = conformant)."""
+    schema = load_official_schema(OFFICIAL_SCHEMA_COLUMNS[column])
+    return _validate(obj, schema, schema, "$")
+
+
+def _resolve_ref(root: dict, ref: str) -> dict:
+    if not ref.startswith("#/"):  # the official schemas only use local refs
+        raise UnsupportedSchemaKeyword(f"unsupported $ref target {ref!r}")
+    node: object = root
+    for part in ref[2:].split("/"):
+        node = node[part]  # type: ignore[index]
+    return node  # type: ignore[return-value]
+
+
+def _type_ok(value: object, spec: str | list[str]) -> bool:
+    names = [spec] if isinstance(spec, str) else spec
+    return any(_TYPE_CHECKS[n](value) for n in names)
+
+
+def _json_equal(a: object, b: object) -> bool:
+    # JSON equality: booleans are not numbers (Python's bool == int would conflate them).
+    if isinstance(a, bool) is not isinstance(b, bool):
+        return False
+    return a == b
+
+
+def _validate(value: object, schema: object, root: dict, path: str) -> list[str]:
+    if schema is True:
+        return []
+    if schema is False:
+        return [f"{path}: not permitted here"]
+    assert isinstance(schema, dict)
+
+    if "$ref" in schema:
+        ref_errors = _validate(value, _resolve_ref(root, schema["$ref"]), root, path)
+        if ref_errors:
+            return ref_errors
+
+    spec_type = schema.get("type")
+    if spec_type is not None and not _type_ok(value, spec_type):
+        return [f"{path}: expected type {spec_type}"]
+
+    errors: list[str] = []
+    if "enum" in schema and not any(_json_equal(value, v) for v in schema["enum"]):
+        errors.append(f"{path}: value not in {schema['enum']}")
+    if "const" in schema and not _json_equal(value, schema["const"]):
+        errors.append(f"{path}: expected constant {schema['const']!r}")
+
+    for sub in schema.get("allOf", ()):
+        errors.extend(_validate(value, sub, root, path))
+    if "anyOf" in schema and all(_validate(value, sub, root, path) for sub in schema["anyOf"]):
+        errors.append(f"{path}: matches none of the allowed forms (anyOf)")
+    if "oneOf" in schema:
+        matched = sum(1 for sub in schema["oneOf"] if not _validate(value, sub, root, path))
+        if matched != 1:
+            errors.append(f"{path}: must match exactly one allowed form (matched {matched})")
+    if "not" in schema and not _validate(value, schema["not"], root, path):
+        errors.append(f"{path}: matches a prohibited form")
+    if "if" in schema and not _validate(value, schema["if"], root, path):
+        errors.extend(_validate(value, schema.get("then", True), root, path))
+
+    if isinstance(value, dict):
+        errors.extend(_validate_object(value, schema, root, path))
+    elif isinstance(value, list):
+        errors.extend(_validate_array(value, schema, root, path))
+    elif isinstance(value, int | float) and not isinstance(value, bool):
+        if "minimum" in schema and value < schema["minimum"]:
+            errors.append(f"{path}: {value} is below minimum {schema['minimum']}")
+        if "maximum" in schema and value > schema["maximum"]:
+            errors.append(f"{path}: {value} is above maximum {schema['maximum']}")
+    return errors
+
+
+def _validate_object(value: dict, schema: dict, root: dict, path: str) -> list[str]:
+    errors: list[str] = []
+    for req in schema.get("required", ()):
+        if req not in value:
+            errors.append(f"{path}: required property {req!r} is missing")
+    properties = schema.get("properties", {})
+    patterns = {re.compile(p): s for p, s in schema.get("patternProperties", {}).items()}
+    additional = schema.get("additionalProperties", True)
+    for key, item in value.items():
+        matched = False
+        if key in properties:
+            matched = True
+            errors.extend(_validate(item, properties[key], root, f"{path}.{key}"))
+        for pattern, sub in patterns.items():
+            if pattern.search(key):
+                matched = True
+                errors.extend(_validate(item, sub, root, f"{path}.{key}"))
+        if not matched:
+            errors.extend(_validate(item, additional, root, f"{path}.{key}"))
+    return errors
+
+
+def _validate_array(value: list, schema: dict, root: dict, path: str) -> list[str]:
+    errors: list[str] = []
+    if "minItems" in schema and len(value) < schema["minItems"]:
+        errors.append(f"{path}: needs at least {schema['minItems']} item(s)")
+    if "maxItems" in schema and len(value) > schema["maxItems"]:
+        errors.append(f"{path}: allows at most {schema['maxItems']} item(s)")
+    if "items" in schema:
+        for i, item in enumerate(value):
+            errors.extend(_validate(item, schema["items"], root, f"{path}[{i}]"))
+    if "contains" in schema and all(
+        _validate(item, schema["contains"], root, path) for item in value
+    ):
+        errors.append(f"{path}: no item matches the required form (contains)")
+    return errors

focus_data_toolkit/model/json_schemas/allocatedmethoddetailsobjectschema.json

@@ -0,0 +1,82 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://focus.finops.org/schemas/allocatedmethoddetailsobject.json",
+    "title": "Allocated Method Details Object",
+    "description": "Schema for validating the Allocated Method Details column JSON object structure in FOCUS datasets",
+    "type": "object",
+    "required": [
+        "Elements"
+    ],
+    "properties": {
+        "Elements": {
+            "type": "array",
+            "description": "Array containing one or more objects describing allocation properties",
+            "minItems": 1,
+            "items": {
+                "type": "object",
+                "required": [
+                    "AllocatedRatio"
+                ],
+                "properties": {
+                    "AllocatedRatio": {
+                        "type": "number",
+                        "description": "Percentage of overall cost derived from corresponding method and metric",
+                        "minimum": 0,
+                        "maximum": 1
+                    },
+                    "UsageUnit": {
+                        "type": [
+                            "string",
+                            "null"
+                        ],
+                        "description": "Unit being measured used to calculate allocation"
+                    },
+                    "UsageQuantity": {
+                        "type": [
+                            "number",
+                            "null"
+                        ],
+                        "description": "Volume of UsageUnit consumed or used"
+                    }
+                },
+                "anyOf": [
+                    {
+                        "description": "Scenario 1: UsageQuantity is absent or explicitly null. UsageUnit can be anything (or absent).",
+                        "properties": {
+                            "UsageQuantity": {
+                                "type": "null"
+                            }
+                        }
+                    },
+                    {
+                        "description": "Scenario 2: UsageQuantity is provided and is a number. UsageUnit MUST be provided and MUST be a string.",
+                        "required": [
+                            "UsageQuantity",
+                            "UsageUnit"
+                        ],
+                        "properties": {
+                            "UsageQuantity": {
+                                "type": "number"
+                            },
+                            "UsageUnit": {
+                                "type": "string"
+                            }
+                        }
+                    }
+                ],
+                "patternProperties": {
+                    "^x_[A-Z][a-zA-Z0-9]*$": {
+                        "description": "Custom data generator-defined properties prefixed with x_ in PascalCase format"
+                    }
+                },
+                "additionalProperties": false
+            }
+        }
+    },
+    "patternProperties": {
+        "^x_[A-Z][a-zA-Z0-9]*$": {
+            "description": "Custom data generator-defined top-level properties prefixed with x_ in PascalCase format"
+        }
+    },
+    "additionalProperties": false
+}

focus_data_toolkit/model/json_schemas/commitmentprogrameligibilitydetailsobjectschema.json

@@ -0,0 +1,41 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://focus.finops.org/schemas/commitmentprogrameligibilitydetailsobject.json",
+    "title": "Commitment Program Eligibility Details Object",
+    "description": "Schema for validating the Commitment Program Eligibility Details column JSON object structure in FOCUS datasets",
+    "type": "object",
+    "required": [
+        "CommitmentPrograms"
+    ],
+    "properties": {
+        "CommitmentPrograms": {
+            "type": "array",
+            "description": "Array of objects identifying commitment programs for which the usage is eligible.",
+            "minItems": 1,
+            "items": {
+                "type": "object",
+                "required": [
+                    "ProgramType"
+                ],
+                "properties": {
+                    "ProgramType": {
+                        "type": "string",
+                        "description": "The specific type of commitment program (e.g., discount or capacity reservation) available for this usage."
+                    }
+                },
+                "patternProperties": {
+                    "^x_[A-Z][a-zA-Z0-9]*$": {
+                        "description": "Custom data generator-defined properties prefixed with x_ in PascalCase format"
+                    }
+                },
+                "additionalProperties": false
+            }
+        }
+    },
+    "patternProperties": {
+        "^x_[A-Z][a-zA-Z0-9]*$": {
+            "description": "Custom data generator-defined top-level properties prefixed with x_ in PascalCase format"
+        }
+    },
+    "additionalProperties": false
+}

focus_data_toolkit/model/json_schemas/contractappliedobjectschema.json

@@ -0,0 +1,104 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://focus.finops.org/schemas/contractappliedobject.json",
+    "title": "Contract Applied Object",
+    "description": "Schema for validating the Contract Applied column JSON object structure in FOCUS datasets",
+    "type": "object",
+    "required": [
+        "Elements"
+    ],
+    "properties": {
+        "Elements": {
+            "type": "array",
+            "description": "Array containing one or more objects describing contract commitments applied to the charge",
+            "minItems": 1,
+            "items": {
+                "type": "object",
+                "required": [
+                    "ContractId",
+                    "ContractCommitmentId"
+                ],
+                "properties": {
+                    "ContractId": {
+                        "type": "string",
+                        "description": "Unique identifier for the contract"
+                    },
+                    "ContractCommitmentId": {
+                        "type": "string",
+                        "description": "Unique identifier for the contract commitment term"
+                    },
+                    "ContractCommitmentAppliedCost": {
+                        "type": [
+                            "number",
+                            "null"
+                        ],
+                        "description": "Cost value of the charge applied to the contract commitment"
+                    },
+                    "ContractCommitmentAppliedQuantity": {
+                        "type": [
+                            "number",
+                            "null"
+                        ],
+                        "description": "Quantity of usage applied to the contract commitment"
+                    },
+                    "ContractCommitmentAppliedUnit": {
+                        "type": [
+                            "string",
+                            "null"
+                        ],
+                        "description": "Unit of measure for the applied quantity"
+                    }
+                },
+                "oneOf": [
+                    {
+                        "description": "Scenario 1: Cost has a value. Quantity and Unit MUST be absent or explicitly null.",
+                        "required": [
+                            "ContractCommitmentAppliedCost"
+                        ],
+                        "properties": {
+                            "ContractCommitmentAppliedCost": {
+                                "type": "number"
+                            },
+                            "ContractCommitmentAppliedQuantity": {
+                                "type": "null"
+                            },
+                            "ContractCommitmentAppliedUnit": {
+                                "type": "null"
+                            }
+                        }
+                    },
+                    {
+                        "description": "Scenario 2: Quantity and Unit have values. Cost MUST be absent or explicitly null.",
+                        "required": [
+                            "ContractCommitmentAppliedQuantity",
+                            "ContractCommitmentAppliedUnit"
+                        ],
+                        "properties": {
+                            "ContractCommitmentAppliedCost": {
+                                "type": "null"
+                            },
+                            "ContractCommitmentAppliedQuantity": {
+                                "type": "number"
+                            },
+                            "ContractCommitmentAppliedUnit": {
+                                "type": "string"
+                            }
+                        }
+                    }
+                ],
+                "patternProperties": {
+                    "^x_[A-Z][a-zA-Z0-9]*$": {
+                        "description": "Custom data generator-defined properties prefixed with x_ in PascalCase format"
+                    }
+                },
+                "additionalProperties": false
+            }
+        }
+    },
+    "patternProperties": {
+        "^x_[A-Z][a-zA-Z0-9]*$": {
+            "description": "Custom data generator-defined top-level properties prefixed with x_ in PascalCase format"
+        }
+    },
+    "additionalProperties": false
+}