JSON specification
Detailed technical specification for Zendro’s data model JSON files, aimed at software developers and system administrators.
Table of contents
For each data set you want to include in the project, you need to describe its data model. This description should include its relations, or associations, with any other model, and must be placed in a JSON file following the specification below. Store all these JSON files in a single folder — from now on, in this document, we’ll assume that folder is /your-path/json-files. Each model should have a unique name, independent of its type.
JSON Specs
Each JSON file describes one and only one model. However, one model can reference another model using the associations mechanism described in Associations.
To fully describe a model, specify the following fields in its JSON file:
| Name | Type | Description |
|---|---|---|
| model | String | Name of the model (it is recommended to use snake_case naming style to obtain nice names in the auto-generated GraphQL API). The string here cannot contain spaces. |
| model_name_in_storage | String | The name of the model in the storage itself, e.g. the table name in relational databases, the collection in MongoDB, the node in Neo4j, etc. By default Zendro uses the lowercase pluralized model property. |
| database | String | Name of the database connection as a key defined in data_models_storage_config.json. If this field is not defined, the database connection used will be default-<storageType>. |
| storageType | String | Type of storage where the model is stored. So far can be one of: - sql for local relational databases supported by sequelize, such as PostgreSQL/MySQL etc. - generic for any database that your project connects to remotely. - zendro-server for models stored in another instance created with zendro-tools. - cassandra for local Cassandra databases, supported by the DataStax node cassandra-driver. See Cassandra storage type for Cassandra-specific restrictions. - mongodb for local MongoDB databases, supported by the mongodb-driver. - neo4j for local Neo4j databases, supported by the neo4j-driver. - presto/trino for local Presto/Trino databases, supported by the presto-driver. - amazon-s3 for the Amazon S3 cloud storage service and local object storage MinIO, supported by the amazon-s3-driver. - distributed-data-model for a distributed setup, which connects all relevant adapters. - adapter for the different adapters in a distributed setup: sql-adapter, generic-adapter, cassandra-adapter, mongodb-adapter, amazonS3-adapter, trino-adapter, neo4j-adapter, ddm-adapter, zendro-webservice-adapter. |
| url | String | Only mandatory for zendro-server stored models. Indicates the URL where the Zendro server storing the model is running. |
| attributes | Object | The key of each entry is the name of the attribute. The value can either be a string indicating the attribute’s type, or an object where you indicate the type (in the type field) together with a description (in the description field). See the table below for allowed types. Example of option one: { "attribute1" : "String", "attribute2": "Int" }. Example of option two: { "attribute1" : {"type": "String", "description": "Some description"}, "attribute2": "Int" } |
| associations | Object | The key of each entry is the name of the association, and the value should be an object describing the corresponding association. See Associations for details. |
| indices | [String] | Attributes for which to generate indices. By default, indices are generated for internalId; it is recommended to also add indices for attributes that are foreign keys. |
| operatorSet | String | Lets you specify the operator set for generic models, distributed adapters and Zendro servers. The following operator sets are supported: GenericPrestoSqlOperator, MongodbNeo4jOperator, CassandraOperator, AmazonS3Operator. See documentation of operators for details. |
| internalId | String | The name of the attribute that uniquely identifies a record. If this field is not specified, a default attribute named id will be added. |
| spaSearchOperator | ‘like’ | ‘iLike’ | Optional attribute to specify which operator the single-page-app text search field should use. Defaults to iLike. |
Supported Data Types
The following types are allowed for the attributes field:
| Type |
|---|
| String |
| Int |
| Float |
| Boolean |
| Date |
| Time |
| DateTime |
For more info about Date, Time, and DateTime types, please see this reference.
Examples:
- Date: a date string, such as
2007-12-03. - Time: a time string at UTC, such as
10:15:30Z. - DateTime: a date-time string at UTC, such as
2007-12-03T10:15:30Z.
Next steps
- Associations — connecting data models to each other.
- Resolver and model layers — what the code generator builds from this specification.