JSON-SCHEMA Tutorial

Item:OSWf4a9514baed04859a4c6c374a7312f10 /
Revision as of 07:27, 13 April 2023 by Admin (talk | contribs) (Install package: OSW Docs - Core)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
JSON-SCHEMA Tutorial [OSWf4a9514baed04859a4c6c374a7312f10]
ID OSWf4a9514baed04859a4c6c374a7312f10
UUID f4a9514b-aed0-4859-a4c6-c374a7312f10
Label JSON-SCHEMA Tutorial
Machine compatible name JsonSchemaTutorial
OSW7ab0a0b8aaa34217bff6cf9e97988c4d.png
Statements (outgoing)
Statements (incoming)
Keywords

Description

No description found
Item
Type(s)/Category(s) Tutorial
CreativeWork
Article
Tutorial
Prerequisites (required) JSON Tutorial
Prerequisites (optional)
Follow-up (recommended) JSON-LD Tutorial
JSON Application Tutorial

View as slide show

JSON-SCHEMA: Motivation

Problem: If many JSON-Files are created over time by different people / tools, you want them to follow a certain structure

JSON Dataset 1
{
    "c": 1.0
}
JSON Dataset 2
{
    "c": "1.0"
}

They express the same information, but are different / incompatible

JSON-SCHEMA: Validation (1)

A JSON-SCHEMA can describe and validate a JSON-Document

JSON Schema
{
    "type": "object",
    "properties": {
        "c": {
            "type": "number"
        }
    }
}
JSON Dataset 1
{
    "c": 1.0



}

Dataset 1 is valid

JSON-SCHEMA: Validation (2)

A JSON-SCHEMA can describe and validate a JSON-Document

JSON Schema
{
    "type": "object",
    "properties": {
        "c": {
            "type": "number"
        }
    }
}
JSON Dataset 2
{
    "c": "1.0"



}

Dataset 2 is not valid


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! [1]

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 [2]:
    • 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!
{
    "title": "Item",
    "type": "object",
    "properties": {
        "name": {
            "type": "string"
        },
        "count": {
            "type": "integer"
        },
        "pi": {
            "type": "number"
        },
        "validated": {
            "type": "boolean"
        }     
    }
}

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
{
    "title": "Item",
    "type": "object",
    "properties": {
        "name": {
            "type": "string"
        },
        "count": {
            "type": "integer"
        },
        "pi": {
            "type": "number"
        },
        "validated": {
            "type": "boolean"
        }     
    }
}

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
{
    "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"
        }     
    }
}

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
{
    "title": "Item",
    "type": "object",
    "properties": {
        "name": {
            "title": "Name",
            "description": "The name of the item",    
            "type": "string"
        }  
    }
}

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
{
    "title": "Item",
    "type": "object",
    "properties": {
        "name": {
            "title": "Name",
            "description": "The name of the item",
            "default": "John Doe",    
            "type": "string"
        }  
    }
}

JSON-SCHEMA: Selected Types

Some selected property types and formats

JSON-SCHEMA: Integer

Some selected property types and formats

  • "type": "integer" - analogous to int [3]
    • 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
{
    "type": "integer",
}

JSON-SCHEMA: Number (1)

Some selected property types and formats

  • "type": "integer"
  • "type": "number" - analogous to float [4]
    • 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
{
    "type": "number",
}

JSON-SCHEMA: Number (2)

Some selected property types and formats

  • "type": "integer"
  • "type": "number" - analogous to float
{
    "type": "number",
    "multipleOf" : 10
}

JSON-SCHEMA: Number (3)

Some selected property types and formats

  • "type": "integer"
  • "type": "number" - analogous to float
    • Multiples
    • Range [6]
{
    "type": "number",
    "minimum": 0,
    "exclusiveMaximum": 100
}

JSON-SCHEMA: String

Some selected property types and formats

  • "type": "integer"
  • "type": "number"
  • "type": "string" - analogous to str [7]
{
    "type": "string"
}

JSON-SCHEMA: String Length

Some selected property types and formats

  • "type": "integer"
  • "type": "number"
  • "type": "string" - analogous to str
{
    "type": "string",
    "minLength": 2,
    "maxLength": 3
}

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 [9]
{
    "type": "string",
    "pattern": "^(\\([0-9]{3}\\))?[0-9]{3}-[0-9]{4}$"
}

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 [10]
      • "email"
{
    "type": "string",
    "format": "email"
}

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
{
    "type": "object",
    "properties": {        
        "image": {
            "title": "Image",
            "type": "string",
            "format": "uri"
        }
    }
}

JSON-SCHEMA: Array (1)

Some selected property types and formats

  • "type": "integer"
  • "type": "number"
  • "type": "string"
  • "type": "array" - analogous to list [11]
{
    "type": "array"
}

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"}
{
    "type": "array"
}

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 [12]
{
    "type": "array",
    "items": {
        "type": "number"
    }
}

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 [13]
{
    "type": "array",
    "minItems": 2,
    "maxItems": 3
}

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 [14]
{
    "type": "array",
    "uniqueItems": true
}

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
JSON Schema
{
    "title": "Entity",
    "type": "object",
    "required": [
        "label"
    ],
    "properties": {
        "label": {
            "type": "string"
        }    
    }
}
JSON Data
{
    "label": "Item"
}

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
JSON Schema
{
    "title": "Entity",
    "type": "object",
    "required": [
        "label",
        "uuid"
    ],
    "properties": {
        "uuid": {
            "title": "UUID",
            "type": "string",
            "format": "uuid",
            "options": {
                "hidden": true
            }
        }
    }
}
JSON Data
{
    "label": "Item",
    "uuid": "ae7e1570-80c2-4476-8e68-bbd3063ba085"
}

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
{
    "title": "Identifier",
    "type": "string",
    "oneOf": [
        {
            "title": "UUID",
            "format": "uuid"
        },
        {
            "title": "URI or URL",
            "format": "uri"
        }
    ]
}

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
{
    "title": "Abbreviation",    
    "type": "string",
    "allOf": [
        "minLength": 2,
        "maxLength": 5,
        "pattern": "[A-Z]"
    ]
}

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
{
    "title": "Abbreviation",    
    "not": [
        "type": "number",
        "type": "integer",
        "type": "null",
        "type": "boolean"  
    ]
}

JSON Documents: Next

jsondata
required_predecessor
"Item:OSWf1df064239044b8fa3c968339fb93344"
type
"Category:OSW494f660e6a714a1a9681c517bbb975da"
uuid"f4a9514b-aed0-4859-a4c6-c374a7312f10"
name"JsonSchemaTutorial"
label
text"JSON-SCHEMA Tutorial"
lang"en"
image"File:OSW7ab0a0b8aaa34217bff6cf9e97988c4d.png"
recommended_successor
"Item:OSW911488771ea449a6a34051f8213d7f2f"
"Item:OSWee501c0fa6a9407d99c058b5ff9d55b4"