Skip to content

Commit 19f45c0

Browse files
jnbdzjnbdz
committed
Publish the JSON Schemas at their canonical $id URLs.
Copy vdp.v0-1.schema.json and vdp-discovery.v0-1.schema.json from the canonical VDP repo into docs/schemas/ so they are served at https://vdprotocol.org/schemas/, making the $id URLs resolvable and external $ref references to the schema definitions work. Link the published URLs from the schema page. The copies must be kept in sync with the VDP repo whenever a schema changes.
1 parent d2a5a20 commit 19f45c0

3 files changed

Lines changed: 129 additions & 3 deletions

File tree

‎docs/schema.md‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,12 @@
22

33
The VDP JSON Schemas define the structure of view descriptor documents and the discovery document. Both use [JSON Schema draft-07](https://json-schema.org/specification-links#draft-7).
44

5-
**Current versions:**
5+
**Current versions**, published at their canonical `$id` URLs:
66

7-
- `vdp.v0-1.schema.json` — validates standalone view descriptors and multi-view descriptors
8-
- `vdp-discovery.v0-1.schema.json` — validates the discovery document served at `/.well-known/vdp`
7+
- [`vdp.v0-1.schema.json`](https://vdprotocol.org/schemas/vdp.v0-1.schema.json) — validates standalone view descriptors and multi-view descriptors
8+
- [`vdp-discovery.v0-1.schema.json`](https://vdprotocol.org/schemas/vdp-discovery.v0-1.schema.json) — validates the discovery document served at `/.well-known/vdp`
9+
10+
Because the schemas are hosted at their `$id` URLs, they can be referenced directly from other schemas and validators.
911

1012
## View Descriptor Schema
1113

‎docs/schemas/vdp-discovery.v0-1.schema.json‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
{
2+
"$schema": "http://json-schema.org/draft-07/schema#",
3+
"$id": "https://vdprotocol.org/schemas/vdp-discovery.v0-1.schema.json",
4+
"title": "View Descriptor Protocol (VDP) v0.1 Discovery Document",
5+
"description": "Schema for the VDP discovery document served at /.well-known/vdp as application/vdp-discovery+json (spec Section 13.2). Unrecognized members are permitted everywhere per the discovery extensibility clause: clients MUST ignore members they do not recognize.",
6+
7+
"type": "object",
8+
"properties": {
9+
"version": {
10+
"type": "string",
11+
"description": "The VDP protocol version supported by the API (e.g. \"0.1\"). Matches the value advertised by the VDP-Version header.",
12+
"minLength": 1
13+
},
14+
"endpoints": {
15+
"type": "object",
16+
"description": "Maps API paths to their view descriptor resources. Keys are absolute paths relative to the origin serving the discovery document, and MAY be RFC 6570 Level 1 URI Templates (e.g. /api/products/{id}).",
17+
"propertyNames": {
18+
"pattern": "^/"
19+
},
20+
"additionalProperties": {
21+
"$ref": "#/$defs/EndpointEntry"
22+
}
23+
},
24+
"trustedTemplateUrls": {
25+
"type": "array",
26+
"description": "Template URL allowlist (spec Section 10). Each entry is a URL prefix; entries SHOULD end with a trailing slash.",
27+
"items": {
28+
"type": "string",
29+
"format": "uri",
30+
"minLength": 1
31+
}
32+
}
33+
},
34+
"required": ["version"],
35+
36+
"$defs": {
37+
"EndpointEntry": {
38+
"type": "object",
39+
"description": "Discovery metadata for one API endpoint. Additional members are permitted for extensibility.",
40+
"properties": {
41+
"descriptor": {
42+
"type": "string",
43+
"format": "uri-reference",
44+
"description": "URL of the endpoint's view descriptor resource. MAY be a relative reference, resolved against the discovery document URL per RFC 3986.",
45+
"minLength": 1
46+
}
47+
},
48+
"required": ["descriptor"]
49+
}
50+
}
51+
}

‎docs/schemas/vdp.v0-1.schema.json‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
{
2+
"$schema": "http://json-schema.org/draft-07/schema#",
3+
"$id": "https://vdprotocol.org/schemas/vdp.v0-1.schema.json",
4+
"title": "View Descriptor Protocol (VDP) v0.1",
5+
"description": "Schema for VDP view descriptor documents. Validates standalone ViewDescriptor and MultiViewDescriptor payloads. Definitions in $defs can be referenced by other schemas for inline body transport (_view / _views). The discovery document served at /.well-known/vdp has its own schema: vdp-discovery.v0-1.schema.json.",
6+
7+
"oneOf": [
8+
{ "$ref": "#/$defs/ViewDescriptor" },
9+
{ "$ref": "#/$defs/MultiViewDescriptor" }
10+
],
11+
12+
"$defs": {
13+
"ViewDescriptor": {
14+
"type": "object",
15+
"description": "A view descriptor identifying a root template URL and its dynamic slot assignments. Slots are recursive — each slot value is itself a ViewDescriptor or an array of ViewDescriptors.",
16+
"properties": {
17+
"template": {
18+
"$ref": "#/$defs/TemplateURL"
19+
},
20+
"slots": {
21+
"$ref": "#/$defs/Slots"
22+
}
23+
},
24+
"required": ["template"],
25+
"additionalProperties": false
26+
},
27+
28+
"TemplateURL": {
29+
"type": "string",
30+
"format": "uri",
31+
"description": "A URL identifying a template resource. MUST use HTTPS (loopback addresses excepted for local development)."
32+
},
33+
34+
"Slots": {
35+
"type": "object",
36+
"description": "A map of slot names to slot values. Each key is a named insertion point in the parent template. Each value is a ViewDescriptor (single template) or an array of ViewDescriptors (multiple templates rendered in sequence).",
37+
"additionalProperties": {
38+
"$ref": "#/$defs/SlotValue"
39+
}
40+
},
41+
42+
"SlotValue": {
43+
"description": "A single ViewDescriptor or an ordered array of ViewDescriptors. Arrays are rendered in sequence within the slot.",
44+
"oneOf": [
45+
{ "$ref": "#/$defs/ViewDescriptor" },
46+
{
47+
"type": "array",
48+
"items": {
49+
"$ref": "#/$defs/ViewDescriptor"
50+
},
51+
"minItems": 1
52+
}
53+
]
54+
},
55+
56+
"MultiViewDescriptor": {
57+
"type": "object",
58+
"description": "Multiple named view descriptors for a single API response. Clients SHOULD use the 'default' view when no specific view is requested.",
59+
"properties": {
60+
"views": {
61+
"type": "object",
62+
"description": "A map of view names to ViewDescriptors.",
63+
"additionalProperties": {
64+
"$ref": "#/$defs/ViewDescriptor"
65+
},
66+
"minProperties": 1
67+
}
68+
},
69+
"required": ["views"],
70+
"additionalProperties": false
71+
}
72+
}
73+
}

0 commit comments

Comments
 (0)