Reference component schemas by JSON Pointer in the published OpenAPI documents

[tkanov]

The published OpenAPI documents reference their component schemas by JSON Schema $id rather than by JSON Pointer, so OpenAPI tooling cannot resolve them. openapi-generator validate reports 280 errors on openapi.json, and generate -g python exits 0 while producing no model classes at all. Reported as Systems-Modeling/SysML-v2-Release#115.

In openapi.json and openapi-x.json, this rewrites the 367 "$ref": "20250201/<Name>" to "#/components/schemas/<Name>" and removes the 395 schema-level $id keys. The 2 $id occurrences that are data rather than keywords are preserved. Validation is then clean and codegen produces 557 models. Dereferencing both documents before and after gives the same effective schema throughout, so only the reference form changes.

Three things for you to decide.

1. The removed $id values came from PR ST5AS-226 Align JSON Schema and OpenAPI spec with OMG URI standard #93 (ST5AS-226) for OMG URI identity, and for most schemas are not recoverable from the patched document. I can instead keep $id on schemas that are never a reference target.
2. These artifacts look generated outside the repository and regenerated alongside conf/json/schema on each baseline update, for example PR ST5AS-246 update to 2025-02 metamodel baseline #127, so the generator needs the same change or this reverts.
3. This does not fix Release#115 as the reporter saw it. /docs serves openapi-sans-schemas.json, whose empty components.schemas produces the 62 errors quoted in that issue. I left it alone because I cannot test how RapiDoc resolves references across files. Point index.html at the full document, or make the reduced one self-contained?

conf/json/schema/** is untouched, since its $id based references are valid JSON Schema and FlatSchemaDao keys the /schemas endpoint on $id. Issues #106 and #108 are separate.

[tkanov]

Hey @seidewitz, didn't know about the policy - should this be closed as well? Thanks!