Skip to content

Commit 5f7108a

Browse files
IsakNaslundBhIsakNaslundBh
committed
wrap examples in example admonitions
1 parent bb3d462 commit 5f7108a

File tree

1 file changed

+101
-97
lines changed

1 file changed

+101
-97
lines changed

‎docs/BHoM_oM/JSONSchema.md‎

Lines changed: 101 additions & 97 deletions
Original file line numberDiff line numberDiff line change
@@ -14,71 +14,73 @@ The BHoM JSON schemas make use of [references ($ref)](https://json-schema.org/un
1414
A major benfit of using this type of structure is that in reduces the size and complexity of the schemas, especially for cases when a property is targeting an [interface](#interfaces).
1515

1616
#### Properties
17-
For properties that target another IObject, the property is linked across via $ref. As an example, the [Line](https://bhom.xyz/api/oM/Dimensional/Geometry/Curve/Line/) class has two properties, start and end, that are of type [Point](https://bhom.xyz/api/oM/Dimensional/Geometry/Vector/Point/). These properties are referenced in via the ref keyword:
17+
For properties that target another IObject, the property is linked across via $ref. This allows for greater flexibility as well as simpler composition, especially for more complex schemas. As an example, the [Line](https://bhom.xyz/api/oM/Dimensional/Geometry/Curve/Line/) class has two properties, start and end, that are of type [Point](https://bhom.xyz/api/oM/Dimensional/Geometry/Vector/Point/). These properties are referenced in via the ref keyword:
1818

19-
``` JSON hl_lines="8 11" title="Line.json" linenums="1"
20-
{
21-
"$id" : "https://raw.githubusercontent.com/BHoM/BHoM_JSONSchema/develop/Geometry_oM/Line.json",
22-
"title" : "Line",
23-
"type" : ["object", "null"],
24-
"description" : "Line: A straight segment in space defining the shortest distance between two points in three-dimensional Euclidean geometry.\nThe Vector from Start to End defines the Line direction, which can be important for some applications.",
25-
"properties" : {
26-
"Start" : {
27-
"$ref" : "https://raw.githubusercontent.com/BHoM/BHoM_JSONSchema/develop/Geometry_oM/Point.json"
28-
},
29-
"End" : {
30-
"$ref" : "https://raw.githubusercontent.com/BHoM/BHoM_JSONSchema/develop/Geometry_oM/Point.json"
31-
},
32-
"Infinite" : {
33-
"type" : "boolean",
34-
"description" : "Defines the Line as a ray of infinite extents in both directions"
35-
},
36-
"_t" : {
37-
"type" : ["string", "null"],
38-
"description" : "Optional type disciminator.",
39-
"const" : "BH.oM.Geometry.Line"
40-
},
41-
"_bhomVersion" : {
42-
"type" : ["string", "null"],
43-
"description" : "Optional version of BHoM used as part of automatic versioning and schema upgrades."
44-
}
45-
},
46-
"required" : ["Start", "End", "Infinite"]
47-
}
48-
```
19+
!!! example
4920

50-
``` JSON hl_lines="2" title="Point.json" linenums="1"
51-
{
52-
"$id" : "https://raw.githubusercontent.com/BHoM/BHoM_JSONSchema/develop/Geometry_oM/Point.json",
53-
"title" : "Point",
54-
"type" : ["object", "null"],
55-
"description" : "Point: Defines a dimensionless location in three-dimensional space.",
56-
"properties" : {
57-
"X" : {
58-
"type" : "number",
59-
"description" : "Position along global X coordinate axis."
60-
},
61-
"Y" : {
62-
"type" : "number",
63-
"description" : "Position along global Y coordinate axis."
64-
},
65-
"Z" : {
66-
"type" : "number",
67-
"description" : "Position along global Z coordinate axis."
21+
``` JSON hl_lines="8 11" title="Line.json" linenums="1"
22+
{
23+
"$id" : "https://raw.githubusercontent.com/BHoM/BHoM_JSONSchema/develop/Geometry_oM/Line.json",
24+
"title" : "Line",
25+
"type" : ["object", "null"],
26+
"description" : "Line: A straight segment in space defining the shortest distance between two points in three-dimensional Euclidean geometry.\nThe Vector from Start to End defines the Line direction, which can be important for some applications.",
27+
"properties" : {
28+
"Start" : {
29+
"$ref" : "https://raw.githubusercontent.com/BHoM/BHoM_JSONSchema/develop/Geometry_oM/Point.json"
30+
},
31+
"End" : {
32+
"$ref" : "https://raw.githubusercontent.com/BHoM/BHoM_JSONSchema/develop/Geometry_oM/Point.json"
33+
},
34+
"Infinite" : {
35+
"type" : "boolean",
36+
"description" : "Defines the Line as a ray of infinite extents in both directions"
37+
},
38+
"_t" : {
39+
"type" : ["string", "null"],
40+
"description" : "Optional type disciminator.",
41+
"const" : "BH.oM.Geometry.Line"
42+
},
43+
"_bhomVersion" : {
44+
"type" : ["string", "null"],
45+
"description" : "Optional version of BHoM used as part of automatic versioning and schema upgrades."
46+
}
6847
},
69-
"_t" : {
70-
"type" : ["string", "null"],
71-
"description" : "Optional type disciminator.",
72-
"const" : "BH.oM.Geometry.Point"
48+
"required" : ["Start", "End", "Infinite"]
49+
}
50+
```
51+
52+
``` JSON hl_lines="2" title="Point.json" linenums="1"
53+
{
54+
"$id" : "https://raw.githubusercontent.com/BHoM/BHoM_JSONSchema/develop/Geometry_oM/Point.json",
55+
"title" : "Point",
56+
"type" : ["object", "null"],
57+
"description" : "Point: Defines a dimensionless location in three-dimensional space.",
58+
"properties" : {
59+
"X" : {
60+
"type" : "number",
61+
"description" : "Position along global X coordinate axis."
62+
},
63+
"Y" : {
64+
"type" : "number",
65+
"description" : "Position along global Y coordinate axis."
66+
},
67+
"Z" : {
68+
"type" : "number",
69+
"description" : "Position along global Z coordinate axis."
70+
},
71+
"_t" : {
72+
"type" : ["string", "null"],
73+
"description" : "Optional type disciminator.",
74+
"const" : "BH.oM.Geometry.Point"
75+
},
76+
"_bhomVersion" : {
77+
"type" : ["string", "null"],
78+
"description" : "Optional version of BHoM used as part of automatic versioning and schema upgrades."
79+
}
7380
},
74-
"_bhomVersion" : {
75-
"type" : ["string", "null"],
76-
"description" : "Optional version of BHoM used as part of automatic versioning and schema upgrades."
81+
"required" : ["X", "Y", "Z"]
7782
}
78-
},
79-
"required" : ["X", "Y", "Z"]
80-
}
81-
```
83+
```
8284

8385
In the example above, you can see that the Point class is referenced across using the $ref keyword, and that the $id of the point is exactly matching the ref used.
8486

@@ -90,7 +92,7 @@ For a json object to validate against a interface schema it requires the type di
9092
!!! note
9193
The type discriminator "_t" is not generally set as required across the BHoM JSON schemas for validation against a known class schema. When validating against a interface schema, at base level or as a property, however it is required to determine the schema to validate against.
9294

93-
!!! note
95+
!!! warning
9496
To successfully evaluate a type that is implementing an interface agaist the schema of that interface, the subtype needs to known at the point of creation of the interface schema. This means a class in a repo not set to be part of the [generation](#generation) wont be able to be validated against its base interface, even if it is implementing that inferface in C#.
9597

9698
It then uses the [if then + all of](https://json-schema.org/understanding-json-schema/reference/conditionals#ifthenelse) pattern to validate the object against the appropriate type.
@@ -107,44 +109,46 @@ Then the all-of + if-the pattern follows, which can be read as: If the value `"_
107109

108110
The initial part of requiring `"_t"` to exist and match one of the types guarantiues that only valid types are validated as correct. The allOf if, then ensures that this subtime is valid against the matching schema.
109111

110-
``` JSON title="IPolyline" linenums="1" hl_lines="3 6 14 20 27 33"
111-
{
112-
"$id" : "https://raw.githubusercontent.com/BHoM/BHoM_JSONSchema/develop/Geometry_oM/IPolyline.json",
113-
"required" : ["_t"],
114-
"properties" : {
115-
"_t" : {
116-
"enum" : ["BH.oM.Geometry.Polyline", "BH.oM.Geometry.Polygon"]
117-
}
118-
},
119-
"allOf" : [{
120-
"if" : {
121-
"properties" : {
122-
"_t" : {
123-
"type" : ["string", "null"],
124-
"const" : "BH.oM.Geometry.Polyline"
125-
}
112+
!!! example
113+
114+
``` JSON title="IPolyline" linenums="1" hl_lines="3 6 14 20 27 33"
115+
{
116+
"$id" : "https://raw.githubusercontent.com/BHoM/BHoM_JSONSchema/develop/Geometry_oM/IPolyline.json",
117+
"required" : ["_t"],
118+
"properties" : {
119+
"_t" : {
120+
"enum" : ["BH.oM.Geometry.Polyline", "BH.oM.Geometry.Polygon"]
121+
}
122+
},
123+
"allOf" : [{
124+
"if" : {
125+
"properties" : {
126+
"_t" : {
127+
"type" : ["string", "null"],
128+
"const" : "BH.oM.Geometry.Polyline"
129+
}
130+
},
131+
"required" : ["_t"]
126132
},
127-
"required" : ["_t"]
128-
},
129-
"then" : {
130-
"$ref" : "https://raw.githubusercontent.com/BHoM/BHoM_JSONSchema/develop/Geometry_oM/Polyline.json"
131-
}
132-
}, {
133-
"if" : {
134-
"properties" : {
135-
"_t" : {
136-
"type" : ["string", "null"],
137-
"const" : "BH.oM.Geometry.Polygon"
138-
}
133+
"then" : {
134+
"$ref" : "https://raw.githubusercontent.com/BHoM/BHoM_JSONSchema/develop/Geometry_oM/Polyline.json"
135+
}
136+
}, {
137+
"if" : {
138+
"properties" : {
139+
"_t" : {
140+
"type" : ["string", "null"],
141+
"const" : "BH.oM.Geometry.Polygon"
142+
}
143+
},
144+
"required" : ["_t"]
139145
},
140-
"required" : ["_t"]
141-
},
142-
"then" : {
143-
"$ref" : "https://raw.githubusercontent.com/BHoM/BHoM_JSONSchema/develop/Geometry_oM/Polygon.json"
144-
}
145-
}]
146-
}
147-
```
146+
"then" : {
147+
"$ref" : "https://raw.githubusercontent.com/BHoM/BHoM_JSONSchema/develop/Geometry_oM/Polygon.json"
148+
}
149+
}]
150+
}
151+
```
148152

149153
## Releases
150154

0 commit comments

Comments
 (0)