VDP/vdp.v0-1.schema.json at main · ViewDescriptorProtocol/VDP · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://vdprotocol.org/schemas/vdp.v0-1.schema.json",
  "title": "View Descriptor Protocol (VDP) v0.1",
  "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.",

  "oneOf": [
    { "$ref": "#/$defs/ViewDescriptor" },
    { "$ref": "#/$defs/MultiViewDescriptor" }
  ],

  "$defs": {
    "ViewDescriptor": {
      "type": "object",
      "description": "A view descriptor identifying a root template URI and its dynamic slot assignments. Slots are recursive — each slot value is a ViewDescriptor, a DescriptorReference, or an array of either.",
      "properties": {
        "template": {
          "$ref": "#/$defs/TemplateURI"
        },
        "type": {
          "type": "string",
          "minLength": 1,
          "description": "Advisory media type (RFC 6838) of the template resource, e.g. text/x-qute. The Content-Type of the fetched template is authoritative."
        },
        "integrity": {
          "type": "string",
          "minLength": 1,
          "description": "Integrity metadata for the template resource in W3C Subresource Integrity format, e.g. sha384-<base64 digest>. A mismatch is treated as a template fetch failure."
        },
        "slots": {
          "$ref": "#/$defs/Slots"
        }
      },
      "required": ["template"],
      "additionalProperties": false
    },

    "DescriptorReference": {
      "type": "object",
      "description": "A reference to a standalone view descriptor resource, valid only as a slot value. The client fetches the URL and uses the result as the slot's descriptor. The URL may be a relative reference, resolved against the same base as the containing descriptor's template URIs.",
      "properties": {
        "descriptor": {
          "type": "string",
          "format": "uri-reference",
          "minLength": 1,
          "description": "URL of the referenced view descriptor resource."
        }
      },
      "required": ["descriptor"],
      "additionalProperties": false
    },

    "TemplateURI": {
      "type": "string",
      "format": "uri-reference",
      "minLength": 1,
      "description": "A URI identifying a template. The URI is an identifier first — which source supplies the template (app bundle, page, BFF-local store, network fetch) is deployment-specific and outside the protocol. The scheme is optional: a scheme-less identifier that does not begin with '/' (e.g. example.com/templates/card) is an opaque, host-qualified identity and is NOT resolved as an RFC 3986 relative reference (spec Section 5.4); the resolving code supplies a scheme only when it fetches over the network. Whenever a template is retrieved over the network, retrieval MUST use HTTPS (loopback addresses excepted for local development)."
    },

    "Slots": {
      "type": "object",
      "description": "A map of slot names to slot values. Each key is a named insertion point in the parent template. Each value is a SlotDescriptor (an inline ViewDescriptor or a DescriptorReference) or an array of SlotDescriptors rendered in sequence.",
      "additionalProperties": {
        "$ref": "#/$defs/SlotValue"
      }
    },

    "SlotDescriptor": {
      "description": "An inline ViewDescriptor or a DescriptorReference pointing at a standalone view descriptor resource.",
      "oneOf": [
        { "$ref": "#/$defs/ViewDescriptor" },
        { "$ref": "#/$defs/DescriptorReference" }
      ]
    },

    "SlotValue": {
      "description": "A single SlotDescriptor or an ordered array of SlotDescriptors. Arrays are rendered in sequence within the slot.",
      "oneOf": [
        { "$ref": "#/$defs/SlotDescriptor" },
        {
          "type": "array",
          "items": {
            "$ref": "#/$defs/SlotDescriptor"
          },
          "minItems": 1
        }
      ]
    },

    "MultiViewDescriptor": {
      "type": "object",
      "description": "Multiple named view descriptors for a single API response. Clients SHOULD use the 'default' view when no specific view is requested.",
      "properties": {
        "views": {
          "type": "object",
          "description": "A map of view names to ViewDescriptors.",
          "additionalProperties": {
            "$ref": "#/$defs/ViewDescriptor"
          },
          "minProperties": 1
        }
      },
      "required": ["views"],
      "additionalProperties": false
    }
  }
}