Tag.bio Syntax

syntax overview

Designing, building, and maintaining a Tag.bio Data Product involves authoring & editing a series of JSON objects & arrays stored as files in the project code repository.

These JSON files instruct the Tag.bio system to load & model data within a Data Product and to deploy protocols (apps) as Data Product API methods.

This implementation of JSON-as-code is designed to be stable, secure, scalable, human-readable, and language-agnostic.

file and folder conventions

The JSON files in a Data Product repository are conventionally organized into folders and subfolders which segregate the different functions of the codebase.

File and folder naming conventions are not mandatory, but please use them. These conventions help beginner developers better align their work with advanced Data Products, they enable greater code re-use, and they give instant familiarity to any experienced developer visiting a Data Product's codebase.

ordering of attributes and values

In a JSON object, the ordering of attributes does not matter.

However, many JSON object types within the Tag.bio system conventionally adhere to standards for the order in which attributes are specified. These standards are not enforced, but it is recommended to follow the attribute ordering conventions for each JSON object type. This will help you and other developers more readily understand how each object will behave in the system.

In a JSON array, the ordering of values does matter.

There are many situations within the Tag.bio system that will utilize the ordering of values within a JSON array, and some situations which will not care about ordering.

JSON values as file references

The Tag.bio JSON syntax allows for wide-scale use of file references for better organization & modularization of the codebase.

Thus, most values for JSON object attributes, and most elements in JSON arrays are permitted to be strings - references to other files containing JSON objects and arrays.

Example of an attribute with a value of a JSON object type:

{
  "some_attribute": {
    ...
  }
}

Example of the same attribute with a value of a string - a reference to a JSON object within a file

{
 "some_attribute": "path/to/object.json"
} 

During compilation, when string values are encountered that represent paths to other JSON files - the contents of those files will be ingested and the system will work as if all JSON components were included in the same parent file.

File paths within JSON strings are almost always designed to be relative to the root of the Data Product project - i.e. the git repository root.

objects as an automatic 1-element array

In most cases across the Tag.bio platform, if an attribute value is required to be a JSON array of objects (or string references to files containing JSON objects), but you only have one element to put in that array, you don't have to wrap the object inside an array. Instead, you can directly specify an object for that attribute value.

For example, instead of this:

{
  "array_attribute": [
    {...}
  ]
}

You can do this:

{
  "array_attribute": {...}
}

Or use a file reference like this:

{
  "array_attribute": "path/to/object.json"
}

syntax checking

The Tag.bio compiler will error and crash upon encountering a JSON syntax issue - e.g. a missing comma. The resulting error message on the server console will indicate the JSON file and line where the issue occurred.

However, it's a good idea to use a modern code editor for editing the JSON files so it can catch simple syntax issues for you - like missing commas or mismatched brackets - before crashing the Tag.bio compiler.

comments

The JSON parser in Tag.bio allows comments with two forward slashes //, even for files with a .json extension. Comments within your code are a great way to provide useful, concise descriptions of the inner workings of a Data Product.