Schema
Languages are typically classified into two: statically typed, where type type is explicitly specified before the execution of the program, and dynamically typed, where type is unknown until runtime. Codeflow, even though built on top of JavaScript, which is dynamically typed, however uses a JSON schema based type system to mark all the interfaces with type information, which brings the benefits of both static and dynamic type systems.
The schema specifies the structure and type of all the input/output interfaces of a flow, module and step during the design time. There are several benefits of using that approach:
-
Gradual typing Using a structured type definition like schema to mark its interfaces brings the benefits of a typed language, like better validation and auto completion hints, into a dynamic core that's built on top of JavaScript.
-
Self-documented Using the schema eliminates the need for documenting interfaces separately. The designer lets developers specify additional metadata like validation rules and descriptions for each field within itself, which are normally decoupled (and therefore often unsynced) from the main code in traditional programming languages.
-
Better reusability Using a standard, like the JSON schema, helps developers share and reuse commonly used data structures efficiently, even across the language boundary.
Schema editor in Codeflow designer being used to specify the schema for the end step of a flow.
Supported types
Below are the supported types in Codeflow (as derived from JSON Schema draft v3):
- string - A string.
- boolean - A boolean.
- integer - A number without a fraction or exponent part.
- number - Any number. Number includes integer.
- null - The null value.
- array - An array.
- object - An object.
- any - A special type that can be used as placeholder for all other, unknown types. (see below).
- $ref - To reference other schemas.
All the types map to their JavaScript equivalent internally. Codeflow might bring additional types on top of above to bring more language features into the platform.
The any type
The any type, adopted from the JSON schema specification(v3), is a special type that can hold any other type. It makes it easy to hold unknown types without a design time validation warning.
Note: The any type is being removed in JSON schema draft v4, and is replaced by composite type. Codeflow will retain the feature by creating a wrapper type making use of composite type.
Using $ref
The $ref keyword is used to reference other schemas. This lets developers structure a complex schema into several reusable parts that can be used in several places.
Editing schema
Because schema is an integral part of the language specification, the designer is built with a full-fledged support for building and editing JSON schemas visually. The below animation shows creating a schema in the designer:
Input/Output definition of flows
A special tab named schema is available under the configuration panel for the start and the end step to bind a schema, that becomes the input and output interface respectively of the flow.
The below image shows how invoking the flow looks like (note that the input fields reflects the structure and type specified in the load.flw's start step):
Input/Output definition of a module
The input/output interface of a module is also defined internally using the schema.
Schema files
Schemas can be also be saved as standalone files with .schema extension. This is useful for sharing schemas across multiple places. The editor is identical to the embedded editor under configuration panel, except that you can also view and edit as text file directly.
Benefits of Schema
Autocompletion & validation
The autocomplete feature in Codeflow designer makes use of the schema that defines the input/output interfaces of the connected modules and steps to show the drop down with data available for mapping. This is described in detail in the chapter input mapping.
Image showing an autocomplete drop down in the expression editor.
The richer validation capabilities of the schema also allow Codeflow to display intuitive warnings at the design time to catch mistakes early and perform complex validations, if required, at the runtime.
Image showing a design time validation warning inside the expression editor.
Reuse
A schema can reference other schemas. This is a neat way to share reusable schemas across multiple places without recreating it again and again.
JSON schema standard
Codeflow uses a subset of JSON schema draft v3, which is not the latest (latest being draft v4). As the requirements of a programming environment might go beyond the requirements of JSON standard, Codeflow might extend the spec to include few additional features in the future.