Argus

JSON is great, but ...

JSON supports:

null
boolean
number
string
array
object

There are other types of data that one regularly encounters writing software, and there are custom types that one may want to send between backend and frontend or remote systems, e.g., dates, UUIDs, sets.

Handling custom types is ad hoc. Data is encoded and the expected types are either implicit in the code or defined in an out-of-band schema. You can't inspect data in a general way. The data isn't necessarily human readable. You can't process data unless the code and/or schema matches the version of the data you're reading. The encoding varies from application to application.

JSON, but better ...

The Argus proposal is simple: encode a custom type as a tagged value. A tagged value is an object with a single field/value, the field is a tag starting with "#" and the value is an encoded value made up of JSON types or other tagged values. For example a date would be:

{"#date" : "1912-06-23"}

So, a person may be represented like this:

{"firstName" : "Alan", "lastName" : "Turing", "dateOfBirth" : {"#date" : "1912-06-23"}}

A person as a tagged value might be:

{"#com.example.person" : {"firstName" : "Alan", "lastName" : "Turing", "dateOfBirth" : {"#date" : "1912-06-23"}}}

Sometimes an object is just an object

If an object has only a single field/value, but the field does not start with "#", then it is not a tagged value. For example, this is not a date:

{"date" : "1912-06-23"}

This is also not a tagged value because it has more than one field/value pair:

{"#date" : "1912-06-23", "type" : "date"}

If an object has a single field/value, but you do not recognize the tag, then just leave it as a tagged value. Maybe someone else will understand the tag. They'll thank you later.

{"#com.example.widget" : [15,73,22,-12]}

Is this a library or specification or ...?

This is not a library. It is a concept. Call it a lightweight specification.

You do not need to implement a JSON parser yourself. Find a fast one and implement enargus/deargus functions as a translation layer on top of it.

It could be a library. If it was a library it should allow registering reader/writers for new types, and process arbitrary tagged values (even if it doesn't understand them). If you make a library, share it!

That's pretty much it!

Some modest proposals

Tags should be namespaced with two or more segments separated by a dot ("."), e.g., "#com.example.mytag".
Single segment tags are reserved to define common types (see below).
If you want to write your own JSON parser, then allow for reading comments and trailing commas in objects and arrays, but never produce them. 100% of developers will thank you for it.

Common types and tags
type	tag	example	description
date	`#date`	`{"#date" : "2025-05-08"}`	A local date without a time or timezone encoded as a string in ISO-8601 format.
instant	`#instant`	`{"#instant" : "2025-05-08T12:27:58.851-00:00"}`	A date with a time and timezone encoded as a string in ISO-8601 format.
set	`#set`	`{"#set" : [1, "2", 3]}`	A set of heterogeneous values encoded as an array.
uuid	`#uuid`	`{"#uuid" : "bbaaf5f4-66e7-4056-8056-be29c6e292d8"}`	A Universally Unique Identifier encoded as a string.

Doesn't library/specification/etc. X do this?

The good ones use a similar or exactly the same tagging scheme and allow for extensibility.

The bad ones are complicated and/or not human readable.

This is not a library nor a specification. I mean, I guess you can use a good library and claim it is Argus-compliant. That's fine with me if it's fine with others.

Questions, comments?

https://github.com/thoughtfull-systems/argus.fyi