Skip to content

feat: generate an OpenAPI 3.1 contract from the enriched catalog#5

Open
estebanzimanyi wants to merge 1 commit into
masterfrom
feat/openapi-generator
Open

feat: generate an OpenAPI 3.1 contract from the enriched catalog#5
estebanzimanyi wants to merge 1 commit into
masterfrom
feat/openapi-generator

Conversation

@estebanzimanyi
Copy link
Copy Markdown
Member

@estebanzimanyi estebanzimanyi commented May 18, 2026

What

Adds generator/openapi.py + generate_openapi.py: projects the enriched
MEOS catalog onto an OpenAPI 3.1 contract — the concrete realisation of
"OpenAPI is a projection of MEOS-API".

python run.py                 # enriched catalog -> output/meos-idl.json
python generate_openapi.py    #              -> output/meos-openapi.json

How

  • One RPC-style POST /{function} per stateless-exposable function
    (a MEOS function ≈ an OGC API – Processes "process").
  • Opaque values cross the wire as strings in their typeEncodings
    (text / MF-JSON / HexWKB), surfaced as reusable components.schemas.
  • Enums → string component schemas with the real C constant names.
  • x-meos-{category,decode,encode,in,out,encodings} make the document
    self-describing, so a downstream server / MCP / gRPC generator needs
    nothing beyond this file.
  • Pure dict → dict (no libclang, no MEOS runtime); deterministic
    (sorted) output so generated diffs are reviewable.

Validation

Run against the live MobilityDB master catalog: 2672 functions →
1790 operations over 14 component schemas, every path a single POST
with responses, all $refs resolve. tests/test_openapi.py: 8 stdlib
unittest cases (serialized/enum/void/exclusion/ref-resolution), all green.
Contract and roadmap in docs/openapi.md.

Scope / dependency

Logically stacks on the catalog-enrichment work (it consumes the
network / wire / typeEncodings fields). It delivers the contract,
not a runtime server. Natural follow-ups (separate PRs): an MCP tool-manifest
generator from the same model, OpenAPI conformance validation in CI, and an
OGC API – Moving Features resource projection.

@estebanzimanyi estebanzimanyi mentioned this pull request May 18, 2026
Open
@estebanzimanyi estebanzimanyi force-pushed the feat/openapi-generator branch from 146c37d to d5d340f Compare May 18, 2026 10:24
@estebanzimanyi
feat: generate an OpenAPI 3.1 contract from the enriched catalog
fc1c600 
Adds generator/openapi.py + generate_openapi.py: projects the enriched MEOS catalog (network/wire/typeEncodings from the service-projection pass) onto an OpenAPI 3.1 document.

- one RPC-style POST /{function} per stateless-exposable function
  (a function is to MEOS what a process is to OGC API - Processes)
- opaque values cross the wire as strings in their typeEncodings
  (text/MF-JSON/HexWKB), surfaced as reusable component schemas
- enums become string component schemas with the real C constant names
- x-meos-{category,decode,encode,in,out,encodings} make the document
  self-describing for a downstream server/MCP/gRPC generator
- pure dict -> dict (no libclang, no MEOS runtime), deterministic output

Logically depends on the catalog being enriched. Validated against the
live MobilityDB master catalog: 2672 functions -> 1790 operations over
14 component schemas, all $refs resolve. Documented in docs/openapi.md;
tested in tests/test_openapi.py (stdlib unittest).
@estebanzimanyi estebanzimanyi force-pushed the feat/openapi-generator branch from d5d340f to fc1c600 Compare May 18, 2026 10:30
This was referenced May 20, 2026
Open
Open
estebanzimanyi added a commit that referenced this pull request May 20, 2026
@estebanzimanyi
ci(openapi): add openapi-validate workflow
0e31082 
Runs the full regenerate path on every PR touching the parser, generator,
meta files, or generate_openapi.py:

- libclang sysroot install (matches MobilityAPI vendor-drift)
- clone MobilityDB master for MEOS headers
- run.py + generate_openapi.py
- openapi-spec-validator against OpenAPI 3.1
- upload meos-openapi.json as an artefact

Catches OpenAPI 3.1 violations the moment a generator change introduces
them, instead of letting downstream consumers (MobilityAPI vendor-drift,
PyMEOS-CFFI codegen, MobilityDuck binding generator) discover them
later. Named as a 'natural follow-up' in PR #5's body.
estebanzimanyi added a commit that referenced this pull request May 20, 2026
@estebanzimanyi
ci(openapi): add openapi-validate workflow
708b8b9 
Runs the full regenerate path on every PR touching the parser, generator,
meta files, or generate_openapi.py:

- libclang sysroot install (matches MobilityAPI vendor-drift)
- clone MobilityDB master for MEOS headers
- run.py + generate_openapi.py
- openapi-spec-validator against OpenAPI 3.1
- upload meos-openapi.json as an artefact

Catches OpenAPI 3.1 violations the moment a generator change introduces
them, instead of letting downstream consumers (MobilityAPI vendor-drift,
PyMEOS-CFFI codegen, MobilityDuck binding generator) discover them
later. Named as a 'natural follow-up' in PR #5's body.
@estebanzimanyi estebanzimanyi mentioned this pull request May 20, 2026
Open
estebanzimanyi added a commit that referenced this pull request May 20, 2026
@estebanzimanyi
ci(openapi): add openapi-validate workflow
420f869 
Runs the full regenerate path on every PR touching the parser, generator,
meta files, or generate_openapi.py:

- libclang sysroot install (matches MobilityAPI vendor-drift)
- clone MobilityDB master for MEOS headers
- run.py + generate_openapi.py
- openapi-spec-validator against OpenAPI 3.1
- upload meos-openapi.json as an artefact

Catches OpenAPI 3.1 violations the moment a generator change introduces
them, instead of letting downstream consumers (MobilityAPI vendor-drift,
PyMEOS-CFFI codegen, MobilityDuck binding generator) discover them
later. Named as a 'natural follow-up' in PR #5's body.
estebanzimanyi added a commit that referenced this pull request May 20, 2026
@estebanzimanyi
ci(openapi): add openapi-validate workflow
65b79bb 
Runs the full regenerate path on every PR touching the parser, generator,
meta files, or generate_openapi.py:

- libclang sysroot install (matches MobilityAPI vendor-drift)
- clone MobilityDB master for MEOS headers
- run.py + generate_openapi.py
- openapi-spec-validator against OpenAPI 3.1
- upload meos-openapi.json as an artefact

Catches OpenAPI 3.1 violations the moment a generator change introduces
them, instead of letting downstream consumers (MobilityAPI vendor-drift,
PyMEOS-CFFI codegen, MobilityDuck binding generator) discover them
later. Named as a 'natural follow-up' in PR #5's body.
estebanzimanyi added a commit that referenced this pull request May 20, 2026
@estebanzimanyi
ci(openapi): add openapi-validate workflow
b2fd812 
Runs the full regenerate path on every PR touching the parser, generator,
meta files, or generate_openapi.py:

- libclang sysroot install (matches MobilityAPI vendor-drift)
- clone MobilityDB master for MEOS headers
- run.py + generate_openapi.py
- openapi-spec-validator against OpenAPI 3.1
- upload meos-openapi.json as an artefact

Catches OpenAPI 3.1 violations the moment a generator change introduces
them, instead of letting downstream consumers (MobilityAPI vendor-drift,
PyMEOS-CFFI codegen, MobilityDuck binding generator) discover them
later. Named as a 'natural follow-up' in PR #5's body.
estebanzimanyi added a commit that referenced this pull request May 20, 2026
@estebanzimanyi
feat: generate an OGC API – Moving Features OpenAPI projection (PR #5 …
efe2400 
…follow-up)

Adds 'generator/movfeat.py' and 'generate_movfeat_openapi.py' as a
second OpenAPI projection alongside the generic RPC-style projection
in 'generator/openapi.py'.

The MovFeat projection maps the subset of MEOS functions that have an
OGC API – Moving Features (OGC 22-003r3) analogue onto the
OGC-defined REST resource hierarchy under
'/collections/{collectionId}/items/{featureId}/…'. Each route carries
'x-meos-{function,decode,encode}' extensions so a downstream OGC
server (MobilityAPI, in this ecosystem) can dispatch each call to the
right MEOS function without re-deriving the mapping.

Reuses the _value_schema / _type_schema / _enum_schema helpers from
'generator/openapi.py' so component schemas and the MeosError
response are byte-identical across the two projections. Smoke-tested
locally on the catalog produced by 'run.py' against MobilityDB master
headers: 10 paths, 5/6 unique MEOS function dependencies present in
the catalog (temporal_as_mfjson, temporal_from_mfjson, tpoint_speed,
temporal_derivative, tpoint_cumulative_length, tpoint_azimuth).

Closes the 'OGC API – Moving Features resource projection' natural
follow-up named in PR #5's body. The MobilityAPI ingestion plan
(MobilityAPI #3, step 5) consumes this projection.
This was referenced May 21, 2026
Open
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@estebanzimanyi