Semantic tagging for interoperability (of 3rd party cloud platforms)

[tietoafinlandoy]

Greetings from Apidays Helsinki & North 2025. Today, APIs speak in schemas, but not that much yet in shared meanings. This leads to brittle integrations, redundant sync logic, and endless manual mapping. Are we able to fix that?

right at heart of it by extending OpenAPI with:

x-semantic-tag: to declare what each field exactly means regardless name of it (e.g., API item field name can be: "purchase_state" but we mark it schema:status.payment.order)
x-master-data: empowers each business to declare, per integration context, which API is the source of truth for each field — enabling controlled, conflict-free sync across cloud platforms.

This simple, vendor-neutral metadata would enable:

• Smarter, AI-assisted field matching across APIs
• Clear master data governance per field --> per chosen joined platforms
• Scalable sync automation with less conflict and duplication

Imagine cloud APIs that "understand" each other semantically — and sync data reliably with zero fragile glue code. With OpenAPI 3.1 and existing extension mechanisms, we’re nearly there.

Tomas Westerholm, CTO
tomas.westerholm@tietoa.fi

Explored the idea with ChatGPT 4o:
Open API semantic tagging for interoperability.pdf

[handrews]

@tietoafinlandoy Why not just use JSON-LD if you want to add semantics? There is a whole body of semantic web research and technology out there, why re-invent the wheel with OAS extensions? To do what you want, would we need to allow the OpenAPI Description documents to be JSON-LD documents of some sort? (I am tossing ideas around here, I really do not know the answers to these questions right now).

[tietoafinlandoy]

I'm netiher an expert on this - rather just exploring it. JSON-LD (and all of the already existing industry of semantics belongs to this topic)

Asking "layman" developers to suddenly adopt JSON-LD documents might create an adoption barrier. We could make it in two steps:

1. OpenAPI extensions provide basic semantic mapping for tooling and field matching
2. JSON-LD contexts provide rich semantic relationships inside the actual data payloads
   --> Tooling bridges can generate JSON-LD contexts from OpenAPI semantic tags

This gives us a migration path: start with simple x-semantic-tag annotations that developers can adopt immediately, then optionally evolve toward richer JSON-LD semantics as teams become more sophisticated.

And totally agree, with the simple tags, it would be cricial to relay on some relevant and adoptable existing semantics model rather than trying to invent a new one. Otherwise the tagging is useless in overall context of easing the mapping of APIs to each others - the main goal.

https://schema.org/ perhaps?

Like this, the creator of API should know which one is correct and thus help the automation of mapping. Though, AI can try to do that as well if there is the larger context given.

customer_id: "schema:Person/identifier"
customer_id: "schema:Organization/identifier"
customer_id: "schema:Customer/identifier"

It would be an interesting test to give AI the task of "tagging" multiple APIs using a semantic model and then check how well they eventually map to each other in respect to what the items really represent.