TM Forum Open APIs Join Smart Data Models: 174 Candidate Models for the Whole Telecom Digital-Service Stack

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 @context maps it to its definition in the versioned OpenAPI file on GitHub, and all 3,181 of these links were checked.
  • TMF polymorphism kept. @type, @baseType and @schemaLocation become tmfType, tmfBaseType and tmfSchemaLocation, and the TMF id becomes tmfId. A few other names that clash with NGSI-LD or with common Smart Data Models attributes also get a tmf prefix, and TMF703’s Entity becomes TmfEntity.
  • 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

Bookmark the permalink.

Comments are closed.