# Mock API standards profile and source evidence

Reviewed 2026-11-01. This document pins the reference material for the educational Cloudflare mock. The runnable supported subset is documented in [`cloudflare/mock/CONTRACT.md`](../../cloudflare/mock/CONTRACT.md). This is not a TM Forum conformance, certification, production security, or interoperability claim.

## Scope and ownership

TMF620 exposes the offer; TMF648 records the quote and buyer acceptance; TMF622 records the product order; TMF641 records fulfilment requests; TMF638 records the resulting service instances. TMF651 supplies a synthetic standing agreement. These are the only six TM Forum API families in this profile.

The proposed IODSP v0.3 routine API consumes the accepted commercial terms and external outcome evidence to record liabilities, commitments and statements. IODSP neither creates the service order nor activates, verifies or releases network capacity. A statement records an amount due; external payment confirmation changes payment exposure. Mock control endpoints stand in for external fulfilment, assurance and payment systems.

## Pinned route and schema subset

The mixed major versions are deliberate: the local fullCIRCLE references cover catalog and quote v5, while the official pinned v4 schemas below supply order, service and agreement definitions. A version number is not a claim that every resource or operation in that version is supported.

| Family | Canonical base | Resource and supported purpose |
| --- | --- | --- |
| TMF620 v5.0.0 | `/tmf-api/productCatalogManagement/v5` | Read `productOffering` and its item resource |
| TMF648 v5 local profile | `/tmf-api/quoteManagement/v5` | Create/read `quote`; accept by PATCH |
| TMF622 v4.0.0 | `/tmf-api/productOrderingManagement/v4` | Create/read `productOrder` |
| TMF641 v4.0.0 | `/tmf-api/serviceOrdering/v4` | Create/read `serviceOrder` |
| TMF638 v4.0.0 | `/tmf-api/serviceInventory/v4` | Read `service`; external fulfilment supplies state |
| TMF651 v4.0.0 | `/tmf-api/agreementManagement/v4` | Read seeded `agreement` |

`productOrderingManagement` is the actual TMF622 v4.0.0 base path. Older public regular Swagger files use different versions and paths and are not the authority for this profile.

The following are schema facts used to shape the mock, rather than an assertion of exhaustive schema validation:

| Resource | Reference create requirements / shape |
| --- | --- |
| ProductOffering | Local fullCIRCLE response builder requires `@type`, `@baseType`, `id`, `href`. Official v5 `Extensible` requires `@type`; `productOfferingPrice` supports references or embedded price values. Only GET is exposed. |
| Quote | Local `QuoteCreate` requires `@type: Quote`, `@baseType: Entity`; local `Quote` also requires `id`, `href`, `state`. Each `QuoteItem` requires `@type: QuoteItem` and `id`; local item action subset is `add`. The mapping prose calls `quoteItem` and `relatedParty` mandatory, while its builder does not; the demo must carry its explicit item/party data where used. |
| ProductOrder | `ProductOrder_Create` requires nonempty `productOrderItem`. Each item requires `id`, `action`; the demo uses `add`. The quote link is `quote: [{id: ...}]`, not a custom scalar `quoteId`. |
| ServiceOrder | `ServiceOrder_Create` requires nonempty `serviceOrderItem`. Each item requires `id`, `action`, `service`; service may be a reference or embedded value. |
| Service | `Service_Create` requires `state` and `serviceSpecification`; a specification reference requires `id`. The demo reads inventory resulting from external fulfilment. Order correlation is `serviceOrderItem: [{itemId, serviceOrderId, serviceOrderHref, ...}]`. |
| Agreement | `Agreement_Create` requires `agreementItem` (nonempty), `agreementType`, `engagedParty`, `name`. An engaged-party reference requires `id`, `name`, `@referredType`. Agreement uses `status` (free string) and `agreementPeriod`, rather than a standard `state` enum or `validFor`. Only GET is exposed. |

V5 quote party references follow the local nested shape `relatedParty: [{"@type":"RelatedParty","role":"customer","partyOrPartyRole":{"@type":"PartyRef","@referredType":"Organization","id":"operator-a"}}]`. V4 order/service `RelatedParty` instead carries `id`, `@referredType`, and optional role/name directly. Do not flatten the v5 party reference or copy the nested form into v4 records.

## Lifecycle values

The quote source enumerates `acknowledged`, `inProgress`, `pending`, `approved`, `rejected`, `accepted`, `declined`, `cancelled`. The demo selects a priced `approved` quote and records buyer `accepted`; acceptance alone reserves no service capacity.

Product and service order v4 schemas enumerate `acknowledged`, `rejected`, `pending`, `held`, `inProgress`, `cancelled`, `completed`, `failed`, `partial`, `assessingCancellation`, `pendingCancellation`. `activating` is a mock workflow phase, not a TMF order state; use `inProgress` on the order.

Service inventory v4 enumerates `feasibilityChecked`, `designed`, `reserved`, `inactive`, `active`, `terminated`. Uncertain activation must remain uncertain in the mock projection and cannot be converted into billable success by a timer. The OpenAPI enums enumerate legal values; the mock's deterministic transition graph is a narrower application policy, not a normative TMF state machine.

## Intentional extensions and limits

`demoProfile`, session isolation, `X-Demo-Session`, required mutation `Idempotency-Key`, server-owned quote sizing/rating, synthetic evidence, deterministic scenario controls, budget and credit checks, atomic resource reservations, terms hashes and proposed IODSP records are explicit DSRC mock behavior. They are not requirements or proof of compliance with the six TMF standards. Standard TMF Money is a decimal amount and currency; integer cents used internally or in the extension are an application accounting choice.

The v4 standard error shape requires `code` and `reason`; `status` is a string, and `referenceError`, if present, is a documentation URI string. The local quote builder additionally requires `status` and permits an object `referenceError` for state-conflict context. That is local behavior, not a v4 error definition.

The mock does not implement the complete CRUD surface, all standard schema properties, filtering/field projection/pagination, cancellation task resources, event hubs/listeners, OAuth scopes, conformance test kits, live inventory integrations or a real settlement rail. Strictly accepting a bounded create-field subset is a documented mock restriction. Server-generated prices and accepted liabilities remain authoritative.

## Official public sources pinned by commit

The TM Forum GitHub organization publishes these as mirrors and identifies the [TM Forum Open API directory](https://www.tmforum.org/oda/open-apis/directory/) as its authoritative directory. Exact contents were retrieved 2026-11-01 from the immutable links below; SHA-256 is over the original downloaded bytes. Scratch downloads under `.codex-build/tmf-schemas` are not served application assets.

| Schema | Immutable official source | SHA-256 |
| --- | --- | --- |
| TMF622 v4.0.0 | [TMF622-ProductOrder-v4.0.0.swagger.json](https://raw.githubusercontent.com/tmforum-apis/TMF622_ProductOrder/a3825f95248eb04fb1c7e2321305bc99631168a4/TMF622-ProductOrder-v4.0.0.swagger.json) | `b2435fed622d58c9f6c2dd339045659dbfdb531430ce92ce1b36dc4a357c08cd` |
| TMF641 v4.0.0 | [TMF641-Service_Ordering-v4.0.0.swagger.json](https://raw.githubusercontent.com/tmforum-apis/TMF641_ServiceOrder/b366ee4ffcdcb57cda6b184a8a8d0eac18bd5704/TMF641-Service_Ordering-v4.0.0.swagger.json) | `88110593180a2a4249e5e21f6c2c28fc2ae0c213f7dfd5fb958547e2be1cb89b` |
| TMF638 v4.0.0 | [TMF638-ServiceInventory-v4.0.0.swagger.json](https://raw.githubusercontent.com/tmforum-apis/TMF638_ServiceInventory/50fc82942e423c81896362d1ab9847f7c918cf7f/TMF638-ServiceInventory-v4.0.0.swagger.json) | `d3c4136952a80c5fc829311f6bbdfe3d2cc22ab7309d2e0716d92f79c6e93a28` |
| TMF651 v4.0.0 | [TMF651-Agreement-v4.0.0.swagger.json](https://raw.githubusercontent.com/tmforum-apis/TMF651_AgreementManagement/008dae3a3f929c97a34f767d051981aadb285b6c/TMF651-Agreement-v4.0.0.swagger.json) | `b55f1514d566c7dee1b08b2a81a3b6e2292f9da079041bc3a3ca12eb2a0fb88a` |