Last active
March 17, 2022 21:02
-
-
Save kevinswiber/4ee078f7bee175852587aca738377168 to your computer and use it in GitHub Desktop.
An example illustrating a use case of composition via templates.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
{ | |
"$schema": "https://json-schema.org/draft/2020-12/schema", | |
"$id": "https://example.com/page.schema.json", | |
"title": "Page", | |
"description": "A page in a catalog", | |
"type": "object", | |
"properties": { | |
"title": { | |
"description": "A descriptive title for the page", | |
"type": "string" | |
}, | |
"cursor": { | |
"description": "A unique pointer representing the page position." | |
"type": "string" | |
}, | |
"count": { | |
"description": "The number of elements represented", | |
"type": "integer" | |
}, | |
"previous": { | |
"description": "A link to the previous page", | |
"type": "string" | |
}, | |
"next": { | |
"description": "A link to the next page", | |
"type": "string" | |
}, | |
"items": { | |
"description": "Page elements", | |
"type": "array", | |
"items": { | |
"$ref": "<<<?????>>>" | |
}, | |
"minItems": 1, | |
"uniqueItems": true | |
} | |
}, | |
"required": [ "cursor", "count", "items" ] | |
} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
{ | |
"$schema": "https://json-schema.org/draft/2020-12/schema", | |
"$id": "https://example.com/product.schema.json", | |
"title": "Product", | |
"description": "A product from Acme's catalog", | |
"type": "object", | |
"properties": { | |
"productId": { | |
"description": "The unique identifier for a product", | |
"type": "integer" | |
}, | |
"productName": { | |
"description": "Name of the product", | |
"type": "string" | |
}, | |
"price": { | |
"description": "The price of the product", | |
"type": "number", | |
"exclusiveMinimum": 0 | |
}, | |
"tags": { | |
"description": "Tags for the product", | |
"type": "array", | |
"items": { | |
"type": "string" | |
}, | |
"minItems": 1, | |
"uniqueItems": true | |
} | |
}, | |
"required": [ "productId", "productName", "price" ] | |
} |
Kevin's got the right idea. The two schemas need to be in separate Schema Resources or their dynamic anchors will clash. You can always create a new Schema Resource within a single document using $id
. So all of these schemas can be bundled into components
in an OpenAPI document.
paths:
/foo:
get:
...
response:
$ref: 'schemas/foo-page.schema.json'
/bar:
get:
...
response:
$ref: 'schemas/bar-page.schema.json'
components:
schemas:
foo-page:
$id: 'schemas/foo-page.schema.json'
...
bar-page:
$id: 'schemas/bar-page.schema.json'
...
page:
$id: 'schemas/page.schema.json'
...
foo:
$id: 'schemas/foo.schema.json'
...
bar:
$id: 'schemas/bar.schema.json'
...
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
@webron I'm not qualified to answer on behalf of Jason on this subject matter, but I believe each reference would have to point to two different schemas that looks like:
I believe these gymnastics are necessary as the dynamic reference has to be resolvable within the same schema. The dynamic anchor is essentially acting as the generic type parameter.