@ -6,10 +6,16 @@
* `anchor`: optional HTML element id for the table
* `properties`: dictionary of the properties to list, each given as:
* `properties`: optional dictionary of the properties to list, each given as:
`property_name` : `property_data`
* `required`: array containing the names of required properties.
* `additionalProperties`: optional dictionary for properties with undefined
names, in the same format as `property_data`
* `patternProperties`: optional dictionary for properties with names adhering
to a regex pattern, in the same format as `property_data`
* `required`: optional array containing the names of required properties.
In some cases (such as response body specifications) this isn't used, and
instead properties have a `required` boolean attribute. We support this too.
@ -34,24 +40,6 @@
{{ range $property_name, $property := $properties }}
{{ $property := partial "json-schema/resolve-allof" $property }}
{{ $type := $property.type }}
{{ if or (eq $property.type "object") (and $property.oneOf (reflect.IsSlice .oneOf)) }}
{{ $type = partial "type-or-title" $property }}
{{ end }}
{{/*
If the property is an array, indicate this with square brackets,
like `[type]`.
*/}}
{{ if eq $property.type "array"}}
{{ $items := $property.items }}
{{ if $property.items }}
{{ $items = partial "json-schema/resolve-allof" $property.items }}
{{ end }}
{{ $inner_type := partial "type-or-title" $items }}
{{ $type = delimit (slice "[" $inner_type "]") "" }}
{{ end }}
{{/*
Handle two ways of indicating "required", one for simple parameters,
@ -61,25 +49,93 @@
< tr >
< td > < code > {{ $property_name }}< / code > < / td >
< td > < code > {{ $type }}< / code > < / td >
< td >
{{ if $required }}< strong > Required: < / strong > {{end -}}
{{ $property.description | markdownify -}}
{{ if $property.enum }}< p > One of: < code > [{{ delimit $property.enum ", " }}]< / code > .< / p > {{ end -}}
{{ if (index $property "x-addedInMatrixVersion") }}{{ partial "added-in" (dict "v" (index $property "x-addedInMatrixVersion")) }}{{ end -}}
{{ if (index $property "x-changedInMatrixVersion") }}{{ partial "changed-in" (dict "changes_dict" (index $property "x-changedInMatrixVersion")) }}{{ end -}}
< / td >
< td > < code > {{ partial "partials/property-type" $property }}< / code > < / td >
< td > {{ partial "partials/property-description" (dict "property" $property "required" $required) }}< / td >
< / tr >
{{ end }}
< / table >
{{ else if (or .additionalProperties .patternProperties) }}
< table { { if . anchor } } id = "{{ .anchor }}" { { end } } class = "object-table" >
{{ with $title }}
< caption > {{ . }}< / caption >
{{ end }}
< thead >
< th class = "col-type" > Type< / th >
< th class = "col-description" > Description< / th >
< / thead >
{{ $property := partial "json-schema/resolve-allof" . }}
< tr >
< td > < code > {{ partial "partials/property-type" $property }}< / code > < / td >
< td > {{ partial "partials/property-description" (dict "property" $property) }}< / td >
< / tr >
< / table >
{{ end }}
{{/*
Computes the type to display for a property, given:
* `type`: string or array of strings for the type(s) of the property
* `title`: optional string for the title of the property
* `oneOf`: optional array of dictionaries describing the different formats
that the property can have
* `additionalProperties`: optional dictionary for properties with undefined
names
* `patternProperties`: optional dictionary for properties with names
adhering to a regex pattern
* `items`: if the type is an array, array of dictionaries describing the
format of the array's items
*/}}
{{ define "partials/property-type" }}
{{ $type := .type }}
{{ if or (eq .type "object") (and .oneOf (reflect.IsSlice .oneOf)) }}
{{ $type = partial "type-or-title" . }}
{{ end }}
{{/*
If the property is an array, indicate this with square brackets,
like `[type]`.
*/}}
{{ if eq .type "array"}}
{{ $items := .items }}
{{ if .items }}
{{ $items = partial "json-schema/resolve-allof" .items }}
{{ end }}
{{ $inner_type := partial "type-or-title" $items }}
{{ $type = delimit (slice "[" $inner_type "]") "" }}
{{ end }}
{{ return $type }}
{{ end }}
{{/*
Picks either the `title` of a property, or the `type`, to turn into the rendered type field.
Also handles `additionalProperties`, if no `title` is present.
Computes the type to display for a property's schema, given:
* `type`: string or array of strings for the type(s) of the property
* `title`: optional string for the title of the property
* `oneOf`: optional array of dictionaries describing the different formats
that the property can have
* `additionalProperties`: optional dictionary for properties with undefined
names
* `patternProperties`: optional dictionary for properties with names
adhering to a regex pattern
The title has a higher priority than anything else.
*/}}
{{ define "partials/type-or-title" }}
{{ $type := "" }}
@ -94,7 +150,24 @@
If the property uses `additionalProperties` to describe its
internal structure, handle this with a bit of recursion
*/}}
{{ $type = delimit (slice "{string: " (partial "type-or-title" .additionalProperties) "}" ) "" }}
{{ $additionalProperties := partial "json-schema/resolve-allof" .additionalProperties }}
{{ $type = delimit (slice "{string: " (partial "property-type" $additionalProperties) "}" ) "" }}
{{ else if reflect.IsMap .patternProperties }}
{{/*
If the property uses `patternProperties` to describe its
internal structure, handle this with a bit of recursion.
Note that we ignore the pattern as the current definitions
always have a single pattern, but we might need to handle
them later to differentiate schemas according to patterns.
*/}}
{{ $types := slice }}
{{ range $pattern, $schema := .patternProperties}}
{{ $schema = partial "json-schema/resolve-allof" $schema }}
{{ $types = $types | append (partial "property-type" $schema) }}
{{ end }}
{{ $type = delimit (slice "{string: " (delimit $types "|") "}" ) "" }}
{{ else if reflect.IsSlice .type }}
{{/* It's legal to specify an array of types. Join them together in that case */}}
@ -123,3 +196,28 @@
{{ end }}
{{ return $type }}
{{ end }}
{{/*
Computes the description to display for a property, given:
* `required`: boolean indicating whether this property is required.
* `property`: dictionary describing the property's data, with these fields:
* `description`: string describing the property
* `enum`: optional array indicating the accepted values for the property
* `x-addedInMatrixVersion`: optional string indicating in which Matrix
spec version this property was added.
* `x-changedInMatrixVersion`: optional string indicating in which Matrix
spec version this property was last changed.
*/}}
{{ define "partials/property-description" }}
{{ if .required }}< strong > Required: < / strong > {{end -}}
{{ .property.description | markdownify -}}
{{ if .property.enum }}< p > One of: < code > [{{ delimit .property.enum ", " }}]< / code > .< / p > {{ end -}}
{{ if (index .property "x-addedInMatrixVersion") }}{{ partial "added-in" (dict "v" (index .property "x-addedInMatrixVersion")) }}{{ end -}}
{{ if (index .property "x-changedInMatrixVersion") }}{{ partial "changed-in" (dict "changes_dict" (index .property "x-changedInMatrixVersion")) }}{{ end -}}
{{ end }}
Kévin Commaille
1 year ago
committed by