OpenAPI export: emit x-jsonld-context / x-jsonld-type per Schema Object (incl. pydantic->FastAPI->Swagger-UI)

[simontaurus]

OpenAPI export: emit x-jsonld-context / x-jsonld-type per Schema Object

Implement the OO-LD -> OpenAPI delivery path defined in the spec (Delivery to OpenAPI, MCP and LLM tooling; rationale tracked in the now-closed OO-LD/oold-schema#42, example added in OO-LD/oold-schema#60). The goal is to take an OO-LD schema (or an OO-LD-flavored pydantic model) and produce an OpenAPI document whose Schema Objects carry the JSON-LD semantics via the REST-API-LD keywords, renderable in a JSON-LD-aware Swagger-UI.

Scope

1. Core transform (OO-LD schema -> OpenAPI Schema Object), per class

• @context -> x-jsonld-context (value copied verbatim; object, array, or URL string are all valid per draft Section 2.2).
• x-oold-instance-rdf-type -> x-jsonld-type (single IRI or array of IRIs - JSON-LD @type per Section 3.5 allows a list; verify the renderer below handles the array form).
• Structural keywords (type, properties, required, allOf, ...) unchanged.
• $id -> the components/schemas key; cross-class $ref rewritten to #/components/schemas/<Class>.
• OpenAPI 3.1: native top-level @context is also valid (arbitrary keywords allowed); 3.0: use the x-jsonld-* form. Support both.
• Lossless and reversible: a round-trip test (OO-LD schema -> OpenAPI 3.0 -> OO-LD schema) must reproduce the original @context and rdf-type.

2. Route from OO-LD-flavored pydantic to OAS via FastAPI

• oold-python emits pydantic models with the embedded @context (existing codegen). FastAPI generates the OpenAPI document from those models.
• Inject x-jsonld-context + x-jsonld-type onto each component schema during OpenAPI generation - e.g. via model_config/json_schema_extra, a custom GenerateJsonSchema, or overriding FastAPI.openapi().
• Result: a FastAPI app whose /openapi.json carries the linked-data annotations per Schema Object, for both 3.1 and 3.0 targets.

3. Rendering with Polli's customized Swagger-UI

• Wire the annotated OpenAPI into the REST-API-LD-aware Swagger-UI fork (italia/swagger-editor) so the JSON-LD context/type render alongside each schema.
• Provide a minimal runnable demo (FastAPI app + the customized Swagger-UI) and a screenshot in the docs.
• Tooling-reality check: the draft's examples only use a single scalar x-jsonld-type; confirm the renderer also displays an array of types, and file upstream if it does not.

Acceptance criteria

• A documented oold API that transforms an OO-LD schema to an OpenAPI 3.0 and 3.1 document with per-class x-jsonld-context / x-jsonld-type.
• Round-trip test (OO-LD -> OAS 3.0 -> OO-LD) passing in CI.
• A FastAPI example app emitting an annotated /openapi.json from an OO-LD-flavored pydantic model.
• A worked demo rendering the annotated OAS in the JSON-LD-aware Swagger-UI, including a multi-type (array) x-jsonld-type case, with a screenshot in the docs.

Milestone: M2 (Core Features).