Vocabulary Design Best Practices

  • 2 minute(s) read

Follow best practices when designing Vocabularies.

Best Practices in Vocabulary Design

Consider the following guidelines and best practices when designing Vocabularies:

  • Upload your JSON schema or design in ProcessMaker Platform: You may design your JSON schema before you create your Vocabulary or design it in ProcessMaker Platform. ProcessMaker Platform provides a graphical interface in the Visual tab of a Vocabulary that non-developers may find easier to design a Vocabulary. This may be helpful if you are not familiar with coding a JSON schema but understand the design compliance your ProcessMaker Platform assets must meet. If you are familiar with designing JSON schemas, you may code your JSON schema in the Code tab. Changes made in one tab reflect in the other tab.

  • Vocabularies designed in ProcessMaker Platform are named mainSchema: If you design Vocabularies in ProcessMaker Platform instead of uploading one when a Vocabulary is created, the root name of the Vocabulary is mainSchema. mainSchema represents the top of the JSON schema object and contains the properties of that Vocabulary. If you upload your own JSON schema, its root name remains unchanged. JSON schema root names must begin with a letter, followed by any number of letters, integers (0 through 9]), hyphens (-), underscores (_), colons (:), or periods (.).

  • Design your Vocabularies modularly: As a best practice, design your Vocabularies as segmented, minimal pieces rather than large encompassing JSON schemas. Small, modular Vocabularies can be re-used across multiple ProcessMaker Platform assets for a variety of Processes and business solutions. More specifically, Vocabularies can inherit their properties from other Vocabularies to build on one another, yet extend from those inherited Vocabularies.

    For example, a Purchase Request Process may require billing information as well as shipping information. These groups of information may be designed in segmented, separate Screens modularly and then incorporated into a third Screen that uses Nested Screen controls to incorporate these segmented Screens for easier re-use and maintenance. Likewise, each of these Screens may use its own Vocabulary to validate required and conforming information for each. As a different design approach for this example, the Vocabulary that validates the shipping information may inherit the Vocabulary for the billing information, thereby referencing its JSON schema properties for easier maintenance; while referencing the Vocabulary for billing information, the Vocabulary for shipping information contains its own properties for validation and compliance.

  • Define properties in your Vocabularies in the order as intended: If you design your Vocabulary in the Visual tab, define its properties in the order from top to bottom as intended. Properties cannot be sorted in a different order than how you create them. However, you may view your Vocabulary in the Code tab, which displays the JSON schema as code, and then reorganize properties there.

  • Ensure the maximum length of each property is not 0 or a negative number: Except for the root of the JSON schema, such as mainSchema, each property in a JSON schema and Vocabulary must have a length that validates how many digits, whether alphabetical, numeric, or alphanumeric, that validates conformity of data for that property. ProcessMaker Platform stores a property's length using the maxLength key name by default to define the maximum number of digits that property's value may contain. For example, a person's age may contain no more than three (3) digits. Ensure that each property contains at least one (1) digit. To specify a minimum digit length of a property, select the Code tab and enter that minimum length using the minLength key name. To specify an exact number of digits, use minLength key name. For example, a credit card number must contain 16 digits.