# perldoc > Cpanel::JSON::XS::Type

---
type: CommandReference
command: Cpanel::JSON::XS::Type
mode: perldoc
section: 
source: perldoc
---

## Quick Reference

- `encode_json([10, "10", 10.25], [JSON_TYPE_INT, JSON_TYPE_INT, JSON_TYPE_STRING])` — enforces types per element
- `encode_json([10, "10", 10.25], json_type_arrayof(JSON_TYPE_INT))` — enforce uniform array type
- `encode_json(1, JSON_TYPE_BOOL)` — output `true`
- `encode_json($perl_struct, { key1 => JSON_TYPE_STRING, key2 => JSON_TYPE_INT })` — hash type spec
- `encode_json($perl_struct, json_type_hashof(JSON_TYPE_STRING))` — all values as strings
- `decode_json('false', 1, my $type)` — `$type` becomes `JSON_TYPE_BOOL`
- `decode_json($json_string, 0, my $type_spec)` — reconstruct type spec from decoded JSON
- `json_type_anyof(JSON_TYPE_FLOAT, json_type_hashof(json_type_arrayof(JSON_TYPE_INT)))` — alternative types

## Name

Cpanel::JSON::XS::Type — Type support for JSON encode

## Synopsis

perl
use Cpanel::JSON::XS;
use Cpanel::JSON::XS::Type;

encode_json([10, "10", 10.25], [JSON_TYPE_INT, JSON_TYPE_INT, JSON_TYPE_STRING]);
# '[10,10,"10.25"]'

encode_json([10, "10", 10.25], json_type_arrayof(JSON_TYPE_INT));
# '[10,10,10]'

encode_json(1, JSON_TYPE_BOOL);
# 'true'

my $perl_struct = { key1 => 1, key2 => "2", key3 => 1 };
my $type_spec = { key1 => JSON_TYPE_STRING, key2 => JSON_TYPE_INT, key3 => JSON_TYPE_BOOL };
my $json_string = encode_json($perl_struct, $type_spec);
# '{"key1":"1","key2":2,"key3":true}'

my $perl_struct = { key1 => "value1", key2 => "value2", key3 => 0, key4 => 1, key5 => "string", key6 => "string2" };
my $type_spec = json_type_hashof(JSON_TYPE_STRING);
my $json_string = encode_json($perl_struct, $type_spec);
# '{"key1":"value1","key2":"value2","key3":"0","key4":"1","key5":"string","key6":"string2"}'

my $perl_struct = { key1 => { key2 => [ 10, "10", 10.6 ] }, key3 => "10.5" };
my $type_spec = { key1 => json_type_anyof(JSON_TYPE_FLOAT, json_type_hashof(json_type_arrayof(JSON_TYPE_INT))), key3 => JSON_TYPE_FLOAT };
my $json_string = encode_json($perl_struct, $type_spec);
# '{"key1":{"key2":[10,10,10]},"key3":10.5}'

my $value = decode_json('false', 1, my $type);
# $value is 0 and $type is JSON_TYPE_BOOL

my $value = decode_json('0', 1, my $type);
# $value is 0 and $type is JSON_TYPE_INT

my $value = decode_json('"0"', 1, my $type);
# $value is 0 and $type is JSON_TYPE_STRING

my $json_string = '{"key1":{"key2":[10,"10",10.6]},"key3":"10.5"}';
my $perl_struct = decode_json($json_string, 0, my $type_spec);
# $perl_struct is { key1 => { key2 => [ 10, 10, 10.6 ] }, key3 => 10.5 }
# $type_spec is { key1 => { key2 => [ JSON_TYPE_INT, JSON_TYPE_STRING, JSON_TYPE_FLOAT ] }, key3 => JSON_TYPE_STRING }
## Type Specifications

### Scalar types

- `JSON_TYPE_BOOL` — enforces JSON boolean (`true` or `false`); uses standard Perl boolean logic
- `JSON_TYPE_INT` — enforces JSON number without fraction; uses `int`
- `JSON_TYPE_FLOAT` — enforces JSON number with fraction; uses `+0`
- `JSON_TYPE_STRING` — enforces JSON string
- `JSON_TYPE_NULL` — represents JSON `null`; meaningful only for `undef`

For each type, a variant with suffix `_OR_NULL` exists (e.g., `JSON_TYPE_INT_OR_NULL`) which encodes `undef` to JSON `null`; without the suffix, `undef` is converted according to the type rule.

### Array types

- `[...]` — array of type specs; each element describes the type for the corresponding element of the Perl array (must match count)
- `json_type_arrayof(type_spec)` — applies the same type spec to every element of the Perl array

### Hash types

- `{...}` — hash of type specs; each key corresponds to a key in the Perl hash; missing keys are ignored
- `json_type_hashof(type_spec)` — applies the same type spec to every value of the Perl hash

### Alternatives

- `json_type_anyof(spec1, spec2, ...)` — encoder chooses the first matching spec; max one scalar, one array, one hash
- `json_type_null_or_anyof(...)` — like `json_type_anyof`, but scalar can only be `undef`

### Recursive specifications

- `json_type_weaken(spec)` — creates a weak reference for recursive structures; depends on `Scalar::Util::weaken`

Example recursive spec to encode all scalars as strings:

perl
my $type = json_type_anyof();
$type->[0] = JSON_TYPE_STRING_OR_NULL;
$type->[1] = json_type_arrayof(json_type_weaken($type));
$type->[2] = json_type_hashof(json_type_weaken($type));

print encode_json([ 10, "10", { key => 10 } ], $type);
# ["10","10",{"key":"10"}]
Alternatively, use `Cpanel::JSON::XS->new->type_all_string` for the same effect.

## Examples

See the Synopsis section for extensive examples of both encoding and decoding with type specifications.

## See Also

- [Cpanel::JSON::XS](http://localhost/phpMan.php/perldoc/Cpanel%3A%3AJSON%3A%3AXS/markdown)
- [Scalar::Util](http://localhost/phpMan.php/perldoc/Scalar%3A%3AUtil/markdown)