Product
Socket Now Supports uv.lock Files
Socket now supports uv.lock files to ensure consistent, secure dependency resolution for Python projects and enhance supply chain security.
praetorian
Advanced tools
Praetorian is a structured JSON validator. Taking JSON data payload and a JSON schema, it's primary usage is to ensure the data meets the required specification of said schema.
While there are other JSON schema validators in the wild, often they are complex, un-weildy or require a lot of knowledge upfront. Praetorian has been designed to be simple to deploy, fast to execute and flexible to support common use cases.
$ npm install praetorian
Praetorian supports the following data types "out of the box", boolean
, date
, decimal
, integer
, string
. By defining these in your schema against a JSON key, Praetorian will ensure the value passed in the JSON data is of that type. Types are required.
{
"shield": true
}
{
"shield": "2016-06-30"
}
{
"shield": 1.07
}
{
"shield": 14
}
{
"shield": "wooden"
}
Praetorian supports both complex data types array
and object
. Both can be used in a schema recursively.
Type array
needs a JSON key of items
. Inside an array
you can pass more basic or complex types as required. As with basic types, array
can have a "required" JSON key.
Note: when passing JSON data as an array
type, the "items" structure can be repeated as many times as you need.
{
"weapon": {
"type": "array",
"required": true,
"items": {
"sword": {
"type": "string"
},
"dagger": {
"type": "string"
}
}
}
}
Type object
needs a JSON key of properties
. Inside an object
you can pass more basic or complex types as required. As with basic types, object
can have a required
JSON key.
Note: unlike with array
, when passing JSON data as type object
, the properties
structure can only be included once.
{
"weapon": {
"type": "object",
"required": true,
"properties": {
"sword": {
"type": "string"
},
"dagger": {
"type": "string"
}
}
}
}
To mark a JSON key as a required field simply do the following:
{
"shield": {
"required": true
}
}
To pass validation of a schema with a required
property, the supplied JSON data must have this field present and correct
Note: if the field is not required, you can set "required": false
or simply remove the property entirely.
During the praetorian.validate()
call, any data that is not recognised by the schema will be removed from the result.
Using an array
type. With the following example notice in the result, the key location
on the second object in the senators
array has been stripped out of the "result". As it doesn't form part of the schema, Praetorian removes this property.
Schema
{
"senators": {
"type": "array",
"items": {
"name": {
"type": "string"
},
"age": {
"type": "integer"
}
}
}
}
JSON
{
"senators": [
{
"name": "Graccus",
"age": 68
},
{
"name": "Quintus",
"age": 56,
"location": "Rome"
}
]
}
Result
{
"senators": [
{
"name": "Graccus",
"age": 68
},
{
"name": "Quintus",
"age": 56
}
]
}
To include Praetorian in your project and get underway, use the following snippet.
var Praetorian = require( 'praetorian' );
praetorian = new Praetorian( options );
// pass your data and structure in like this
praetorian.validate( json, schema, function( err, result ) {
if( err ) {
// in the instance of a schema validation error, requirements will tell you for the passed schema
// how to fulfill the specification
praetorian.requirements( schema, function( err, result ) {
if( err ) {
// requirements errored
} else {
// requirements "result" drop out here
}
} );
} else {
// clean data "result" drops out here
}
} );
Options can be passed into the Praetorian constructor to modify the default behaviour like this:
var Praetorian = require( 'praetorian' );
praetorian = new Praetorian(
{
automaticTypeConversion: false,
language: "es"
}
);
By default automaticTypeConversion
is set to true
. When praetorian.validate()
is called, where "types" are specified in your schema, Praetorian will attempt to convert an obvious types to their native. To turn this off, set it to false
.
How?
{
automaticTypeConversion: false
}
Schema
{
"hasHorse": {
"type": "boolean"
}
}
JSON
{
"hasHorse": "true"
}
Result
{
"hasHorse": true
}
By default language
is set to en
(English). When .validate()
or .requirements()
is called, any messages returned will be in the requested language. Supported languages can be found in the lib/internationalisation
folder.
Note: description
keys will be returned from the schema as they are passed in.
How?
{
language: "es"
}
Schema
{
"hasHorse": {
"type": "boolean",
"description": "Does this senator have a horse?"
}
}
JSON
{
"hasHorse": "notABoolean"
}
Result
{
"hasHorse": {
"example": "debe ser un valor booleano e.g. verdad",
"description": "Does this senator have a horse?",
"required": false
}
}
To run the test harness change to the praetorian directory:
cd praetorian
and run the tests:
node test/sanity.js
(The MIT License)
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
FAQs
A structured JSON parser and validator
We found that praetorian demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Product
Socket now supports uv.lock files to ensure consistent, secure dependency resolution for Python projects and enhance supply chain security.
Research
Security News
Socket researchers have discovered multiple malicious npm packages targeting Solana private keys, abusing Gmail to exfiltrate the data and drain Solana wallets.
Security News
PEP 770 proposes adding SBOM support to Python packages to improve transparency and catch hidden non-Python dependencies that security tools often miss.