Skip to content

An advanced Json Inspector for typed language serializer, powered by Godot.

License

Notifications You must be signed in to change notification settings

Delsin-Yu/Json-Power-Inspector

Repository files navigation

Json Power Inspector for Typed Programming Language

GitHub Release Stars License

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

image

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

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

NuGet Version NuGet Downloads

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

image
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

image
Annotate the property with InspectorNameAttribute to customize the name shown in the editor header Annotate the property with KeyNumberRangeAttribute for TKey
and use ValueNumberRangeAttribute for TValue,
the annotated type should be a NumberRange compatible type.
Annotate the property with KeyDropdownAttribute for TKey
and use ValueDropdownAttribute for TValue,
the annotated type should be a Dropdown compatible type, the corresponding types gets
Not supported
bool N/A Boolean Inspector

image
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

image
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

image
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

image

or Enum Flags Inspector

image
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

image
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": []
}
Key Definition
MainObjectDefinition An ObjectDefiniton JSON type that describes the properties within the inspected type.
ReferencedObjectDefinition An array of ObjectDefinition that describes other types referenced by the inspected type.

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": []
}
Key Definition
ObjectTypeName The name for the type should be used consistently when referring to this type.
Properties An array of PropertyInfo that contains type information for each serialized property within this type.

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
}
Key Definition
PropertyType The property type, should be one of the 8 values with matching content: String, Number, Object, Bool, Array, Dictionary, Enum, or Dropdown.
Name This name should match the value name stored in the JSON file.
DisplayName The text displayed in the inspector.
StringPropertyInfo
Describes a string property; the application offers a String Inspector for editing. image
{
  // 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. image
{
  // 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
}
Key Definition
NumberKind This value can only be Int or Float; the application uses this value to determine if float-point editing should be enabled for the user.
Range Can be null, this value defines the lower and the upper bound for the value, note that the Lower should be lesser than Upper, and both value should be integer if the NumberKind is Int.
Nullable If set to true, an additional button will be available to user to switch this value between number and null.
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
}
Key Definition
ObjectTypeName The type name should be consistent with the ObjectTypeName in the ObjectDefiniton.
BooleanPropertyInfo
Describes a boolean property, the application offers a Boolean Inspector for editing. image
{
  // 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
}
Key Definition
Nullable If set to true, an additional button will be available to user to switch this value between number and null.
ArrayPropertyInfo
Describes an array property; the application offers an Array Inspector for editing. image
{
  // 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
}
Key Definition
ArrayElementTypeInfo This value can only be one of the 8 variations of PropertyInfo with matching content: String, Number, Object, Bool, Array, Dictionary, Enum, or Dropdown.
DictionaryPropertyInfo
Describes a dictionary property, the application offers a Dictionary Inspector for editing. image
{
  // 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
}
Key Definition
KeyTypeInfo This value can only be one of the 2 variations of PropertyInfo with matching content: String or Number.
ValueTypeInfo This value can only be one of the 8 variations of PropertyInfo with matching content: String, Number, Object, Bool, Array, Dictionary, Enum, or Dropdown.
EnumPropertyInfo
Describes an enum property, the application offers an Enum Inspector or Enum Flags Inspector for editing. image image
{
  // 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
}
Key Definition
EnumTypeName The name for this enum type.
EnumValues The values this enum type contains, the type for this JSON object should be the EnumValue.
IsFlags Marks whether Enum utilizes Bitfield to represent flags.
EnumValue

Describes the value of an enum property.

{
  "DisplayName": string,
  "DeclareName": string
  "Value": integer
}
Key Definition
DisplayName The text displayed in the inspector.
DeclareName The name stored in the JSON file.
Value The underlying value for this enum value.
DropdownPropertyInfo
Describes a property that uses a dropdown for selecting value; the application offers a Dropdown Inspector for editing. image
{
  // 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
}
Key Definition
Kind This value can only be Int, Float, or String.
DataSourcePath The path to the file that contains the datasets of this dropdown, relative to the jsontemplate file.
ValueDisplayRegex The Regex expression inspector uses when resolving each line (after the first line) into a data-name pair that populates the dropdown items.

About

An advanced Json Inspector for typed language serializer, powered by Godot.

Resources

License

Stars

Watchers

Forks

Packages

No packages published