JsonPowerInspector.Template 0.0.2

Json Power Inspector for Typed Programming Language

Json Power Inspector is a JSON editor that offers advanced GUI editing experience based on the serialization information created from a typed language.

Using the application

1. Create a .jsontemplate file from your data structure.
2. Download and unzip the application to a place where you can remember.
3. Launch the application.
4. Drag and drop your .jsontemplate file to the application window.
5. Start editing.

Table of Contents

• Create a JsonTemplate file from your data structure
  • Documentation for JsonPowerInspector.Template Nuget Package Users
    • Usage
    • Supported features and restrictions
      • Example
  • Documentation for creating your serializer and jsontemplate file specification
    • Root JSON Object Format
    • ObjectDefiniton
    • PropertyInfo
      • StringPropertyInfo
      • NumberPropertyInfo
      • ObjectPropertyInfo
      • BooleanPropertyInfo
      • ArrayPropertyInfo
      • DictionaryPropertyInfo
      • EnumPropertyInfo
        • EnumValue
      • DropdownPropertyInfo

Create a JsonTemplate file from your data structure

Before using the application, developers must serialize their data structure into a dedicated .jsontemplate file that contains type information.

We provide a serializer Nuget package for C#/dotnet8 developers, so you are more than welcome to create your own version of the serializer for your language/environment.

Documentation for JsonPowerInspector.Template Nuget Package Users

Usage

• Install the JsonPowerInspector.Template Nuget package into the C# project that contains the data structure you wish to work with. For demonstration purposes, let's use this MyItem type as an example.

public struct MyItem
{
    public string Name { get; set; }
    public string Description { get; set; }
    public int Price { get; set; }
}

• Use the following line to serialize the model and save it into a jsontemplate file.

var definition = TemplateSerializer.CollectTypeDefinition<MyItem>();
var jsonTemplateString = TemplateSerializer.Serialize(definition);
File.WriteAllText("MyItem.jsontemplate", jsonTemplateString);

Supported features and restrictions

• The serializer collects type info for instance Properties that are publicly available and have both get and set accessors.
• The following types and features are supported by the serializer:

Type info ______________	Restrictions _________________________	Inspector type __________________________________	Customizable Display Name ___________________________________	Restrict the number range ______________________________	Dropdown support ___________________________	Nullable support __________________
T[] or List<T>	Nested types are displayed with their corresponding inspector	Array Inspector<br/><br/><br/>	Annotate the property with InspectorNameAttribute to customize the name shown in the editor header	Annotate the property with NumberRangeAttribute for the array element type, the type itself should be compatible with NumberRange.	Annotate the property with DropdownAttribute for the array element type, the type itself should be compatible with Dropdown	Not supported
Dictionary<TKey, TValue>	TKey only supports Numbers or Strings (.Net restrictions)	Dictionary Inspector<br/><br/><br/>	Annotate the property with InspectorNameAttribute to customize the name shown in the editor header	Annotate the property with KeyNumberRangeAttribute for TKey<br/> and use ValueNumberRangeAttribute for TValue, <br/>the annotated type should be a NumberRange compatible type.	Annotate the property with KeyDropdownAttribute for TKey<br/> and use ValueDropdownAttribute for TValue, <br/>the annotated type should be a Dropdown compatible type, the corresponding types gets	Not supported
bool	N/A	Boolean Inspector<br/><br/><br/>	Annotate the property with InspectorNameAttribute to customize the name shown in the editor name	Not supported	Not supported	Supported
Primitive number types byte, ushort, uint, ulong, sbyte, short, int, long, float, and double	Integer types only support inputting integral values, where Float types support inputting values with decimal	Number Inspector<br/><br/><br/>	Annotate the property with InspectorNameAttribute to customize the name shown in the editor name	Annotate the property with NumberRangeAttribute to customize the value range	Use DropdownAttribute to customize the dropdown data source and value resolver	Supported
string	N/A	String Inspector<br/><br/><br/>	Annotate the property with InspectorNameAttribute to customize the name shown in the editor name	Not supported	Annotate the property with DropdownAttribute to customize the dropdown data source and value resolver	Not supported
enum	N/A	Enum Inspector<br/><br/><br/><br/>or Enum Flags Inspector<br/><br/>	Annotate the property with InspectorNameAttribute to customize the name shown in the editor name, or annotate the enum values with InspectorNameAttribute to customize the names shown in the dropdown	Not supported	Not supported	Not supported
Other Non-Generic Types	Only publicly available instance Properties and have both get and set accessors are recorded.	Object Inspector<br/><br/><br/>	Annotate the property with InspectorNameAttribute to customize the name shown in the editor header	Not Supported	Not Supported	Not supported

Example

• The model used for serialization:

public class MyDemoModel
{
    /// <summary>
    /// Displayed as "Int Array" in inspector.
    /// Each array element has an input range clamps to -2 to 2.
    /// </summary>
    [InspectorName("Int Array"), NumberRange(-2, 2)] 
    public int[] MyIntArrayProperty { get; set; }
    
    /// <summary>
    /// Displayed as "Dictionary" in inspector.
    /// When adding a dictionary element,
    /// the input range for the key clamps to 0 to 10.
    /// </summary>
    [InspectorName("Dictionary"), KeyNumberRange(0, 10)] 
    public Dictionary<int, string> MyDictionaryProperty { get; set; }
    
    /// <summary>
    /// Displayed as "MyBool" in inspector.
    /// </summary>
    public bool MyBool { get; set; }
    
    /// <summary>
    /// Displayed as "Number Value" in inspector.
    /// Have an input range clamps to -10 to 10.
    /// </summary>
    [InspectorName("Number Value"), NumberRange(-10, 10)] 
    public float MyFloat { get; set; }
    
    /// <summary>
    /// Displayed as "Number Value" in inspector.
    /// Use a dropdown to select the values.
    /// </summary>
    [InspectorName("String Value"), Dropdown("StringSelection.tsv")] 
    public string MyString { get; set; }
    
    /// <summary>
    /// Displayed as "Time Type" in inspector.
    /// Use a dropdown to select the enum values.
    /// </summary>
    [InspectorName("Time Type")]
    public DateTimeKind MyDateTimeKind { get; set; }
    
    /// <summary>
    /// Displayed as "Nested Model" in inspector.
    /// </summary>
    [InspectorName("Nested Model")]
    public MyDemoModel Nested { get; set; }

    /// <summary>
    /// Displayed as nullable number in inspector
    /// </summary>
    [InspectorName("Nullable Number")]
    public int? NullableNumber { get; set; }    

    /// <summary>
    /// Displayed as nullable boolean in inspector
    /// </summary>
    [InspectorName("Nullable Boolean")]
    public bool? NullableBoolean { get; set; }
}

• The serialization code:

var definition = TemplateSerializer.CollectTypeDefinition<MyDemoModel>();
var jsonText = TemplateSerializer.Serialize(definition);
File.WriteAllText("MyDemoModel.jsontemplate", jsonText, Encoding.UTF8);

• And the content for StringSelection.tsv should be placed in the same directory as MyDemoModel.jsontemplate.

Value	Display
Lorem	String Value: Lorem
ipsum	String Value: ipsum
dolor	String Value: dolor
sit	String Value: sit
amet	String Value: amet
consectetur	String Value: consectetur
adipiscing	String Value: adipiscing
elit	String Value: elit

• Here is a screenshot of the inspector after loading the MyDemoModel.jsontemplate.

Documentation for creating your serializer and jsontemplate file specification

The serializer for your language should be capable of converting a developer-supplied data model type into a valid jsontemplate file; you may check the implementation in the JsonPowerInspector.Template package for a reference implementation.

The jsontemplate file itself is a valid JSON file that complies with the following format.

Root JSON Object Format

The inspector expects two key-value pairs in the JSON file:

{
  "MainObjectDefinition": {},
  "ReferencedObjectDefinition": []
}

ObjectDefiniton

The ObjectDefinition JSON type contains the name and information about every serialized property within a specific type; it contains two key-value pairs:

{
  "ObjectTypeName": string,
  "Properties": []
}

PropertyInfo

The PropertyInfo JSON type describes the type info for a serialized property; it comes with 8 variations, and these 8 variations share three key-value pairs:

{
  "PropertyType": string,
  "Name": string,
  "DisplayName": string
}

StringPropertyInfo

Describes a string property; the application offers a String Inspector for editing.

{
  // This value is a defined constant,
  // the JSON object must match the 
  // following structure when using "String"
  // as value for "PropertyType"
  "PropertyType": "String",
  "Name": string,
  "DisplayName": string
}

NumberPropertyInfo

Describes a number property, the application offers a Number Inspector for editing.

{
  // This value is a defined constant,
  // the JSON object must match the 
  // following structure when using "Number"
  // as value for "PropertyType"
  "PropertyType": "Number",
  "NumberKind": string,
  "Range": {
    "Lower": number,
    "Upper": number
  },
  "Nullable": bool,
  "Name": string,
  "DisplayName": string
}

ObjectPropertyInfo

Describes a nested type property, the application offers an Object Inspector for editing.

{
  // This value is a defined constant,
  // the JSON object must match the 
  // following structure when using "Object"
  // as value for "PropertyType"
  "PropertyType": "Object",
  "ObjectTypeName": string,
  "Name": string,
  "DisplayName": string
}

BooleanPropertyInfo

Describes a boolean property, the application offers a Boolean Inspector for editing.

{
  // This value is a defined constant,
  // the JSON object must match the 
  // following structure when using "Bool"
  // as value for "PropertyType"
  "PropertyType": "Bool",
  "Nullable": bool,
  "Name": string,
  "DisplayName": string
}

ArrayPropertyInfo

Describes an array property; the application offers an Array Inspector for editing.

{
  // This value is a defined constant,
  // the JSON object must match the 
  // following structure when using "Array"
  // as value for "PropertyType"
  "PropertyType": "Array",
  "ArrayElementTypeInfo": PropertyInfo,
  "Name": string,
  "DisplayName": string
}

DictionaryPropertyInfo

Describes a dictionary property, the application offers a Dictionary Inspector for editing.

{
  // This value is a defined constant,
  // the JSON object must match the 
  // following structure when using "Dictionary"
  // as value for "PropertyType"
  "PropertyType": "Dictionary",
  "KeyTypeInfo": PropertyInfo,
  "ValueTypeInfo": PropertyInfo,
  "Name": string,
  "DisplayName": string
}

EnumPropertyInfo

Describes an enum property, the application offers an Enum Inspector or Enum Flags Inspector for editing.

{
  // This value is a defined constant,
  // the JSON object must match the 
  // following structure when using "Enum"
  // as value for "PropertyType"
  "PropertyType": "Enum",
  "EnumTypeName": string,
  "EnumValues": [EnumValueInfo],
  "IsFlags": bool,
  "Name": string,
  "DisplayName": string
}

EnumValue

Describes the value of an enum property.

{
  "DisplayName": string,
  "DeclareName": string
  "Value": integer
}

DropdownPropertyInfo

Describes a property that uses a dropdown for selecting value; the application offers a Dropdown Inspector for editing.

{
  // This value is a defined constant,
  // the JSON object must match the 
  // following structure when using "Dropdown"
  // as value for "PropertyType"
  "PropertyType": "Dropdown",
  "Kind": string,
  "DataSourcePath": string,
  "ValueDisplayRegex": string,
  "DisplayName": string
  "Value": integer
}