Skip to content
Sarj Repo Standards
rest/source/nonhermetic-ref

Local reference resolution

References resolve only from supplied local contract bytes.

error

Examples

FlaggedFails
{
  "documents": {
    "openapi.json": {
      "components": {
        "schemas": {
          "Widget": {
            "$ref": "https://example.invalid/schema.json"
          }
        }
      },
      "info": {
        "title": "Fixture",
        "version": "1"
      },
      "openapi": "3.1.2",
      "paths": {
        "/widgets": {
          "get": {
            "responses": {
              "200": {
                "description": "ok"
              }
            }
          }
        }
      }
    }
  },
  "entrypoint": "openapi.json"
}
PassesClean
{
  "documents": {
    "openapi.json": {
      "components": {
        "schemas": {
          "Widget": {
            "$ref": "./schemas.json#/$defs/Widget"
          }
        }
      },
      "info": {
        "title": "Fixture",
        "version": "1"
      },
      "openapi": "3.1.2",
      "paths": {
        "/widgets": {
          "get": {
            "responses": {
              "200": {
                "description": "ok"
              }
            }
          }
        }
      }
    },
    "schemas.json": {
      "$defs": {
        "Widget": {
          "type": "object"
        }
      }
    }
  },
  "entrypoint": "openapi.json"
}

Why it matters

Remote, escaping, missing, and broken references make analysis non-reproducible or incomplete.

How detection works

A $ref is not a string or does not resolve inside the supplied document set.

What is inspected

  • parsed $ref keys and the complete supplied document set

Limits

  • validating referenced schemas
  • fetching remote resources
  • Only parsed $ref keys are examined; examples, defaults, and extension data are ignored.
  • No reference is fetched, and only explicitly supplied local documents count.

How to fix it

Make the reference resolve inside the bounded contract graph.

  1. Use a relative local $ref.
  2. Supply the exact tracked target document and point to an existing object.

Verify

  • Run repo-lint rest check again against the same tracked contract and semantics.