Usage Assumptions Schema

Some AWS services bill by workload, not by declared capacity. A bucket, queue, topic, log group, file system, function, API, stream, or network resource can appear in a diff while the diff says nothing about storage, request volume, message volume, queries, or data transfer. CloudBurn prices that usage from monthly assumptions that live in your repository, and every assumed cost in the report is labeled as an assumption, never presented as a fact.

This page is the schema reference for that file: .cloudburn/usage-assumptions.json at the root of your repository. For worked configurations and guidance on where each number comes from, read Usage assumption examples.

One rule runs through every section below: CloudBurn never infers a quantity it was not given. It will not derive request volume from a bucket's existence, a transfer direction from an undirected byte total, or a write volume from a read volume. A missing input produces an unknown component that names what it needs — not a guess, and not a zero. The per-service sections call out where this bites hardest.

How the file reaches CloudBurn

The CloudBurn GitHub App never reads repository files. The aws-cdk-diff-pr-commenter and terraform-plan-pr-commenter actions read the current .cloudburn/usage-assumptions.json from the GitHub Actions workspace. Check out the pull request head before running the action so those numbers describe the proposed state. When the current file exists, the action also retrieves its previous version at the pull request base commit and embeds both snapshots next to the Resource Change Set.

CloudBurn prices the current snapshot as the proposed state and the previous snapshot as the base state, so a pull request that only edits assumptions can show its cost delta. Keep these rules in mind:

• Each snapshot can contain at most 65,536 UTF-8 bytes. An oversized file, invalid JSON, or a failure to retrieve the previous snapshot produces an explicit assumptions error in the comment rather than silently dropping your numbers.
• The actions check file size and JSON syntax. CloudBurn validates the schema, including duplicate JSON keys and unknown fields; invalid assumptions make the estimate incomplete.
• If the file is absent from the current workspace, the actions skip both snapshots. This also happens when a pull request deletes the file, even if the base commit still has it. Repositories without the file remain opt-in and get no assumed components.

Top-level fields

{
  "schemaVersion": 2,
  "revision": "2026-08-01",
  "freeTier": "disabled",
  "accountContext": {},
  "organizationDefaults": {},
  "repositoryDefaults": {},
  "resourceTypeDefaults": {},
  "resources": {}
}

Schema v1 and the legacy cloudburn-usage-assumptions comment fence still parse, but graduated account tiers and free-tier deductions need schema v2 accountContext.

Supported resource types

Usage assumptions apply to these resource types. Everything else in the diff keeps its existing fixed-price treatment.

Resolution precedence

A value resolves from the narrowest layer that supplies it. The layers below are listed in application order from broadest to narrowest — when several define the same field, the last (narrowest) matching layer wins:

1. organizationDefaults — broadest
2. repositoryDefaults
3. resourceTypeDefaults["AWS::S3::Bucket"]
4. resources["<address>"] — narrowest, always wins

Keys under resources are stable IaC addresses: the CDK construct path such as StorageStack/ReportsBucket, or the Terraform address such as module.storage.aws_s3_bucket.reports. Wildcard selectors are rejected. A bare CDK construct name without its stack works only while it matches exactly one changed resource; an ambiguous selector fails the whole block. The report attributes every assumed component to the scope and field that supplied its quantity.

Quantities and units

Usage totals are monthly. A bare number or an object with only value uses the measure's canonical unit; adding unit converts to that unit:

{ "value": 2, "unit": "TB" }

Quantity objects also accept period: "month". Unknown units, negative or non-finite values, and any other period are rejected. TB and TB-Mo convert to 1,024 GB and GB-Mo respectively.

duration is the one non-monthly measure: lambda.averageDurationMs is an average per invocation, and CloudBurn derives the monthly compute quantity from it. computeGbSeconds appears only in accountContext, never as an assumption field.

Account usage and graduated tiers

AWS applies graduated pricing tiers across an account, not per resource. Put the billable usage that already occupies each tier under accountContext.usage, and CloudBurn starts the changed resources after that quantity, advancing one shared pool per account as it prices each resource.

A component whose AWS price has more than one tier stays unknown until its account pool is present. CloudBurn does not guess where your account already sits in the tier. Setting a pool to 0 is a valid answer and the right one for a fresh account, and a pool that turns out not to be needed changes nothing — so when in doubt, supply it. Single-rate dimensions such as SNS deliveries to SQS or Lambda need no pool at all.

Only the keys in the table below are accepted. A key that is not listed fails the whole assumptions block as an unsupported account-context field.

For example, 100 GB of new Standard storage after 51,150 GB of existing usage spans 50 GB in the first tier and 50 GB in the second.

AWS publishes a separate graduated duration schedule per Lambda architecture, so lambda.duration.x86 and lambda.duration.arm advance independently.

Free tier

CloudBurn doesn't guess whether your account still has free allowance. Set "freeTier": "enabled" at the file, layer, or resource scope, then provide the remaining allowance under accountContext.remainingFreeTier:

{
  "schemaVersion": 2,
  "freeTier": "enabled",
  "accountContext": {
    "usage": { "s3.storage.standard": 0 },
    "remainingFreeTier": { "s3.storage.standard": 5 }
  }
}

Each allowance is consumed once across all changed resources in a stable order, so a report can never multiply the same free tier across resources. If free tier is enabled but an eligible pool's remaining allowance is missing, that component stays unknown. AWS catalog tiers that happen to start at zero are not treated as permission to claim a free tier — CloudBurn removes those embedded tiers and applies only the allowance you configure.

Put the allowance you have left this month in remainingFreeTier, not the full figure above, unless the month is genuinely untouched.

Two ordering rules keep totals stable no matter how resources appear in the diff. SQS Standard requests claim the shared SQS allowance before FIFO requests, so the pricier FIFO rate stays billable. Lambda's compute allowance is one account-level pool (lambda.duration) shared by both architectures, and arm64 functions claim it before x86 for the same reason.

S3 fields

Set these under an s3 group at any layer. A missing field affects only its own cost component.

CloudBurn never infers usage from existence: it does not guess request volume from object counts, stored bytes from a bucket's presence, or a transfer direction from replication. Two fields stay intentionally ambiguous and report as unknown: s3.dataTransfer.gb (no direction) and the legacy s3.requests.lifecycleTransition (AWS prices each transition destination differently).

CDK bucket properties and Terraform's separate lifecycle, replication, Intelligent-Tiering, and acceleration resources feed the same bucket model. Transfer acceleration, complex replication, S3 Express One Zone, Multi-Region Access Points, Tables, and Vectors stay unknown.

SQS fields

CloudBurn picks the Standard or FIFO price from the queue's declared FifoQueue property. Supply already-normalized AWS billable request units: account for batching, then round each payload up in 64 KB chunks. One API action with a 256 KB payload contributes four request units.

All queues share one sqs.requests account pool and free-tier pool. A missing request assumption stays unknown instead of being inferred from the queue's existence. CloudBurn records the Standard default for a no-options constructor or a fully visible literal without FIFO settings; indirect, spread, or incomplete options stay unknown rather than assuming Standard.

SNS fields

These fields also take normalized billable units: apply publish batching first, then round Standard publish and non-SMS delivery payloads up in 64 KB chunks. CloudBurn selects Standard or FIFO pricing from the topic's declared FifoTopic property.

Standard HTTP/S, SQS, and Lambda delivery pricing excludes data transfer, which remains unknown in the report.

FIFO topics support SQS delivery pricing only. FIFO payload-volume charges and data transfer stay explicitly unknown until payload-size assumptions are supported, so never fold raw bytes into sns.publishedMessages. HTTP, email, Lambda, mobile push, and SMS delivery assumptions on a FIFO topic are reported as unsupported unknowns rather than matched to Standard prices.

CloudWatch Logs fields

Set these under a logs group. The declared log group class (LogGroupClass, log_group_class, or the CDK logGroupClass prop) selects the Standard or Infrequent Access ingestion dimension; an omitted class keeps the CloudFormation Standard default. Storage bills under one dimension for both classes.

Stored volume is always assumed, never derived from retention — the declared retention is surfaced alongside the storage component so a reviewer can sanity-check the number. The 5 GB ingestion free tier applies only to Standard-class ingestion, once per report, through the logs.ingestion.standard pool. The Delivery log class, vended-log delivery, Logs Insights queries, Live Tail, metric filters, subscription delivery, and Intelligent Tiering access tiers stay unknown.

EFS fields

Set these under an efs group. A declared availability zone (AvailabilityZoneName, availability_zone_name, or the CDK oneZone flag) selects the One Zone storage dimensions; One Zone and Regional file systems never share a dimension. Archive is Regional-only, so Archive assumptions on a One Zone file system are reported as unsupported unknowns.

The declared throughput mode is a second discriminator. AWS bills Regional Infrequent Access storage under a separate, cheaper dimension on file systems using elastic throughput, so a declared ThroughputMode: elastic selects it; an omitted mode keeps the bursting default that CloudFormation, CDK, and Terraform all document. One Zone Infrequent Access has no elastic variant and is unaffected.

Per-class IA and Archive access charges apply in every throughput mode. On an elastic file system AWS bills them on top of the elastic per-GB read and write charges, so those access components are priced as usual while the elastic read and write volume stays unknown as its own component.

Read and write bill separately, so one direction never stands in for the other — a workload that truly reads or writes nothing in a class states that with an explicit 0. IA or Archive storage assumed without its access assumptions leaves the access charge unknown. A declared lifecycle transition marks only the class it moves data into as expected and never invents its quantity: a file system that transitions to IA with no efs.storage.infrequentAccessGbMonth reports IA storage as unknown, and a return-to-primary policy names no destination so it expects neither. Provisioned throughput is declared capacity rather than usage and is not yet priced; elastic throughput data access and replication also stay unknown.

Lambda fields

Set these under a lambda group. The declared configuration scales and selects the components: MemorySize (CloudFormation default 128 MB) sizes the compute derivation, Architectures (default x86_64) selects the x86 or arm64 price dimensions, and EphemeralStorage above the included 512 MB adds a storage component. A declared value that cannot be resolved to a concrete number leaves the affected components unknown instead of silently pricing the default.

Compute GB-seconds are derived exactly from the assumptions — invocations × (averageDurationMs ÷ 1000) × (memoryMB ÷ 1024) — and the derivation is stated in the component explanation. Ephemeral storage GB-seconds use the declared megabytes above 512 in place of memory.

Missing lambda.averageDurationMs leaves only the derived duration and storage components unknown. Missing lambda.invocations leaves everything unknown, because every Lambda charge scales with it. SnapStart set to anything other than None, provisioned concurrency, response streaming, and Lambda@Edge invocations stay unknown.

API Gateway fields

Set these under an apigateway group. The declared API type is the discriminator: AWS::ApiGateway::RestApi bills REST requests, and AWS::ApiGatewayV2::Api bills HTTP requests or WebSocket messages and connection minutes depending on its ProtocolType. CDK HttpApi and WebSocketApi constructs imply the protocol; a V2 API whose protocol cannot be resolved stays unknown rather than defaulting to the cheaper HTTP schedule.

REST and HTTP APIs never share a price dimension: REST requests bill under the four-tier REST schedule against apigateway.requests.rest, HTTP requests under their lower two-tier schedule against apigateway.requests.http. An assumption that does not apply to the declared type — WebSocket fields on a request-billed API, or apigateway.requests on a WebSocket API — is reported as an unsupported unknown. Messages and connection minutes bill separately, so state a true zero explicitly rather than omitting one.

Stage caching keeps declared-capacity semantics. Data transfer, custom domain certificates, API Gateway Portals, and private API endpoint charges stay unknown or belong to their own resources.

Kinesis fields

Kinesis keeps IaC-declared capacity exact and adds assumed workload charges beside it. Provisioned streams keep their shard-hour and retention-hour rows, on-demand streams keep their declared stream-hour row, and registered enhanced fan-out consumers keep their consumer-shard-hour row.

Stream mode selects the applicable fields. On-demand ingestion and retrieval bill separately, so supplying only one leaves the other unknown. PUT payload units and long-term retention apply to provisioned streams only. Enhanced fan-out retrieval belongs on the AWS::Kinesis::StreamConsumer, so each registered consumer carries its own quantity.

Network fields

Network usage requires an explicit billed path. CloudBurn never turns an undirected byte total into a cheaper direction.

Global Accelerator accepts NorthAmerica, Europe, AsiaPacific, Australia, India, SouthKorea, SouthAmerica, SouthAfrica, and MiddleEast in place of <Geography>, with independent inbound and outbound quantities. The source geography comes from the accelerator's AWS Region. Direct Connect also requires the exact declared Location facility code. VPN outbound internet usage shares the awsDataTransfer.outboundInternet account pool, and Resolver query tiers share resolver.queries.

Validation limits

Any violation, duplicate JSON key, or unknown field fails the whole assumptions block with one explicit configuration error in the cost report.

What's next