-
-
Save kevinswiber/4ee078f7bee175852587aca738377168 to your computer and use it in GitHub Desktop.
| { | |
| "$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" ] | |
| } |
| { | |
| "$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" ] | |
| } |
@jdesrosiers thanks for this. Sorry for not jumping into all the references, but I'm curious, can you have multiple such dynamic references pointing to different schemas within the same top-level schema?
Think about it from the OpenAPI spec perspective. The Page schema is supposed to represent a paged result of list call, and say you have (overly simplified definition):
/foo:
get:
...
response:
$ref: '#/defs/Page<foo>'
/bar:
get:
...
response:
$ref: '#/defs/Page<bar>'
is this something you can represent this way? From your example, I get how to define one of those, but not two or more.
@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:
{
"$id": "https://example.com/foo-page.schema.json",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$ref": "page.schema.json",
"$defs": {
"page-content": {
"$dynamicAnchor": "page-content",
"$ref": "foo.schema.json"
}
}
}{
"$id": "https://example.com/bar-page.schema.json",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$ref": "page.schema.json",
"$defs": {
"page-content": {
"$dynamicAnchor": "page-content",
"$ref": "bar.schema.json"
}
}
}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.
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'
...
This can be solved with dynamic references. The
$dynamicRefkeyword indicates a named slot that can be overridden by a schema that references this schema.{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://example.com/page.schema.json", "type": "object", "properties": { "title": { "type": "string" }, "cursor": { "type": "string" }, "count": { "type": "integer" }, "previous": { "type": "string" }, "next": { "type": "string" }, "items": { "type": "array", "items": { "$dynamicRef": "#page-content" }, "minItems": 1, "uniqueItems": true } }, "required": ["cursor", "count", "items"], "$defs": { "default-page-content": { "$dynamicAnchor": "page-content" } } }This schema has a slot named
page-contentthat can be filled. It's required that the dynamic reference is resolvable within the same schema document which is why we need to include/$defs/default-page-content. In this case, if nopage-contentdynamic anchor is found, then the items are unconstrained. In the next release of JSON Schema, we won't need to include this default schema.Here's how you would compose these schemas to get something like a
Page<Product>schema.{ "$id": "https://example.com/project-page.schema.json", "$schema": "https://json-schema.org/draft/2020-12/schema", "$ref": "page.schema.json", "$defs": { "page-content": { "$dynamicAnchor": "page-content", "$ref": "product.schema.json" } } }The dynamic anchor indicates that any dynamic references to
page-contentshould resolve to this schema. So, when the"$ref": "page.schema.json"reference is followed, it's dynamic reference topage-contentwill resolve to the dynamic anchor in this schema. You can see this in action at https://json-schema.hyperjump.io.