Skip to content
Vinxi/Kernel THE BOOK OF RECORD

ADR-0022: Standards interop lives at the edge — TMF SID/Open-API is the worked instance

ADR-0022: Standards interop lives at the edge — TMF SID/Open-API is the worked instance

Status

Accepted

Date

2026-07-03

Context

NETW-18’s remaining gap. The generic driver/connector framework — how any external system is reached — is already settled (ADR-0005, LLD §28 capability descriptors and target families, P16–P17). What was undecided is standards interoperability: telecom operators (BSNL and peers) require conformance to TM Forum standards — the SID information model, the Open-APIs (TMF639 Resource Inventory, TMF638 Service Inventory, TMF634/633 Resource/Service Catalog, TMF641/640/652 Ordering/Activation/Resource-Order, TMF673/674/675 Geographic Address/Site/Location, TMF621/642 Trouble/Alarm), and the ODA architecture — plus GIS import/export. TMF is one of many overlapping standards (MEF LSO, IETF YANG/RFC 8345, 3GPP NRM, ETSI NFV SOL, OGC/GeoJSON, O-RAN). The kernel is domain-agnostic (“shape, not meaning”), so the question is where standards conformance lives without teaching the kernel what a “Service” is.

Decision

  1. Standards interop is an edge concern; the kernel stays domain-agnostic. SID never becomes native kernel vocabulary. Conformance resolves into three mechanisms that already exist, none of which touches the kernel’s closed surface:

    • Expose → a surface projection;
    • Consume → a driver/connector;
    • Map the model → interface conformance in a Reality Package.

  2. Expose = a profiled TMF surface over the six verbs. A TMF Open-API facade is a surface projection (P18-class, alongside GraphQL and MCP): reads compile to the Query IR, writes (TMF641 Ordering, TMF640 Activation, TMF652 Resource Order) are Acts, and TMF hub notifications are emitted off Subscribe. It is a profiled adapter — one that knows the TMF REST envelope, pagination, and hub semantics — driven by the declared conformance + mapping (field-level mapping is config; the envelope is the adapter). Governed at the same seam, versioned per TMF API version. It is not fully code-generated from the mapping: TMF’s envelope and hub semantics make a profiled adapter the pragmatic call.

  3. Consume = a driver in the §28 connector surface. A peer’s TMF Open-API is an ordinary external source — a driver in the SaaS/business-API target family (MATERIALIZED via the driver SDK, or F2 get-by-key for live reads). Its MappingRef turns SID resources into entity/trait Asserts; inbound TMF hub notifications arrive as driver emit → Subscribe (ADR-0019). Nothing new is required.

  4. Map = SID conformance as interfaces. SID’s core abstractions (Resource, Service, Place, Party) live as structural interfaces (LLD §20/§26.6) that a telecom Reality Package’s entity types conform to, bound by a bidirectional MappingRef. The internal model stays richer than SID — bitemporal, fused, contested, graph — and SID is the deliberately lossy edge projection: expose TMF-compatible APIs even though the internal model is a richer temporal graph.

  5. TMF is the worked instance; the pattern generalizes. MEF LSO, IETF YANG/RFC 8345, 3GPP NRM, ETSI NFV SOL, OGC/GeoJSON, and O-RAN are future instances of the same recipe — an interface set plus a surface (expose) and/or a driver (consume) — never new architectures.

  6. GIS import/export. Import is the §28.5 geospatial connector family (PostGIS, File-GDB, WFS, ArcGIS REST via GDAL, geometry validated against the geo kind at admission). Export is a materialization to GeoJSON/Shapefile/GeoPackage (a P7 job or a surface) plus the TMF673/674/675 geographic surface and OGC/GeoJSON interfaces (geo.Locatable). This is largely covered already by §28.5 and the geo kind; the ADR names it explicitly.

Consequences

  • The kernel stays domain-agnostic; TMF/SID conformance is Reality-Package + surface/connector configuration, versioned per operator per TMF API version. Two operators’ differing TMF profiles are config, not forks (ties ADR-0020).
  • The consume half was already delivered by ADR-0005/§28; this ADR adds the expose (surface) and map (interface-conformance) halves and names the general recipe.
  • A profiled TMF surface adapter is a real build item (once per TMF API family), not free — but bounded and reused across all operators.
  • Feeds the telecom Reality Package and the BSNL pilot; per-tenant TMF config rides ADR-0020.
  • Revisit trigger: the first non-TMF standard a deal demands (MEF LSO for wholesale, YANG for device config) — same recipe, a new interface set + profile.

Alternatives Considered

  • SID as native kernel vocabulary. Rejected: it would teach the kernel what a “Service” is — a semantic monolith in kernel costume, the exact failure “shape, not meaning” exists to prevent.
  • Fully generating the TMF surface from the SID mapping (like GraphQL/MCP projection). Considered and set aside: TMF’s REST envelope and hub-notification semantics make a profiled adapter more honest than pretending the facade is free — the mapping is declared, the envelope is profiled.
  • A bespoke integration product per operator. Rejected: the fork attractor again; interop is edge configuration over one kernel, not a second codebase.