JSON Pointer is a standardized string syntax for identifying a value within a JSON or YAML document. In OpenAPI, a pointer lets $ref locate reusable schemas and other components instead of duplicating their definitions. section 7.7.1
A pointer begins at the document root, marked by #, and follows slash-separated property names. Thus #/components/schemas/Product identifies the Product schema under components.schemas. Reusing that target keeps request and response models consistent and limits future changes to one definition. section 7.7.1 section 7.8
Listing 7.12 References to reusable schemas
...
paths:
/products:
...
post:
...
responses:
"201":
...
content:
application/json:
schema:
$ref: "#/components/schemas/Product" #1
...
/products/{productReference}:
get:
...
responses:
"200":
...
content:
application/json:
schema:
$ref: "#/components/schemas/Product" #1
...
components:
schemas:
Product: ... #1
Use the same pointer to return the Product schema from both product-creation and product-retrieval responses. section 7.7.1
JSON Pointer also supports practical API tooling and error-reporting tasks:
- Target reusable error schemas, parameters, request bodies, headers, and responses from their component locations. section 17.8
- Identify the precise request-body location of a validation problem so consumers can display actionable feedback in a user interface. section 9.8.4
- Point Spectral overrides at individual lint findings; encode path slashes as ~1, as in #/paths/~1accounts/get/parameters. section 18.9.2
