- Research Area
- Introduction
- Type System
- version 2 roadmap
- MIMUW
- Using nianio pattern in JS
- Using nianio pattern in C
- json:ptd validator documentation
- json:ptd validator
json-ptd validator
After reading this documentation, you will be able to start using the json-ptd validator library in your own projects.
What is json-ptd validator?
json-ptd validator is a JavaScript library that allows you to validate JSON using a defined type.
In other words, you are able to verify that the JSON structure and data types are exactly as you expect.
json-ptd example
Let’s try to utilize the invoice_type
as the example. Below is an example of an invoice defined using JSON.
{
"number" : "101/01/2023",
"date" : "2023-01-28",
"due_date" : "2023-02-28",
"sender" : {
"company_name" : "Ringwood",
"company_address" : "77 Old Edinburgh Road, Beeston NG34ZY",
"vat_number" : "GB123456789"
},
"receiver" : {
"company_name" : "Roundpath",
"company_address" : "88 Golden Knowes Road, Freshford BA36RX",
"vat_number" : "GB456123789"
},
"items" : [
{
"item_description" : "Wooden ring bell",
"quantity" : 1,
"net_price" : 78.55,
"vat_rate" : 20.00
},
{
"item_description" : "Wooden mailbox (white)",
"quantity" : 2,
"net_price" : 32.10,
"vat_rate" : 20.00
},
{
"item_description" : "Wooden fence (white)",
"quantity" : 8,
"net_price" : 18.05,
"vat_rate" : 20.00
}
]
}
It consists of the following fields: number
, date
, due_date
, sender
, receiver
and items
. The first three are of (JSON) string
type, which corresponds to ov.ptd_utf8
json-ptd type. By using it, we are able to define value type for number
, date
and due_date
fields.
{
"invoice_type" : { "ov.ptd_rec" : {
"number" : { "ov.ptd_utf8" : null },
"date" : { "ov.ptd_utf8" : null },
"due_date" : { "ov.ptd_utf8" : null }
}}
}
Notice the syntax of json-ptd, the top level of json-ptd type is always an object
, which keys are type names.
In our example it is invoice_type
, which we are going to define.
As mentioned before invoice_type
consist of several fields, what can be defined with ov.ptd_rec
type.
Remember, like an object JSON specification, ov.ptd_rec is an unordered set of fields/values pairs.
Next, we are going to specify the type for the sender
and the receiver
. In the example of invoice we can notice that both of them consist of the same fields, which are: company_name
, company_address
and vat_rate
. In this scenario, we can define separate company_type
and then refer to it.
{
"company_type" : { "ov.ptd_rec" : {
"company_name" : { "ov.ptd_utf8" : null },
"company_address" : { "ov.ptd_utf8" : null },
"vat_number" : { "ov.ptd_utf8" : null }
}}
}
As in case of invoice_type
, it is ov.ptd_rec
. All its fields are ov.ptd_utf8
type. By utilizing the ov.ptd_ref
type, you can create recursive structures also, which an example is metatype
.
{
"invoice_type" : { "ov.ptd_rec" : {
"number" : { "ov.ptd_utf8" : null },
"date" : { "ov.ptd_utf8" : null },
"due_date" : { "ov.ptd_utf8" : null },
"sender" : { "ov.ptd_ref" : "company_type" },
"receiver" : { "ov.ptd_ref" : "company_type" }
}},
"company_type" : { "ov.ptd_rec" : {
"company_name" : { "ov.ptd_utf8" : null },
"company_address" : { "ov.ptd_utf8" : null },
"vat_number" : { "ov.ptd_utf8" : null }
}}
}
The last type we need to define is items
. Due to the fact that the number of items on the invoice may differ, we should use the ov.ptd_arr
type. The only parameter that is required is the type of array elements. As we know from our example item is described by: item_description
, quantity
, net_price
and vat_rate
, so we should use ov.ptd_rec
type.
{
"items" : { "ov.ptd_arr" : { "ov.ptd_rec" : {
"item_description" : { "ov.ptd_utf8" : null },
"quantity" : { "ov.ptd_int" : null },
"net_price" : { "ov.ptd_double" : null },
"vat_rate" : { "ov.ptd_double" : null }
}}}
}
Putting all together:
{
"invoice_type" : { "ov.ptd_rec" : {
"number" : { "ov.ptd_utf8" : null },
"date" : { "ov.ptd_utf8" : null },
"due_date" : { "ov.ptd_utf8" : null },
"sender" : { "ov.ptd_ref" : "company_type" },
"receiver" : { "ov.ptd_ref" : "company_type" },
"items" : { "ov.ptd_arr" : { "ov.ptd_rec" : {
"item_description" : { "ov.ptd_utf8" : null },
"quantity" : { "ov.ptd_int" : null },
"net_price" : { "ov.ptd_double" : null },
"vat_rate" : { "ov.ptd_double" : null }
}}}
}},
"company_type" : { "ov.ptd_rec" : {
"company_name" : { "ov.ptd_utf8" : null },
"company_address" : { "ov.ptd_utf8" : null },
"vat_number" : { "ov.ptd_utf8" : null }
}}
}
This completes the definition of the type.
Metatype
A metatype
is both a type and a self-consistent value. This means that by entering the metatype in the type and data fields into the validator, we will receive a compliance message.
{
"metatype_lib" : { "ov.ptd_hash" : { "ov.ptd_ref" : "metatype" }},
"metatype" : { "ov.ptd_var" : {
"ptd_rec" : { "ov.with_param" : { "ov.ptd_hash" : { "ov.ptd_ref" : "metatype" }}},
"ptd_arr" : { "ov.with_param" : { "ov.ptd_ref" : "metatype" }},
"ptd_hash" : { "ov.with_param" : { "ov.ptd_ref" : "metatype" }},
"ptd_var" : { "ov.with_param" : { "ov.ptd_hash" : { "ov.ptd_ref" : "variant_def"}}},
"ptd_ref" : { "ov.with_param" : { "ov.ptd_utf8" : null } },
"ptd_utf8" : { "ov.no_param" : null },
"ptd_bytearray" : { "ov.no_param" : null },
"ptd_int" : { "ov.no_param" : null },
"ptd_double" : { "ov.no_param" : null },
"ptd_bool" : { "ov.no_param" : null },
"ptd_decimal" : { "ov.with_param" : { "ov.ptd_rec" : {
"size" : { "ov.ptd_int" : null },
"scale" : { "ov.ptd_int" : null }
}}}
}},
"variant_def" : { "ov.ptd_var" : {
"no_param" : { "ov.no_param" : null },
"with_param" : { "ov.with_param" : { "ov.ptd_ref" : "metatype" }}
}}
}
Simple types
Supported json-ptd
types can be divided into simple and complex.
json-ptd
supports 6 different simple types - each corresponds to a proper data type.
All simple types can define a field value type, but cannot define the field itself.
ov.ptd_utf8
Type without parameter, corresponds to UTF-8 encoding standard. Corresponding value in JSON should be a string
.
Type:
{
"item_description" : { "ov.ptd_utf8" : null }
}
Example:
"Wooden ring bell"
ov.ptd_bytearray
Type without parameter. Corresponding value in JSON should be a string
and all characters should correspond to integers in the range 0 <= x < 256
.
Type:
{
"item_description" : { "ov.ptd_bytearray" : null }
}
Example:
"576f6f64656e2072696e672062656c6c"
ov.ptd_int
Type without parameter. Corresponding value in JSON should be a number
which is integer.
Type:
{
"quantity" : { "ov.ptd_int" : null }
}
Example:
2
ov.ptd_double
Type without parameter. Corresponding value in JSON should be a number
.
Type:
{
"net_price" : { "ov.ptd_double" : null }
}
Example:
78.55
ov.ptd_bool
Type without parameter. There are only two possible values: true
and false
.
Type:
{
"is_delivered" : { "ov.ptd_bool" : null }
}
Example:
false
ov.ptd_decimal
Type with parameter. Required parameter is ov.ptd_rec
(more information in Complex types
section), which includes 2 fields: size
and scale
. Both fields are ov.ptd_int
.
Type:
{
"vat_rate" : { "ov.ptd_decimal" : { "size" : 4, "scale" : 2 }}
}
Example:
10.50
ov.ptd_ref
Type with parameter. Required parameter is ov.ptd_utf8
, which should correspond to name of another type.
Type:
{
"sender" : { "ov.ptd_ref" : "company_type" },
"company_type" : { "ov.ptd_utf8" : null }
}
Example:
"Ringwood"
Complex types
json-ptd
validator supports 4 different complex types - each corresponds to proper data structure.
ov.ptd_rec
Type with parameter. It corresponds to the type of the JSON object
and allows you to define the required fields along with their types.
Type:
{
"item" : { "ov.ptd_rec" : {
"item_description" : { "ov.ptd_utf8" : null },
"quantity" : { "ov.ptd_int" : null },
"net_price" : { "ov.ptd_double" : null },
"vat_rate" : { "ov.ptd_double" : null }
}}
}
Example:
{
"item_description" : "Wooden ring bell",
"quantity" : 1,
"net_price" : 78.55,
"vat_rate" : 20.00
}
ov.ptd_arr
Type with parameter. It corresponds to the type of the JSON array
and allows you to define array elements type.
Each of the elements must be the same type. According to the JSON specification array
can be top level of JSON structure, which is consistenty with json-ptd specification.
Type:
{
"items" : { "ov.ptd_arr" : { "ov.ptd_utf8" : null }}
}
Example:
["Wooden ring bell", "Wooden mailbox (white)", "Wooden fence (white)"]
ov.ptd_hash
Type with parameter. Like a ov.ptd_rec
it corresponds to the type of the JSON object
. However the only parameter of ov.ptd_hash
is type of all its fields.
The amount and names of the fields are not specified. All fields are the same type.
Type:
{
"car_mileage" : { "ov.ptd_hash" : { "ov.ptd_double" : null }}
}
Example:
{
"ww15151" : 105267.12,
"wb56b12" : 232300.00,
"wz0012a" : 50764.97
}
ov.ptd_var
Type with parameter. According to the ptd
specification ov.ptd_var
is a hash
, which consist of elements, which value is ov.with_param
or ov.no_param
.
Using these keyword we can define if variant has parameter or does not. json-ptd
syntax requires using ov.
prefix when using variants (see examples below).
As you could notice, we use ov.
prefix with all supported json-ptd
types - it is because all types are variants in fact (see metatype
).
Type:
{
"car_type" : { "ov.ptd_var" : {
"gasoline" : { "ov.with_param" : { "ov.ptd_rec" : {
"fuel_consumption" : { "ov.ptd_double" : null },
"transmission_type" : { "ov.ptd_utf8" : null }
}}},
"electric" : { "ov.with_param" : { "ov.ptd_rec" : {
"power_consumption" : { "ov.ptd_double" : null },
"charging_power" : { "ov.ptd_int" : null }
}}},
"none" : { "ov.no_param" : null }
}}
}
Examples (different variants):
{
"ov.gasoline" : { "fuel_consumption" : 10.5, "transmission_type" : "automatic" }
}
{
"ov.electric" : { "power_consumption" : 18.1, "charging_power" : 250 }
}
{
"ov.none" : null
}
How to use json-ptd validator?
json-ptd validator
is simple application which interface allows user to enter type
and value
in proper text areas. By clicking Validate
button validation of type with values is triggered.
Source files includes ptd-validator.js
file. This script is used to perform validation operation. You can use this file in any of your projects. Function verify
requires 3 arguments, which are value
(JSON parsed value), typeName
(name of the type) and typeLib
(JSON parsed type).
Download json-ptd validator
https://github.com/atinea-nl/json-ptd