Version 0.1.3 (2026-10-22). Current version. Other versions: 0.1.2 (2026-10-08), 0.1.1 (2026-09-15).

Open Agent Spend Attribution (OASA) Specification

Version 0.1.3 · Initial public draft 2026-09-14 · Revised 2026-10-22 Published by Onaro (BrianOnAI LLC) · Licensed CC BY 4.0

Canonical HTML version: https://www.onaro.io/spec Pinned version: https://www.onaro.io/spec/v0.1.3

Abstract

OASA defines a canonical record format that attributes AI-agent resource consumption and spend to agent identity, task, and cost object, and joins runtime telemetry, normalized billing, and payment settlement into a single auditable ledger row. It is designed to interoperate with OpenTelemetry GenAI semantic conventions (telemetry), the FOCUS specification (billing), and x402 payment-rail records (settlement). It is not a payment protocol and not a billing format; it is the join between them.

Partial records are valid. Every field outside the envelope is optional so adapters can emit what they know and reconcile later. Within a major version, the schema is additive-only.

Design principles

• Hub-and-spoke: canonical middle, adapters at the edges.
• Settlement-agnostic: invoice, card, wire, and on-chain rails reconcile into the same spine.
• Additive to FOCUS and OpenTelemetry — never competing with them.
• Envelope required; all other groups optional so partial records remain valid.
• Versioned; additive-only within a major version.

The three-layer model

        ┌───────────────────────────────┐
        │  Telemetry — OTel GenAI       │
        └───────────────┬───────────────┘
                        │  trace_id
        ┌───────────────┴───────────────┐
        │  Attribution — OASA           │
        │  (canonical)                  │
        └───────────────┬───────────────┘
                        │  invoice_id + source_record_id
                        │  settlement_ref
        ┌───────────────┴───────────────┐
        │  Billing — FOCUS              │
        │  + Settlement — x402          │
        └───────────────────────────────┘

Join keys on the edges; attribution in the middle.

Record schema v0.1.3

Group 1 — Envelope (required)

source_system = otel-collector is the value emitted by oasa-otel-exporter, an OpenTelemetry Collector exporter that turns GenAI spans into OASA usage records.

Group 2 — Agent identity

Group 3 — Task & session context

Group 4 — Consumption

Group 5 — Cost

Group 6 — Allocation

Group 7 — Settlement join

Group 8 — Control & governance

Group 9 — Outcome (optional, forward-looking)

Outcome capture is intentionally minimal in v0.1; it exists so cost-per-outcome queries have a landing zone.

Attribution

agent_id, agent_owner, cost_center, and project_id are the common attribution fields. Each stays optional and keeps the definition in its field group. This section says how a producer records the source of each field, the order of sources, and how a native identifier becomes one of those fields.

customer_id, product_line, environment, tags, task, session, and trace fields stay on the record. They are not common attribution fields and they do not get an attribution entry. Setting customer_id alone does not clear attribution_unattributed_reason.

Per-field provenance

attribution is an object. Its keys are common fields. Each value has four members:

When attribution is present, its keys MUST be exactly the common fields that are set on the record, and each entry MUST include all four members. A lower-precedence source MAY fill a field a higher-precedence source left empty, and that field gets its own entry.

A record MAY omit attribution. Every 0.1.2 record omits it and remains valid. Producers of new attributed records SHOULD include it whenever a common field is set.

attribution_unattributed_reason is record-level. It MUST be absent when any common field is set. There is no per-field unattributed method. A producer that attributes a record and sets none of the four common fields MUST set the reason. A record MAY omit the reason; 0.1.2 records that name no common field omit it and remain valid.

Methods

cost_source says how the money was derived. allocation_method says how a split was calculated. method says how the actor and the cost object were chosen.

Resolution order

Each common field is resolved on its own. The first source that supplies that field sets it:

1. declared
2. manual
3. mapped
4. inherited
5. rule
6. unattributed

unattributed applies to the record only when none of the four fields was set.

A manual assignment overrides mapped, inherited, and rule for the fields it names. A field already stored as one of those three MAY be replaced by a manual assignment; its provenance becomes manual.

A declared value on a stored record is left as declared. To correct it, publish an allocation record, or a charge with tags.adjustment = true as the FOCUS mapping describes for ChargeCategory = Adjustment. The new record carries its own per-field provenance.

A usage record and the charge that bills it stay two records. They join on trace_id when both have one. Inheritance MAY fill a field the charge left empty. It does not replace a field the charge declared.

When two mapping records match the same identity type, the same value, and overlapping windows, neither is applied. If the record then has no common field, the reason is mapping_conflict. If another field was set, the conflicted field stays empty and the record-level reason stays absent. Publishers SHOULD treat overlapping windows for one pair as an invalid mapping set.

occurred_at selects the mapping. A mapping that changes later does not rewrite a record whose occurred_at is already inside an earlier window.

Unattributed reasons

Closed enum. A new reason is a minor spec revision. The reason is set only when none of the four common fields is set.

Mapping records

A mapping record says: this native identifier means these common fields, from this time to this time. It carries the envelope. occurred_at is when the mapping was recorded. valid_from is when it takes effect.

attribution and attribution_unattributed_reason MUST be absent on a mapping record. attribution_identity_type, attribution_identity_value, valid_from, and valid_to MUST be absent on every other record type. On those records the identity pair lives inside the per-field entry.

The envelope stays the only schema-required group. A partial mapping still validates. Receivers MAY refuse to apply a mapping that lacks a type, a value, or valid_from.

Applying a mapping fills each still-empty target field with method = mapped, the mapping's identity pair, and source_system set to the system that minted that identity. A field already declared is left declared. A manual assignment for that field wins over the mapping.

Identity type names

identity_type is a string, not a closed enum. Receivers MUST match the names below as case-sensitive strings. Unknown types are allowed. They match a row only when a mapping record uses them.

Form: lowercase segments separated by dots. Each segment starts with a letter and otherwise contains [a-z0-9_].

The initial vocabulary, by the shape of the native identity. Platform grain is recorded in Attribution identity by platform.

A gateway identity reaches the provider invoice only when the upstream call also sets a provider partition, tag, or label. Otherwise a provider charge with no join key is not_on_bill.

Tagging convention

One set of keys, written so a Google Cloud request label will accept them. Keys and values are lowercase letters, digits, underscores, and dashes. A key starts with a lowercase letter. Key and value are at most 63 characters. Empty values are not used. Those limits are the Google Cloud request-label rules read on 2026-10-22 from Custom metadata labels. A label key can be dropped after 1,000 distinct values for that key over the life of the billing account.

environment is not a common attribution field and has no provenance entry. The tag value should be prod, staging, or dev when the environment is one of those.

These four oasa_ keys are the names this specification defines. An implementation MAY accept configured aliases for keys a customer already writes. An alias fills the same field as the convention key it stands in for. The field is declared. identity_value SHOULD be the key that was present on the row.

trace_id, span_id, session_id, task_id, request id, message id, end-user id, email, and timestamp MUST NOT be tag or label keys or values. An agent catalog larger than 1,000 distinct oasa_agent values on one Google billing account MUST NOT put oasa_agent on Google labels. Bind those agents with a mapping record from the profile or project id.

Record schema v0.2.0 (additive)

schema_version "0.2" / "0.2.0" unlocks Group 10 and the capacity record type. v0.1.x records remain valid unchanged. Receivers that advertise known-minor 0.2 MUST reject infrastructure.* keys and record_type: capacity on schema_version < 0.2.

Extended record_type

Group 10 — Infrastructure

Wire names are flat (same style as token/cost fields). OTLP attribute reservations use the oasa.infrastructure.* namespace and map onto these wire names.

Token and cost groups remain permitted (not required) on capacity records.

Draft OTLP attribute reservations (v0.2 binding)

These reservations are draft until OASA 0.2.0 is published. They MUST NOT collide with OpenTelemetry GenAI semantic conventions.

Deterministic record IDs

Receivers deduplicate on record_id. An adapter that generates a fresh random ID on every attempt turns each retry into a duplicate row. Adapters whose source has a stable key SHOULD derive record_id from it with the procedure below; two implementations given the same inputs then produce the same ID, and the result is still a valid UUIDv7 under RFC 9562.

Inputs: occurred_at and source_record_id of the record being emitted.

1. ms = occurred_at as Unix time in milliseconds, truncated (not rounded) to the millisecond.
2. h = SHA-256 of the UTF-8 bytes of source_record_id.
3. Build 16 bytes b:
   • b[0..5] = ms as a 48-bit big-endian integer.
   • b[6] = 0x70 | (h[0] & 0x0F) (version 7).
   • b[7] = h[1].
   • b[8] = 0x80 | (h[2] & 0x3F) (RFC 9562 variant).
   • b[9..15] = h[3..9].
4. Format b as a lowercase hyphenated UUID string (8-4-4-4-12).

For OpenTelemetry spans, source_record_id is <trace_id>/<span_id> in lowercase hex and occurred_at is the span end time.

Test vector: occurred_at = 2026-09-01T15:04:05Z, source_record_id = 4bf92f3577b34da6a3ce929d0e0e4736/00f067aa0ba902b7 → record_id = 01a05d7f-b288-7532-8207-8cb53896d9e1.

Derived IDs are predictable from their inputs. They are identifiers, not secrets, and MUST NOT be used as access tokens.

Machine-readable schema

The record tables above are published as JSON Schema (draft 2020-12) for adapters to validate their output:

• schema/oasa-record.schema.json: the 0.1.2 record schema. $id https://oasaspec.org/schema/0.1/oasa-record.schema.json. This document is unchanged in 0.1.3.
• schema/oasa-batch.schema.json: the 0.1.2 batch schema. $id https://oasaspec.org/schema/0.1/oasa-batch.schema.json.
• schema/0.1.3/oasa-record.schema.json: the 0.1.3 record schema. $id https://oasaspec.org/schema/0.1.3/oasa-record.schema.json.
• schema/0.1.3/oasa-batch.schema.json: the 0.1.3 batch schema. $id https://oasaspec.org/schema/0.1.3/oasa-batch.schema.json.
• examples/: golden records, one per file. Current examples validate against the 0.1.3 record schema. The six records published with 0.1.2 also validate against the unchanged 0.1.2 schema.

A published $id never changes, and the document at that identifier never changes. 0.1.3 has its own identifier. schema_version inside a record stays "0.1". The 0.1.3 schema is generated from this document by scripts/generate-schema.mjs and never edited by hand. A field change is a pull request against SPEC.md first; the schema is regenerated from it, and CI fails if the committed 0.1.3 schema drifts from these tables. Run npm run validate to check every example, including the six golden records published with 0.1.2.

Decimal fields, including every money field, are JSON numbers. Consumers SHOULD parse them with decimal precision rather than binary floating point.

The 0.2.0 draft (Group 10 and capacity) is not covered yet; it gets its own schema when 0.2.0 is published. The schema files, examples, and scripts are licensed Apache-2.0 (see LICENSE-APACHE); the specification text remains CC BY 4.0.

Batch envelope

Adapters that send records in bulk wrap them in this header. Every record in records is validated independently; the header carries no attribution.

Mapping tables

Verified against upstream docs on 2026-09-15. The oasa.* rows and the gen_ai.agent.id row were revised on 2026-10-22, when the GenAI registry defined gen_ai.agent.id as a hosted agent resource id. OpenTelemetry GenAI conventions are still experimental and may drift; unmapped OASA fields are noted where no ratified equivalent exists. FOCUS token-economics columns track 1.4 (ratified) and 1.5 (scheduled). x402 V2 communicates requirements via PAYMENT-REQUIRED payloads (network, asset, amount, payTo).

OASA ↔ OpenTelemetry GenAI

oasa-otel-exporter v0.1.0 implements the earlier reading of this table, in which agent_id is read from gen_ai.agent.id. Output from that version remains valid 0.1.2. The rows below are the 0.1.3 mapping.

OASA ↔ FOCUS

FOCUS 1.4 added token-economics columns; FOCUS 1.5 (Dec 2026 target) adds native token tracking and a Price Sheet dataset. OASA tracks those columns as they ratify.

Full column-by-column mapping, including the Invoice Detail dataset and worked examples: OASA ↔ FOCUS 1.4 mapping.

A convention key in FOCUS Tags declares the matching common field: oasa_cost_center, oasa_agent, oasa_owner, oasa_project. The provenance identity_value is that key. An accepted alias is declared the same way, and identity_value is the key on the row. Export carries the attribution object in the custom column x_oasa_attribution, and attribution_unattributed_reason in x_oasa_unattributed_reason when the reason is set. Mapping records are not FOCUS cost rows.

OASA ↔ x402

Worked example

One agent tool-call as a usage row, later joined by a charge row and an x402 settlement row sharing trace_id / settlement_ref.

1. Usage (telemetry)

{
  "record_id": "0193f0a0-0000-7000-8000-000000000001",
  "record_type": "usage",
  "schema_version": "0.1",
  "occurred_at": "2026-09-01T15:04:05Z",
  "recorded_at": "2026-09-01T15:04:06Z",
  "source_system": "otel-collector",
  "source_record_id": "span-9f2c",
  "currency": "USD",
  "agent_id": "agent-support-47",
  "agent_name": "Support Triage",
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "span_id": "00f067aa0ba902b7",
  "task_type": "ticket_resolve",
  "provider": "openai",
  "model": "gpt-4.1",
  "operation": "tool_call",
  "tool_name": "crm.lookup",
  "input_tokens": 1200,
  "output_tokens": 340,
  "cached_tokens": 800,
  "session_id": "sess-2f91",
  "unit_type": "tokens",
  "units_consumed": 1540,
  "cost_source": "measured"
}

2. Charge (billing)

{
  "record_id": "0193f0a0-0000-7000-8000-000000000002",
  "record_type": "charge",
  "schema_version": "0.1",
  "occurred_at": "2026-09-02T00:00:00Z",
  "recorded_at": "2026-09-02T06:12:00Z",
  "source_system": "openai-billing",
  "source_record_id": "inv_line_88421",
  "currency": "USD",
  "agent_id": "agent-support-47",
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "invoice_id": "INV-2026-09-01",
  "focus_charge_ref": "focus:row:88421",
  "list_cost": 0.042,
  "billed_cost": 0.038,
  "effective_cost": 0.038,
  "cost_source": "invoiced"
}

3. Settlement (x402)

{
  "record_id": "0193f0a0-0000-7000-8000-000000000003",
  "record_type": "settlement",
  "schema_version": "0.1",
  "occurred_at": "2026-09-01T15:04:07Z",
  "recorded_at": "2026-09-01T15:04:08Z",
  "source_system": "x402-facilitator",
  "source_record_id": "pay_0xabc",
  "currency": "eip155:8453/erc20:0x",
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "settlement_rail": "x402",
  "settlement_network": "eip155:8453",
  "settlement_asset": "eip155:8453/erc20:0x",
  "settlement_amount": 0.038,
  "settlement_ref": "0xdeadbeef",
  "settled_at": "2026-09-01T15:04:07Z",
  "reconciliation_status": "matched"
}

References

Upstream specifications and standards this document maps to or depends on.

Referencing these specifications does not imply endorsement by their stewards. OASA is an independent publication of Onaro (BrianOnAI LLC).

Changelog

See CHANGELOG.md.

Cite this specification

Open Agent Spend Attribution (OASA) Specification, version 0.1.3. Onaro, 2026-09-14 (revised 2026-10-22). https://www.onaro.io/spec

License: CC BY 4.0. Attribution required; adaptations allowed.