Smart Data Models’ Candidates repository already had a first slice of the TM Forum Open APIs (five inventory, order and trouble-ticket models). The candidate tmforum-open-apis now covers every TM Forum Open API published under Apache-2.0: 86 APIs and 174 candidate models, one per managed resource, linked by 213 NGSI-LD Relationships. As with every candidate, each model has a JSON Schema, an NGSI-LD @context and four example serializations (NGSI-v2 and NGSI-LD, key-values and normalized), each validated against its schema.
About the TM Forum Open APIs
TM Forum is the global industry association of communication service providers and their suppliers. Its Open APIs are the REST interfaces of the Open Digital Architecture (ODA), used across the industry for catalogues, ordering, inventory, assurance, billing, party management, testing, IoT, AI and partner APIs (Open Gateway). Through its API Apache 2.0 project, TM Forum publishes the OpenAPI files on github.com/tmforum-apis. We checked the licence of every repository at the exact release we used. We left out the one API without a licence file (TMF667 Document), the repository template and one repository that has no OpenAPI file yet. We used the latest release of each API: 38 are at v5, the others at v4 or older.
The models
| Area | TM Forum APIs | Models | Model names |
|---|---|---|---|
| Catalogues | TMF620, TMF633, TMF634, TMF662, TMF767, TMF936 | 22 | ProductCatalog, Category, ProductOffering, ProductOfferingPrice, ProductSpecification, ServiceCatalog, ServiceCategory, ServiceCandidate, ServiceSpecification, ResourceCatalog, ResourceCategory, ResourceCandidate, ResourceSpecification, EntityCatalog, EntityCategory, EntityCatalogItem, EntitySpecification, AssociationSpecification, Association, ProductUsageSpecification, OpenGatewayProductOffering, OpenGatewayProductSpecification |
| Ordering, qualification and sales | TMF622, TMF641, TMF652, TMF648, TMF663, TMF645, TMF679, TMF760, TMF680, TMF699, TMF651, TMF687, TMF700, TMF697, TMF716 | 21 | ProductOrder, ServiceOrder, ServiceOrderSpecification, ResourceOrder, Quote, ShoppingCart, CheckServiceQualification, QueryServiceQualification, CheckProductOfferingQualification, QueryProductOfferingQualification, CheckProductConfiguration, QueryProductConfiguration, QueryProductRecommendation, SalesLead, SalesOpportunity, Agreement, AgreementSpecification, ProductStock, ShippingOrder, WorkOrder, ResourceReservation |
| Inventory | TMF637, TMF638, TMF639, TMF664, TMF685, TMF703, TMF640, TMF702, TMF730 | 7 | Product, Service, Resource, ResourceFunction, ResourcePool, Reservation, TmfEntity |
| Assurance and performance | TMF621, TMF642, TMF656, TMF653, TMF657, TMF649, TMF628, TMF724, TMF655 | 18 | TroubleTicket, TroubleTicketSpecification, Alarm, ServiceProblem, ServiceProblemEventRecord, ServiceTest, ServiceTestSpecification, ServiceLevelObjective, ServiceLevelSpecification, Threshold, ThresholdRule, ThresholdJob, MeasurementCollectionJob, PerformanceIndicatorGroupSpecification, PerformanceIndicatorSpecification, TrackingRecord, Incident, ChangeRequest |
| Party, customer and identity | TMF629, TMF632, TMF669, TMF668, TMF644, TMF683, TMF717, TMF720, TMF691, TMF672, TMF681, TMF646, TMF658, TMF671 | 27 | Customer, Individual, Organization, PartyRole, PartyRoleSpecification, Partnership, PartnershipSpecification, PartyPrivacyAgreement, PartyPrivacyProfile, PartyPrivacyProfileSpecification, PartyInteraction, Customer360, DigitalIdentity, Userinfo, PermissionSet, PermissionSpecification, PermissionSpecificationSet, CommunicationMessage, Appointment, ProgramProductSpec, LoyaltyRule, LoyaltyAction, LoyaltyCondition, LoyaltyEventType, LoyaltyMember, LoyaltyBalance, Promotion |
| Accounts, billing, payment and usage | TMF666, TMF670, TMF676, TMF678, TMF654, TMF635, TMF677, TMF771, TMF735, TMF736, TMF737, TMF738 | 24 | PartyAccount, BillingAccount, SettlementAccount, FinancialAccount, BillFormat, BillPresentationMedia, BillingCycleSpecification, PaymentMethod, Payment, Refund, CustomerBill, AppliedCustomerBillingRate, BillCycle, Bucket, AccumulatedBalance, BalanceActionHistory, ProductUsage, UsageConsumptionReport, ResourceUsage, ResourceUsageSpecification, CdrTransaction, PartyRevSharingAlgorithm, PartyRevSharingReport, PartyRevSharingModel |
| Places and shipping | TMF673, TMF674, TMF675, TMF684 | 4 | GeographicAddress, GeographicSite, GeographicLocation, ShipmentTracking |
| Test management | TMF704, TMF705, TMF706, TMF707, TMF708, TMF709, TMF710 | 19 | TestCase, TestSuite, NonFunctionalTestModel, AbstractEnvironment, ConcreteEnvironmentMetaModel, TestResourceAPI, ProvisioningArtifact, TestDataInstance, TestDataSchema, TestCaseResult, TestSuiteResult, NonFunctionalTestResult, TestEnvironmentAllocationExecution, TestEnvironmentProvisioningExecution, TestCaseExecution, TestSuiteExecution, NonFunctionalTestExecution, TestScenario, GeneralTestArtifact |
| Process, intent, events and risk | TMF701, TMF921, TMF688, TMF696 | 14 | Process, ProcessSpecification, Task, TaskSpecification, Intent, IntentSpecification, IntentReport, Topic, Event, ProductOfferingRiskAssessment, PartyRoleRiskAssessment, PartyRoleProductOfferingRiskAssessment, ShoppingCartRiskAssessment, ProductOrderRiskAssessment |
| Component suites (IoT, AI, Open Gateway, NaaS, self-care) | TMF908, TMF914, TMF915, TMF931, TMF909, TMF910 | 18 | IotDevice, IotDeviceSpecification, DataAccessEndpoint, IotDataEvent, IotManagementEvent, IotService, IotServiceSpecification, User, AiModel, AiModelSpecification, AiContract, AiContractSpecification, AiContractViolation, Rule, ApiProduct, ApiProductOrder, Application, ApplicationOwner |
Some APIs, mostly the component suites, only re-publish resources that another API already defines, such as Service, Resource or Alarm. Those resources are modelled once, from the API that owns them. Operations like cancelling an order or acknowledging an alarm are not separate models, and neither are the notification payloads.
Examples
For the 78 models from v5 APIs, the examples are the example payloads in TM Forum’s own OpenAPI files (Apache-2.0, illustrative, not real operator data). The older v4 files have no example payloads, so the other 96 examples are generated from the schema and its example values. Each example says which kind it is in its source. Many of these resources hold personal data in real deployments (individuals, customers, contacts, digital identities), so all examples are fictitious. Names of people are removed or replaced by “Jane Doe”, e-mail addresses use example.com, phone numbers come from the ranges reserved for fiction, and postal addresses and identity-document numbers are placeholders.
Translation notes
- TMF names, verbatim. Every attribute keeps its TMF name. Each
@contextmaps it to its definition in the versioned OpenAPI file on GitHub, and all 3,181 of these links were checked. - TMF polymorphism kept.
@type,@baseTypeand@schemaLocationbecometmfType,tmfBaseTypeandtmfSchemaLocation, and the TMFidbecomestmfId. A few other names that clash with NGSI-LD or with common Smart Data Models attributes also get atmfprefix, and TMF703’sEntitybecomesTmfEntity. - A connected graph. When a TMF attribute references a resource that is also a model here, it becomes an NGSI-LD Relationship. For example, a product offering points to its specification and prices, a product to its offering and billing account, and a service problem to the affected service, resource and trouble ticket. Characteristics, prices, related parties and order items keep their full TMF structure as nested JSON.
- One generator. A single generic script, driven by a table of API, repository, release, file and resources, produces all 174 models. It was also used to regenerate the five original models, which move to schema version 0.0.2 because their references to catalogue, billing and intent resources are now Relationships.
- Source issues documented. The metadata lists the small problems found in the specifications, such as invalid timestamps, example attributes missing from the schemas, dangling references and copyright lines left over in some files, for reporting upstream.
Try it, and tell us what’s missing
These are Candidates: carefully sourced translations, not yet official Smart Data Models subjects. The main open question before promotion is naming. Many TMF names are generic (Organization, Event, Alarm, Rule, Task, User, Product, Service…) and already exist in Smart Data Models or other candidates with other meanings. There is also scope overlap with dataModel.Organization, dataModel.Device and dataModel.IssueTracking.
Browse the models, open an issue, or send a PR:
👉 https://github.com/smart-data-models/Candidates/tree/master/standards/tmforum-open-apis

