Skip to content

Commit 31c2091

Browse files
timotheeguerintimotheeguerin
committed
docs(json-schema): document Format enum members and Json.value
Documents all 18 members of the `Format` enum and the `value" property of `Json`. Also escapes the `@extension` reference in the `Json` doc comment: without backticks the doc parser reads it as a tag and silently truncates the rest of the description. Prerequisite for #1229 and #2090.
1 parent 395a298 commit 31c2091

3 files changed

Lines changed: 71 additions & 25 deletions

File tree

‎.chronus/changes/docs-json-schema-2026-8-11.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
changeKind: internal
3+
packages:
4+
- "@typespec/json-schema"
5+
---
6+
7+
Document the members of the `Format` enum and escape a code reference in the `Json` doc comment

‎packages/json-schema/lib/main.tsp‎

Lines changed: 37 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -139,29 +139,64 @@ extern dec extension(target: unknown, key: valueof string, value: (valueof unkno
139139
* Well-known JSON Schema formats.
140140
*/
141141
enum Format {
142+
/** A date and time, as defined by the `date-time` production in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). */
142143
dateTime: "date-time",
144+
145+
/** A calendar date, as defined by the `full-date` production in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). */
143146
date: "date",
147+
148+
/** A time of day, as defined by the `full-time` production in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). */
144149
time: "time",
150+
151+
/** An ISO 8601 duration such as `P3DT4H5M`, as defined by the `duration` production in [RFC 3339, appendix A](https://datatracker.ietf.org/doc/html/rfc3339#appendix-A). */
145152
duration: "duration",
153+
154+
/** An email address, as defined by the `addr-spec` production in [RFC 5322](https://datatracker.ietf.org/doc/html/rfc5322#section-3.4.1). */
146155
email: "email",
156+
157+
/** An internationalized email address, as defined by [RFC 6531](https://datatracker.ietf.org/doc/html/rfc6531). */
147158
idnEmail: "idn-email",
159+
160+
/** A host name, as defined by [RFC 1123](https://datatracker.ietf.org/doc/html/rfc1123#section-2.1). */
148161
hostname: "hostname",
162+
163+
/** An internationalized host name, as defined by [RFC 5890](https://datatracker.ietf.org/doc/html/rfc5890#section-2.3.2.3). */
149164
idnHostname: "idn-hostname",
165+
166+
/** An IPv4 address, as defined by the `dotted-quad` production in [RFC 2673](https://datatracker.ietf.org/doc/html/rfc2673#section-3.2). */
150167
ipv4: "ipv4",
168+
169+
/** An IPv6 address, as defined by [RFC 4291](https://datatracker.ietf.org/doc/html/rfc4291#section-2.2). */
151170
ipv6: "ipv6",
171+
172+
/** A URI, as defined by [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986). */
152173
uri: "uri",
174+
175+
/** A URI reference, which may be relative, as defined by [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986#section-4.1). */
153176
uriReference: "uri-reference",
177+
178+
/** An internationalized resource identifier, as defined by [RFC 3987](https://datatracker.ietf.org/doc/html/rfc3987). */
154179
iri: "iri",
180+
181+
/** An internationalized resource identifier reference, which may be relative, as defined by [RFC 3987](https://datatracker.ietf.org/doc/html/rfc3987). */
155182
iriReference: "iri-reference",
183+
184+
/** A universally unique identifier, as defined by [RFC 4122](https://datatracker.ietf.org/doc/html/rfc4122). */
156185
uuid: "uuid",
186+
187+
/** A JSON pointer, as defined by [RFC 6901](https://datatracker.ietf.org/doc/html/rfc6901). */
157188
jsonPointer: "json-pointer",
189+
190+
/** A relative JSON pointer, as defined by the [relative JSON pointer draft](https://datatracker.ietf.org/doc/html/draft-handrews-relative-json-pointer-01). */
158191
relativeJsonPointer: "relative-json-pointer",
192+
193+
/** A regular expression, as defined by [ECMA-262](https://www.ecma-international.org/publications-and-standards/standards/ecma-262/). */
159194
regex: "regex",
160195
}
161196

162197
/**
163198
* Specify that the provided template argument should be emitted as raw JSON or YAML
164-
* as opposed to a schema. Use in combination with the @extension decorator. For example,
199+
* as opposed to a schema. Use in combination with the `@extension` decorator. For example,
165200
* `@extension("x-schema", { x: "value" })` will emit a JSON schema value for `x-schema`,
166201
* whereas `@extension("x-schema", Json<{x: "value"}>)` will emit the raw JSON code
167202
* `{x: "value"}`.
@@ -170,6 +205,7 @@ enum Format {
170205
*/
171206
@Private.validatesRawJson(Data)
172207
model Json<Data> {
208+
/** The value to emit as raw JSON or YAML. */
173209
value: Data;
174210
}
175211

‎website/src/content/docs/docs/emitters/json-schema/reference/data-types.md‎

Lines changed: 27 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,10 @@ llmstxt: true
99
### `Json` {#TypeSpec.JsonSchema.Json}
1010

1111
Specify that the provided template argument should be emitted as raw JSON or YAML
12-
as opposed to a schema. Use in combination with the
12+
as opposed to a schema. Use in combination with the `@extension` decorator. For example,
13+
`@extension("x-schema", { x: "value" })` will emit a JSON schema value for `x-schema`,
14+
whereas `@extension("x-schema", Json<{x: "value"}>)` will emit the raw JSON code
15+
`{x: "value"}`.
1316

1417
```typespec
1518
model TypeSpec.JsonSchema.Json<Data>
@@ -23,9 +26,9 @@ model TypeSpec.JsonSchema.Json<Data>
2326

2427
#### Properties
2528

26-
| Name | Type | Description |
27-
| ----- | ------ | ----------- |
28-
| value | `Data` | |
29+
| Name | Type | Description |
30+
| ----- | ------ | -------------------------------------- |
31+
| value | `Data` | The value to emit as raw JSON or YAML. |
2932

3033
### `Format` {#TypeSpec.JsonSchema.Format}
3134

@@ -35,23 +38,23 @@ Well-known JSON Schema formats.
3538
enum TypeSpec.JsonSchema.Format
3639
```
3740

38-
| Name | Value | Description |
39-
| ------------------- | ------------------------- | ----------- |
40-
| dateTime | `"date-time"` | |
41-
| date | `"date"` | |
42-
| time | `"time"` | |
43-
| duration | `"duration"` | |
44-
| email | `"email"` | |
45-
| idnEmail | `"idn-email"` | |
46-
| hostname | `"hostname"` | |
47-
| idnHostname | `"idn-hostname"` | |
48-
| ipv4 | `"ipv4"` | |
49-
| ipv6 | `"ipv6"` | |
50-
| uri | `"uri"` | |
51-
| uriReference | `"uri-reference"` | |
52-
| iri | `"iri"` | |
53-
| iriReference | `"iri-reference"` | |
54-
| uuid | `"uuid"` | |
55-
| jsonPointer | `"json-pointer"` | |
56-
| relativeJsonPointer | `"relative-json-pointer"` | |
57-
| regex | `"regex"` | |
41+
| Name | Value | Description |
42+
| ------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
43+
| dateTime | `"date-time"` | A date and time, as defined by the `date-time` production in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). |
44+
| date | `"date"` | A calendar date, as defined by the `full-date` production in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). |
45+
| time | `"time"` | A time of day, as defined by the `full-time` production in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). |
46+
| duration | `"duration"` | An ISO 8601 duration such as `P3DT4H5M`, as defined by the `duration` production in [RFC 3339, appendix A](https://datatracker.ietf.org/doc/html/rfc3339#appendix-A). |
47+
| email | `"email"` | An email address, as defined by the `addr-spec` production in [RFC 5322](https://datatracker.ietf.org/doc/html/rfc5322#section-3.4.1). |
48+
| idnEmail | `"idn-email"` | An internationalized email address, as defined by [RFC 6531](https://datatracker.ietf.org/doc/html/rfc6531). |
49+
| hostname | `"hostname"` | A host name, as defined by [RFC 1123](https://datatracker.ietf.org/doc/html/rfc1123#section-2.1). |
50+
| idnHostname | `"idn-hostname"` | An internationalized host name, as defined by [RFC 5890](https://datatracker.ietf.org/doc/html/rfc5890#section-2.3.2.3). |
51+
| ipv4 | `"ipv4"` | An IPv4 address, as defined by the `dotted-quad` production in [RFC 2673](https://datatracker.ietf.org/doc/html/rfc2673#section-3.2). |
52+
| ipv6 | `"ipv6"` | An IPv6 address, as defined by [RFC 4291](https://datatracker.ietf.org/doc/html/rfc4291#section-2.2). |
53+
| uri | `"uri"` | A URI, as defined by [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986). |
54+
| uriReference | `"uri-reference"` | A URI reference, which may be relative, as defined by [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986#section-4.1). |
55+
| iri | `"iri"` | An internationalized resource identifier, as defined by [RFC 3987](https://datatracker.ietf.org/doc/html/rfc3987). |
56+
| iriReference | `"iri-reference"` | An internationalized resource identifier reference, which may be relative, as defined by [RFC 3987](https://datatracker.ietf.org/doc/html/rfc3987). |
57+
| uuid | `"uuid"` | A universally unique identifier, as defined by [RFC 4122](https://datatracker.ietf.org/doc/html/rfc4122). |
58+
| jsonPointer | `"json-pointer"` | A JSON pointer, as defined by [RFC 6901](https://datatracker.ietf.org/doc/html/rfc6901). |
59+
| relativeJsonPointer | `"relative-json-pointer"` | A relative JSON pointer, as defined by the [relative JSON pointer draft](https://datatracker.ietf.org/doc/html/draft-handrews-relative-json-pointer-01). |
60+
| regex | `"regex"` | A regular expression, as defined by [ECMA-262](https://www.ecma-international.org/publications-and-standards/standards/ecma-262/). |

0 commit comments

Comments
 (0)