Resolve the original two-hop OpenAPI fixture using the current document URL at each hop. The native parser, retrieved schema, fragment existence, and API endpoint remain separate checks.
Start with three documents and one operation
The entry location is https://example.invalid/repo/docs/openapi.yaml. Its metadata names Practice Item API, version v1. It describes GET /items with a 200 response containing an application/json schema reference to ./schemas/item.yaml.
The API server is separately declared as https://api.example.invalid/v1. These addresses are illustrative, not sites to visit. The server value describes the API connection; it is not the base for these schema-file references. OpenAPI 3.0.4 specifies that relative $ref values use the current document URL as their base. See the versioned reference rule.
Plan the other two documents like this:
Document under docs/ |
content |
|---|---|
schemas/item.yaml |
An object schema requiring property code; that property references ../common.yaml#/components/schemas/Code |
common.yaml |
components.schemas.Code, a string schema with enum values A and B |
This supplies an expected target shape: an item object with a required code constrained by that string enum. It does not prove native parsing, bundling, or rendered schema compatibility. Those require complete files and the actual pinned tools.
Change the base when you follow the first reference
The first reference belongs to openapi.yaml. Resolve ./schemas/item.yaml relative to its directory. The expected document is https://example.invalid/repo/docs/schemas/item.yaml.
The second reference belongs to that item document. Resolve ../common.yaml from docs/schemas/, which produces https://example.invalid/repo/docs/common.yaml. Then resolve the fragment /components/schemas/Code inside that document. Swagger's reference syntax guide explains document references and fragment targets.
| Hop | Referring document | Reference | Expected target |
|---|---|---|---|
| 1 | docs/openapi.yaml |
./schemas/item.yaml |
Whole docs/schemas/item.yaml object schema |
| 2 | docs/schemas/item.yaml |
../common.yaml#/components/schemas/Code |
Code schema inside docs/common.yaml |
If you reuse the entry document as the second hop's base, you would incorrectly arrive at repo/common.yaml. If you use the API server, you would search an unrelated API location. Neither is the authored target.
Prepare a ledger with the full referring URI, reference string, resolved document URI, fragment, expected shape, retrieval status, and actual parser status. A correct-looking filename is only an expectation until the native resolver retrieves and inspects the intended document.
Separate a missing file from a missing fragment
Use two independent negative cases. In one, docs/common.yaml is unavailable. In the other, that document is available but lacks components.schemas.Code. The first is a document-retrieval failure; the second is a target-resolution failure inside a retrieved document.
Hold either case instead of silently using an older schema or inventing a fallback Code definition. Record which stage failed and keep the displayed result unapproved. If the files change, reopen the relevant hop and compare the actual schema identity with the current source revision.
Do not assume an inline object retains the configured URL
Swagger UI's configuration documentation says that supplying spec causes url to be ignored. Passing both therefore does not establish that url supplies the relative-reference base. Confirm the actual pinned resolver's base contract, or prepare and inspect a bundle whose internal references are resolved appropriately. Until then, mark the inline object's relative base unresolved. Swagger UI's configuration reference documents this precedence.
A 2021 project issue records a relative-base error with an inline definition in Swagger UI 3.50.0 and Swagger 2.0. It is historical troubleshooting context, not a current reproduction of this OpenAPI 3.0.4 fixture. Keep actual diagnostics blank until a native test produces them.
Prepare a documentation-only view separately
For a later Swagger UI view, specify supportedSubmitMethods: [] to disable Try it out. This does not remove operations from the display. Review validator configuration against the actual version as a separate decision; disabling submissions is not proof that documentation loading or other network activity stops. The UI configuration guide describes these settings.
Try the worked example
Resolve the default chain for docs/common.yaml. Change the second reference to ./common.yaml to see docs/schemas/common.yaml instead. That change demonstrates why the second hop needs the item document’s base. Keep retrieval and fragment inspection in separate native records. The API server URL is not the reference-file base.
This computes URL locations only, not YAML parsing, schema retrieval, fragment validation, Swagger UI rendering, or deployment.
Recreate this example
Build one complete self-contained HTML page for this task: resolve the original split OpenAPI reference locations without fetching documents.
Use these exact original practice data and worked expectations: Entry: https://example.invalid/repo/docs/openapi.yaml. First reference: ./schemas/item.yaml. Nested reference: ../common.yaml#/components/schemas/Code. Expected hop 1: https://example.invalid/repo/docs/schemas/item.yaml. Expected hop 2 document: https://example.invalid/repo/docs/common.yaml; fragment: /components/schemas/Code. The API server https://api.example.invalid/v1 is not the schema base.
Implement the following useful local interactions: Entry URL and both ref fields, Resolve. Use URL resolution from entry to item then from item to common. Display document URI and fragment separately. Validate http/https and same-origin local-document exercise; never fetch or claim fragment existence. Blank reference held. Preserve the supplied source text and distinguish an uncomputed state, a successful local result, and an invalid or incomplete input. Update output only from the current input snapshot. An input edit must retire stale feedback until the reader runs the relevant action again. Do not silently invent missing values or replace a failing case with a success.
Design the page as a compact source-and-result developer workbench with readable code, labeled inputs, and a separate explanation area. Put a compact task heading, actual sample data, the main result, and usable controls early enough to be useful on a narrow screen. Use readable text of at least 16px, generous paragraph spacing, strong contrast, native labels, accessible buttons, and visible keyboard focus. Stack long records at 360px and wrap code without page-level horizontal overflow.
Use type=button and explicit querySelector-based click handlers rather than relying on form submission. If Enter is useful, handle it only on the relevant input and ignore isComposing. Keep effects within this open page; no remote dependencies, network calls, persistence, fake downloads, or automated sending. This computes URL locations only, not YAML parsing, schema retrieval, fragment validation, Swagger UI rendering, or deployment. Place worked explanations beside their data and identify teacher or synthetic examples clearly. Output only the complete HTML document, with inline styles and script and LF line endings.
Review the nested reference URL resolver in NOS
Compare both resolved locations with the actual parser and hosted file inventory. Use the reference map in NOS to review why the second hop reaches docs/common.yaml rather than repo/common.yaml, and revise eligible static schema-loading instructions in visual editing mode before changing the hosted bundle.