$ref with escaped slash (~1) causes "Reference not found" error

[chrg1001]

Description

It seems that Reference not found errors occur when an escaped slash (~1) is present in a $ref string.

Error: Reference not found: #/paths/~1api~1users/get/responses/200/content/application~1json/schema

Reproducible example or configuration

https://stackblitz.com/edit/hey-api-client-fetch-example-hcuescjt?file=docs%2Fschema.json

OpenAPI specification (optional)

{
  "openapi": "3.0.0",
  "info": {
    "title": "Sample API",
    "version": "1.0.0"
  },
  "paths": {
    "/api/users": {
      "get": {
        "summary": "Get users",
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "integer"
                      },
                      "name": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Post user",
        "responses": {
          "200": {
            "description": "successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/paths/~1api~1users/get/responses/200/content/application~1json/schema"
                }
              }
            }
          }
        }
      }
    }
  }
}

System information (optional)

No response

[bolt-new-by-stackblitz]

Start a new pull request in StackBlitz Codeflow.

• hey-api-client-fetch-example-hcuescjt (Open reproduction)

[chrg1001]

Ah, so the problem is here.

openapi-ts/packages/openapi-ts/src/utils/ref.ts

Lines 20 to 42 in fcb77c9

	const refToParts = ($ref: string): string[] => {
	// Remove the leading `#` and split by `/` to traverse the object
	const parts = $ref.replace(/^#\//, '').split('/');
	return parts;
	};
	export const resolveRef = <T>({
	$ref,
	spec,
	}: {
	$ref: string;
	spec: Record<string, any>;
	}): T => {
	// refs using unicode characters become encoded, didn't investigate why
	// but the suspicion is this comes from `@hey-api/json-schema-ref-parser`
	const parts = refToParts(decodeURI($ref));
	let current = spec;
	for (const part of parts) {
	const p = part as keyof typeof current;
	if (current[p] === undefined) {
	throw new Error(`Reference not found: ${$ref}`);

What are the following possible modifications?

  const parts = $ref.replace(/^#\//, '').split('/').map(part => {
    // Decode JSON Pointer escape sequences: ~1 -> /, ~0 -> ~
    return part.replace(/~1/g, '/').replace(/~0/g, '~');
  });

json-schema-ref-parser's implements is

https://github.com/APIDevTools/json-schema-ref-parser/blob/9376c243790f9e7e1dbd8c3bf85c5ff45e0b6dba/lib/util/url.ts#L479

[mrlubos]

@chrg1001 does your spec contain references to other operation responses like this? Are you able to share your full spec with me? (over email is fine) Is it automatically generated by a tool? Which tool?

[chrg1001]

@mrlubos

I found this bug when I tried to parse this API specification of the API provided by the labor management tool.

(Since the tool is used in Japan, the comments in the specification are in Japanese.)

I do not know what tool this specification was generated with, as it is provided by the vendor.

https://github.com/freee/freee-api-schema/blob/master/hr/open-api-3/api-schema.json

Error occurs at https://github.com/freee/freee-api-schema/blob/3824573ed643c081c49328b372d7a80b22404f32/hr/open-api-3/api-schema.json#L6468

[mrlubos]

Thank you! Last question, did you use an older version and this worked or are you a new user?

[chrg1001]

I have been using hey-api for some time in another project, but this is the first time I have used the above OpenAPI file.

[chrg1001]

@mrlubos

I am curious about one thing and would like to ask.

There is the following implementation elsewhere, but what is the use of this function (resolveRef) vs.

openapi-ts/packages/openapi-ts/src/openApi/common/parser/getRef.ts

Line 22 in acac297

path.replace(ESCAPED_REF_SLASH, '/').replace(ESCAPED_REF_TILDE, '~'),

[mrlubos]

Everything in common is legacy parser related. This folder will be removed in v1.

The issue isn't even with resolving the references, that's a quick fix. It's the internal structure not mapping 1:1 with OpenAPI that's the challenge to resolve.

[carson2222]

Hey @chrg1001 thanks for your effort! I fixed the issue in this PR hey-api/json-schema-ref-parser#11
It will be soon available