You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: _docs/schema/schemagen/schema-generation.md
+99-24Lines changed: 99 additions & 24 deletions
Original file line number
Diff line number
Diff line change
@@ -36,36 +36,37 @@ The above will give you a basic schema that will include the `type` keyword, and
36
36
- string properties may have length requirements
37
37
- numeric properties may have value range requirements
38
38
39
-
All of these and more are supplied via a set of attributes that can be applied to properties. The following attributes are included in this package:
39
+
All of these and more are supplied via a set of attributes that can be applied to properties, and some can be applied to to types. The following attributes are included in this package:
40
40
41
41
- Numeric values
42
-
-`Minimum`
43
-
-`ExclusiveMinimum`
44
-
-`Maximum`
45
-
-`ExclusiveMaximum`
46
-
-`MultipleOf`
42
+
-`Minimum`
43
+
-`ExclusiveMinimum`
44
+
-`Maximum`
45
+
-`ExclusiveMaximum`
46
+
-`MultipleOf`
47
47
- Strings
48
-
-`MinLength`
49
-
-`MaxLength`
50
-
-`Pattern`
48
+
-`MinLength`
49
+
-`MaxLength`
50
+
-`Pattern`
51
51
- Arrays
52
-
-`MinItems`
53
-
-`MaxItems`
54
-
-`UniqueItems`
52
+
-`MinItems`
53
+
-`MaxItems`
54
+
-`UniqueItems`
55
55
- All
56
-
-`Required` & `Nullable` (see below)
57
-
-`Obsolete`\* (translates to `deprecated`)
58
-
-`JsonExclude`\*\*
59
-
-`Title`
60
-
-`Description`
61
-
-`Const`\*\*\*
62
-
-`Default`\*\*\*
63
-
-`ReadOnly`
64
-
-`WriteOnly`
56
+
-`Id`
57
+
-`Required` & `Nullable` (see below)
58
+
-`Obsolete`\* (translates to `deprecated`)
59
+
-`JsonExclude`\*\*
60
+
-`Title`
61
+
-`Description`
62
+
-`Const`\*\*\*
63
+
-`Default`\*\*\*
64
+
-`ReadOnly`
65
+
-`WriteOnly`
65
66
- Conditional (see [Conditionals](./conditional-generation))
66
-
-`If`
67
-
-`Then`
68
-
-`Else`
67
+
-`If`
68
+
-`Then`
69
+
-`Else`
69
70
70
71
\* The `[Obsolete]` attribute is `System.Obsolete`. All of the others have been defined within this library. `System.ComponentModel.DataAnnotations` support is currently [in discussion](https://github.com/gregsdennis/json-everything/issues/143).
71
72
@@ -142,6 +143,80 @@ For POCOs, read-only properties and fields will be marked with a `readOnly` keyw
142
143
143
144
Lastly, property names will either be listed as declared in code (default) or sorted by name. This is controlled via the `SchemaGeneratorConfiguration.PropertyOrder` property.
144
145
146
+
### Setting identifiers and referencing external schemas
147
+
148
+
In JSON Schema, the `$id` keyword is the primary way to create an identifier for a schema. To create an identifier for a .Net type, you'll use the `[Id]` attribute along with a URI. This has two effects:
149
+
150
+
- If the attribute is found on the root type (the type used in the `.FromType<T>()` call), then the `$id` keyword will be added to the schema.
151
+
- If the attribute is found on a type used for a property, then a reference (`$ref`) will be created.
152
+
153
+
For example, let's look at these classes:
154
+
155
+
```c#
156
+
[Id("https://docs.json-everything.net/foo")]
157
+
classFoo
158
+
{
159
+
publicBarValue { get; set; }
160
+
}
161
+
162
+
[Id("https://docs.json-everything.net/bar")]
163
+
classBar
164
+
{
165
+
publicintNumber { get; set; }
166
+
}
167
+
```
168
+
169
+
When we call `.FromType<Foo>()`, the following schema will be generated:
Notice that the attribute on `Foo` was converted to an `$id` keyword, but the attribute on `Bar` was used in a reference.
182
+
183
+
Another way to apply references is through the configuration's `ExternalReferences` property. This property is a mapping that allows you to provide an `$id` URI for a given type, and can be useful for when you don't have the ability to modify a type, but you want to create a reference to it.
184
+
185
+
> The `ExternalReferences` configuration will override any `[Id]` attributes.
Inadditiontotheexplicitattributesabove, theXMLcomment `<Summary>` elementcanbeconfiguredtorendertoa `description` keyword. Because .NetsavesthisinformationintoanexternalXMLfileinsteadofintothereflectiondata, you'll need to have a configuration object and register the XML filename.
0 commit comments