[Standardization] Standardized Schema Definition Template and Instructions

[TanmoySG]

From Open Question in conventions.md

• Need to figure out defining a standard for schema definition
• Might need to create a "custom" template to define the schema
• The Standard Schema Definition should also be interchangeable with JSON Schema or OpenAPI Spec
• Should support Code Generation (reqd. for Go, etc.)
• Require a Standard - a task that can be carried parallely with #6

[Checkpoints]

• [ ] Create a Schema Template for all Schema
• [ ] Should be interchangeable with JSONSchema (for Validation) and OAPI Spec(for Code Gen)
• [ ] Create Code Gen Helper
• [ ] Create JSONSchema-OPAISpec Interchange Script/Utility
• [ ] Modify Code (Schema Parser) to use standard Schema Template

[TanmoySG]

Ideas & Thoughts

• Schema Identifier to identify and differentiate between schemas.
  • the Kind parameter can be reused for this
  • Can also create an ID or SchemaID field for same
• A Codegen and Schema Validation friendly Schema should be the way to go
  • Look at the https://github.com/TanmoySG/w-service-manager/commit/86da03bd0d0e35d7a2fb71c818f3bdfb7256de9a#diff-c076f544545d159aee008738e94dc04c3b42e0c41ce14c33fcdc66d281cda559
  • This schema has been tested for both codegen and schema validation.
  • The Codegen, though is powered by the quicktype tool instead of OAPI Codegen, as we do not need to make any kind of special action before code generation like moving the schemas inside components and so on. Plus this gives a dependancy (on openapi codegen) free code generation as it mostly does the parsing
• Moving away from strictly JSON Schema as well as OAPI should help in getting the Codegen+Validation friendliness.
• Also all existing schemas should be moved to this "standard" schema at some point of time in the scope of this issue.
• A Boilerplate Schema Generator Shell script can help to generate an Initial schema which then can be changed as per requirement, making the schema standardized at creation.

[TanmoySG]

Broilerplate Generator Script

The following script asks for the Schema and Filepath and creates a Schema Boilerplate.

read -p "Schema Name (format: schema.namespace.parent-namespace): " SCHEMAID
read -p "Schema Filepath (format: path/to/schema.namespace.parent-namespace): " SCHEMAPATH

SCHEMAFULLPATH=$SCHEMAPATH/$SCHEMAID.schema.json

TEMPFILE=$(mktemp)

cat ./schema.template.json | jq 'del(.properties.complexField) | del(.required[1]) | .definitions={} | .' > $TEMPFILE
jq --arg SCHEMAID "${SCHEMAID}"  '.SchemaID=$SCHEMAID' < $TEMPFILE > $SCHEMAFULLPATH;

cat $SCHEMAFULLPATH > $TEMPFILE
jq --arg SCHEMAID "${SCHEMAID}"  '.properties.kind.default=$SCHEMAID | .properties.kind.enum[0]=$SCHEMAID' < $TEMPFILE > $SCHEMAFULLPATH

rm -rf $TEMPFILE

Usage

Run it using

sh prepareSchema.sh

Schema Name (format: schema.namespace.parent-namespace): test
Schema Filepath (format: path/to/schema.namespace.parent-namespace): ./

[TanmoySG]

Script to check if a Schema follows the Standard Schema Structure

• [ ] Schemas that aren't generated by the prepareSchema.sh script need to be checked for the standard structure. A script to do this should be helpful to maintain the standard.
• [ ] Also, a schema modifier script to suggest/modify changes to the schema in-case of any issues can also be helpful.