Maintenance script: Install package: OSW Docs - Core

2023-12-15T05:17:14Z

Install package: OSW Docs - Core

New page

==JSON-SCHEMA: Motivation ==
Problem: If many JSON-Files are created over time by different people / tools, you want them to follow a certain structure
<div style=" column-count: 3;">
<div>JSON Dataset 1
<syntaxhighlight lang="json">
{
"c": 1.0
}
</syntaxhighlight>
</div>
<div>JSON Dataset 2
<syntaxhighlight lang="json">
{
"c": "1.0"
}
</syntaxhighlight>
</div>
<div>
They express the same information, but are different / incompatible
</div>
</div>

==JSON-SCHEMA: Validation (1)==
A JSON-SCHEMA can describe and validate a JSON-Document
<div style=" column-count: 3;">
<div>JSON Schema
<syntaxhighlight lang="json">
{
"type": "object",
"properties": {
"c": {
"type": "number"
}
}
}
</syntaxhighlight>
</div>
<div>JSON Dataset 1
<syntaxhighlight lang="json">
{
"c": 1.0

}
</syntaxhighlight>
</div>
<div>
Dataset 1 is valid
</div>
</div>

==JSON-SCHEMA: Validation (2)==
A JSON-SCHEMA can describe and validate a JSON-Document
<div style=" column-count: 3;">
<div>JSON Schema
<syntaxhighlight lang="json">
{
"type": "object",
"properties": {
"c": {
"type": "number"
}
}
}
</syntaxhighlight>
</div>
<div>JSON Dataset 2
<syntaxhighlight lang="json">
{
"c": "1.0"

}
</syntaxhighlight>
</div>
<div>
Dataset 2 is not valid
</div>
</div>

==JSON-SCHEMA: Definition==
What is a JSON-SCHEMA?
* A JSON document defining the valid structure of another JSON document
*The "type" keyword is special. It allows us to specify which values of a JSON object are valid! [https://json-schema.org/understanding-json-schema/basics.html#the-type-keyword]

==JSON-SCHEMA: the "type" Keyword ==
What is a JSON-SCHEMA?
* A JSON document defining the valid structure of another JSON document
*The "type" keyword is special. It allows us to specify which values of a JSON object are valid!
*json-schema.org defines the following basic types [https://json-schema.org/understanding-json-schema/reference/type.html#type-specific-keywords]:
**string
**number
**integer
**object
**array
**boolean
**null
==JSON-SCHEMA: Typing==
How to define a JSON-SCHEMA?
*We want to levearge the power of typing and validation
*Therefore, our defined key(word):value pairs need to become JSON objects, specifying a type!
<syntaxhighlight lang="json">
{
"title": "Item",
"type": "object",
"properties": {
"name": {
"type": "string"
},
"count": {
"type": "integer"
},
"pi": {
"type": "number"
},
"validated": {
"type": "boolean"
}
}
}
</syntaxhighlight>

==JSON-SCHEMA: Reference==
How to define a JSON-SCHEMA?
*We want to levearge the power of typing and validation
*Therefore, our defined key(word):value pairs need to become JSON objects, specifying a type!
*JSON (object) properties posses a keyword, which is used for reference
<syntaxhighlight lang="json">
{
"title": "Item",
"type": "object",
"properties": {
"name": {
"type": "string"
},
"count": {
"type": "integer"
},
"pi": {
"type": "number"
},
"validated": {
"type": "boolean"
}
}
}
</syntaxhighlight>

==JSON-SCHEMA: Other Keywords (1)==
How to define a JSON-SCHEMA?
*We want to levearge the power of typing and validation
*Therefore, our defined key(word):value pairs need to become JSON objects, specifying a type!
*JSON (object) properties posses a keyword, which is used for reference
*JSON properties, being objects, can also have a title - e.g., for display purpose
<syntaxhighlight lang="json">
{
"title": "Item",
"type": "object",
"properties": {
"name": {
"title": "Name",
"type": "string"
},
"count": {
"title": "Count",
"type": "integer"
},
"pi": {
"title": "Pi",
"type": "number"
},
"validated": {
"title": "Validation status",
"type": "boolean"
}
}
}
</syntaxhighlight>

== JSON-SCHEMA: Other Keywords (2) ==
How to define a JSON-SCHEMA?
*We want to levearge the power of typing and validation
*Therefore, our defined key(word):value pairs need to become JSON objects, specifying a type!
*JSON (object) properties posses a keyword, which is used for reference
*JSON properties, being objects, can also have a title - e.g., for display purpose
*Usefull other keywords:
**"description" - to give a context
<syntaxhighlight lang="json">
{
"title": "Item",
"type": "object",
"properties": {
"name": {
"title": "Name",
"description": "The name of the item",
"type": "string"
}
}
}
</syntaxhighlight>

== JSON-SCHEMA: Other Keywords (3) ==
How to define a JSON-SCHEMA?
*We want to levearge the power of typing and validation
*Therefore, our defined key(word):value pairs need to become JSON objects, specifying a type!
*JSON (object) properties posses a keyword, which is used for reference
*JSON properties, being objects, can also have a title - e.g., for display purpose
*Usefull other keywords:
**"description" - to give a context
**"default" - to specify a fall back if no value is entered
<syntaxhighlight lang="json">
{
"title": "Item",
"type": "object",
"properties": {
"name": {
"title": "Name",
"description": "The name of the item",
"default": "John Doe",
"type": "string"
}
}
}
</syntaxhighlight>

==JSON-SCHEMA: Selected Types==
Some selected property types and formats

==JSON-SCHEMA: Integer ==
Some selected property types and formats
*"type": "integer" - analogous to int [https://json-schema.org/understanding-json-schema/reference/numeric.html#integer]
** OK: 42
**OK: -1
**OK: 1.0 - Numbers with a zero fractional part are considered integers
**XX: 3.1415926 - Floating point numbers are rejected
**XX: "42" - Numbers as strings are rejected
<syntaxhighlight lang="json">
{
"type": "integer",
}
</syntaxhighlight>

==JSON-SCHEMA: Number (1)==
Some selected property types and formats
*"type": "integer"
*"type": "number" - analogous to float [https://json-schema.org/understanding-json-schema/reference/numeric.html#number]
** OK: all of the "integer" valid values
**OK: 3.1415926 - Floating point numbers
**OK: 2.99792458e8 - Exponential notation
**XX: "42" - Numbers as strings are rejected
<syntaxhighlight lang="json">
{
"type": "number",
}
</syntaxhighlight>

==JSON-SCHEMA: Number (2)==
Some selected property types and formats
* "type": "integer"
* "type": "number" - analogous to float
** Multiples [https://json-schema.org/understanding-json-schema/reference/numeric.html#multiples]
<syntaxhighlight lang="json">
{
"type": "number",
"multipleOf" : 10
}
</syntaxhighlight>

== JSON-SCHEMA: Number (3) ==
Some selected property types and formats
*"type": "integer"
*"type": "number" - analogous to float
**Multiples
** Range [https://json-schema.org/understanding-json-schema/reference/numeric.html#range]
<syntaxhighlight lang="json">
{
"type": "number",
"minimum": 0,
"exclusiveMaximum": 100
}
</syntaxhighlight>

==JSON-SCHEMA: String ==
Some selected property types and formats
*"type": "integer"
*"type": "number"
*"type": "string" - analogous to str [https://json-schema.org/understanding-json-schema/reference/string.html#string]
<syntaxhighlight lang="json">
{
"type": "string"
}
</syntaxhighlight>

==JSON-SCHEMA: String Length==
Some selected property types and formats
*"type": "integer"
*"type": "number"
*"type": "string" - analogous to str
**Length [https://json-schema.org/understanding-json-schema/reference/string.html#length]
<syntaxhighlight lang="json">
{
"type": "string",
"minLength": 2,
"maxLength": 3
}
</syntaxhighlight>

==JSON-SCHEMA: String Pattern==
Some selected property types and formats
*"type": "integer"
*"type": "number"
*"type": "string" - analogous to str
**Length
** Regular expressions - the "pattern" keyword [https://json-schema.org/understanding-json-schema/reference/string.html#regular-expressions]
<syntaxhighlight lang="json">
{
"type": "string",
"pattern": "^(\$[0-9]{3}\$)?[0-9]{3}-[0-9]{4}$"
}
</syntaxhighlight>

==JSON-SCHEMA: String Format (1)==
Some selected property types and formats
*"type": "integer"
*"type": "number"
*"type": "string" - analogous to str
**Length
**Regular expressions
**Format - the "format" keyword [https://json-schema.org/understanding-json-schema/reference/string.html#format]
***"email"
<syntaxhighlight lang="json">
{
"type": "string",
"format": "email"
}
</syntaxhighlight>

== JSON-SCHEMA: String Format (2) ==
Some selected property types and formats
* "type": "integer"
* "type": "number"
* "type": "string" - analogous to str
**Length
**Regular expressions
**Format - the "format" keyword, some examples:
***"email"
***"date-time"
***"time"
*** "date"
***"duration"
***"ipv4"
*** "uuid"
***"uri" - e.g., an URL
<syntaxhighlight lang="json">
{
"type": "object",
"properties": {
"image": {
"title": "Image",
"type": "string",
"format": "uri"
}
}
}
</syntaxhighlight>

==JSON-SCHEMA: Array (1)==
Some selected property types and formats
*"type": "integer"
*"type": "number"
*"type": "string"
*"type": "array" - analogous to list [https://json-schema.org/understanding-json-schema/reference/array.html#array]
<syntaxhighlight lang="json">
{
"type": "array"
}
</syntaxhighlight>

==JSON-SCHEMA: Array (2)==
Some selected property types and formats
*"type": "integer"
*"type": "number"
*"type": "string"
*"type": "array" - analogous to list
** OK: [1, 2, 3, 4, 5] - items of one type
**OK: [3, "different", { "types" : "of values" }] - items of different types
** XX: {"Not": "an array"}
<syntaxhighlight lang="json">
{
"type": "array"
}
</syntaxhighlight>

==JSON-SCHEMA: Array Item==
Some selected property types and formats
*"type": "integer"
*"type": "number"
*"type": "string"
*"type": "array" - analogous to list
**Specifying types for items - the "items" keyword [https://json-schema.org/understanding-json-schema/reference/array.html#items]
<syntaxhighlight lang="json">
{
"type": "array",
"items": {
"type": "number"
}
}
</syntaxhighlight>

== JSON-SCHEMA: Array Length==
Some selected property types and formats
*"type": "integer"
* "type": "number"
* "type": "string"
* "type": "array" - analogous to list
** Specifying types for items - the "items" keyword
**Length [https://json-schema.org/understanding-json-schema/reference/array.html#length]
<syntaxhighlight lang="json">
{
"type": "array",
"minItems": 2,
"maxItems": 3
}
</syntaxhighlight>

==JSON-SCHEMA: Array Unique==
Some selected property types and formats
* "type": "integer"
*"type": "number"
*"type": "string"
*"type": "array" - analogous to list
**Specifying types for items
**Length
**Uniqueness [https://json-schema.org/understanding-json-schema/reference/array.html#uniqueness]
<syntaxhighlight lang="json">
{
"type": "array",
"uniqueItems": true
}
</syntaxhighlight>

==JSON-SCHEMA: Go-To Patterns==
Some JSON-SCHEMA go-to patterns

== JSON-SCHEMA: Required==
Some JSON-SCHEMA go-to patterns
*Forcing the user to enter a value for a certain property - the "required" keyword
<div style=" column-count: 2;">
<div>JSON Schema
<syntaxhighlight lang="json">
{
"title": "Entity",
"type": "object",
"required": [
"label"
],
"properties": {
"label": {
"type": "string"
}
}
}
</syntaxhighlight>
</div>
<div>JSON Data
<syntaxhighlight lang="json">
{
"label": "Item"
}
</syntaxhighlight>
</div>
</div>

==JSON-SCHEMA: Autogeneration ==
Some JSON-SCHEMA go-to patterns
*Forcing the user to enter a value for a certain property - the "required" keyword
*Automatically generating a value, e.g., for a uuid
<div style=" column-count: 2;">
<div>JSON Schema
<syntaxhighlight lang="json">
{
"title": "Entity",
"type": "object",
"required": [
"label",
"uuid"
],
"properties": {
"uuid": {
"title": "UUID",
"type": "string",
"format": "uuid",
"options": {
"hidden": true
}
}
}
}
</syntaxhighlight>
</div>
<div>JSON Data
<syntaxhighlight lang="json">
{
"label": "Item",
"uuid": "ae7e1570-80c2-4476-8e68-bbd3063ba085"
}
</syntaxhighlight>
</div>
</div>

==JSON-SCHEMA: Options (1)==
Some JSON-SCHEMA go-to patterns
*Allowing more than one valid option - the "anyOf" keyword
*Allowing exactly one valid option - the "oneOf" keyword
<div>
<syntaxhighlight lang="json">
{
"title": "Identifier",
"type": "string",
"oneOf": [
{
"title": "UUID",
"format": "uuid"
},
{
"title": "URI or URL",
"format": "uri"
}
]
}
</syntaxhighlight>
</div>

==JSON-SCHEMA: Options (2)==
Some JSON-SCHEMA go-to patterns
*Allowing more than one valid option - the "anyOf" keyword
*Allowing exactly one valid option - the "oneOf" keyword
*Validating against several options - the "allOf" keyword
<div>
<syntaxhighlight lang="json">
{
"title": "Abbreviation",
"type": "string",
"allOf": [
"minLength": 2,
"maxLength": 5,
"pattern": "[A-Z]"
]
}
</syntaxhighlight>
</div>

==JSON-SCHEMA: Options(3)==
Some JSON-SCHEMA go-to patterns
*Allowing more than one valid option - the "anyOf" keyword
*Allowing exactly one valid option - the "oneOf" keyword
*Validating against several options - the "allOf" keyword
*Excluding one option - the "not" keyword
<div>
<syntaxhighlight lang="json">
{
"title": "Abbreviation",
"not": [
"type": "number",
"type": "integer",
"type": "null",
"type": "boolean"
]
}
</syntaxhighlight>
</div>

==JSON Documents: Next==
*[[Item:OSW911488771ea449a6a34051f8213d7f2f]] [{{fullurl:Item:OSW911488771ea449a6a34051f8213d7f2f
|reveal=true
}} Slideshow]

Item:OSWf4a9514baed04859a4c6c374a7312f10 - Revision history

Maintenance script: Install package: OSW Docs - Core